annotate osx/include/vamp-hostsdk/PluginLoader.h @ 116:e448888319fc

PortAudio on OS/X
author Chris Cannam <cannam@all-day-breakfast.com>
date Thu, 09 Jan 2014 21:33:28 +0000
parents 1e14aae10620
children
rev   line source
cannam@112 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
cannam@112 2
cannam@112 3 /*
cannam@112 4 Vamp
cannam@112 5
cannam@112 6 An API for audio analysis and feature extraction plugins.
cannam@112 7
cannam@112 8 Centre for Digital Music, Queen Mary, University of London.
cannam@112 9 Copyright 2006-2009 Chris Cannam and QMUL.
cannam@112 10
cannam@112 11 Permission is hereby granted, free of charge, to any person
cannam@112 12 obtaining a copy of this software and associated documentation
cannam@112 13 files (the "Software"), to deal in the Software without
cannam@112 14 restriction, including without limitation the rights to use, copy,
cannam@112 15 modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@112 16 of the Software, and to permit persons to whom the Software is
cannam@112 17 furnished to do so, subject to the following conditions:
cannam@112 18
cannam@112 19 The above copyright notice and this permission notice shall be
cannam@112 20 included in all copies or substantial portions of the Software.
cannam@112 21
cannam@112 22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@112 23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@112 24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@112 25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
cannam@112 26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@112 27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@112 28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@112 29
cannam@112 30 Except as contained in this notice, the names of the Centre for
cannam@112 31 Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@112 32 shall not be used in advertising or otherwise to promote the sale,
cannam@112 33 use or other dealings in this Software without prior written
cannam@112 34 authorization.
cannam@112 35 */
cannam@112 36
cannam@112 37 #ifndef _VAMP_PLUGIN_LOADER_H_
cannam@112 38 #define _VAMP_PLUGIN_LOADER_H_
cannam@112 39
cannam@112 40 #include <vector>
cannam@112 41 #include <string>
cannam@112 42 #include <map>
cannam@112 43
cannam@112 44 #include "hostguard.h"
cannam@112 45 #include "PluginWrapper.h"
cannam@112 46
cannam@112 47 _VAMP_SDK_HOSTSPACE_BEGIN(PluginLoader.h)
cannam@112 48
cannam@112 49 namespace Vamp {
cannam@112 50
cannam@112 51 class Plugin;
cannam@112 52
cannam@112 53 namespace HostExt {
cannam@112 54
cannam@112 55 /**
cannam@112 56 * \class PluginLoader PluginLoader.h <vamp-hostsdk/PluginLoader.h>
cannam@112 57 *
cannam@112 58 * Vamp::HostExt::PluginLoader is a convenience class for discovering
cannam@112 59 * and loading Vamp plugins using the typical plugin-path, library
cannam@112 60 * naming, and categorisation conventions described in the Vamp SDK
cannam@112 61 * documentation. This class is intended to greatly simplify the task
cannam@112 62 * of becoming a Vamp plugin host for any C++ application.
cannam@112 63 *
cannam@112 64 * Hosts are not required by the Vamp specification to use the same
cannam@112 65 * plugin search path and naming conventions as implemented by this
cannam@112 66 * class, and are certainly not required to use this actual class.
cannam@112 67 * But we do strongly recommend it.
cannam@112 68 *
cannam@112 69 * \note This class was introduced in version 1.1 of the Vamp plugin SDK.
cannam@112 70 */
cannam@112 71
cannam@112 72 class PluginLoader
cannam@112 73 {
cannam@112 74 public:
cannam@112 75 /**
cannam@112 76 * Obtain a pointer to the singleton instance of PluginLoader.
cannam@112 77 * Use this to obtain your loader object.
cannam@112 78 */
cannam@112 79 static PluginLoader *getInstance();
cannam@112 80
cannam@112 81 /**
cannam@112 82 * PluginKey is a string type that is used to identify a plugin
cannam@112 83 * uniquely within the scope of "the current system". It consists
cannam@112 84 * of the lower-cased base name of the plugin library, a colon
cannam@112 85 * separator, and the identifier string for the plugin. It is
cannam@112 86 * only meaningful in the context of a given plugin path (the one
cannam@112 87 * returned by PluginHostAdapter::getPluginPath()).
cannam@112 88 *
cannam@112 89 * Use composePluginKey() to construct a plugin key from a known
cannam@112 90 * plugin library name and identifier.
cannam@112 91 *
cannam@112 92 * Note: the fact that the library component of the key is
cannam@112 93 * lower-cased implies that library names are matched
cannam@112 94 * case-insensitively by the PluginLoader class, regardless of the
cannam@112 95 * case sensitivity of the underlying filesystem. (Plugin
cannam@112 96 * identifiers _are_ case sensitive, however.) Also, it is not
cannam@112 97 * possible to portably extract a working library name from a
cannam@112 98 * plugin key, as the result may fail on case-sensitive
cannam@112 99 * filesystems. Use getLibraryPathForPlugin() instead.
cannam@112 100 */
cannam@112 101 typedef std::string PluginKey;
cannam@112 102
cannam@112 103 /**
cannam@112 104 * PluginKeyList is a sequence of plugin keys, such as returned by
cannam@112 105 * listPlugins().
cannam@112 106 */
cannam@112 107 typedef std::vector<PluginKey> PluginKeyList;
cannam@112 108
cannam@112 109 /**
cannam@112 110 * PluginCategoryHierarchy is a sequence of general->specific
cannam@112 111 * category names, as may be associated with a single plugin.
cannam@112 112 * This sequence describes the location of a plugin within a
cannam@112 113 * category forest, containing the human-readable names of the
cannam@112 114 * plugin's category tree root, followed by each of the nodes down
cannam@112 115 * to the leaf containing the plugin.
cannam@112 116 *
cannam@112 117 * \see getPluginCategory()
cannam@112 118 */
cannam@112 119 typedef std::vector<std::string> PluginCategoryHierarchy;
cannam@112 120
cannam@112 121 /**
cannam@112 122 * Search for all available Vamp plugins, and return a list of
cannam@112 123 * them in the order in which they were found.
cannam@112 124 */
cannam@112 125 PluginKeyList listPlugins();
cannam@112 126
cannam@112 127 /**
cannam@112 128 * AdapterFlags contains a set of values that may be OR'd together
cannam@112 129 * to indicate in which circumstances PluginLoader should use a
cannam@112 130 * plugin adapter to make a plugin easier to use for a host that
cannam@112 131 * does not want to cater for complex features.
cannam@112 132 *
cannam@112 133 * The available flags are:
cannam@112 134 *
cannam@112 135 * ADAPT_INPUT_DOMAIN - If the plugin expects frequency domain
cannam@112 136 * input, wrap it in a PluginInputDomainAdapter that automatically
cannam@112 137 * converts the plugin to one that expects time-domain input.
cannam@112 138 * This enables a host to accommodate time- and frequency-domain
cannam@112 139 * plugins without needing to do any conversion itself.
cannam@112 140 *
cannam@112 141 * ADAPT_CHANNEL_COUNT - Wrap the plugin in a PluginChannelAdapter
cannam@112 142 * to handle any mismatch between the number of channels of audio
cannam@112 143 * the plugin can handle and the number available in the host.
cannam@112 144 * This enables a host to use plugins that may require the input
cannam@112 145 * to be mixed down to mono, etc., without having to worry about
cannam@112 146 * doing that itself.
cannam@112 147 *
cannam@112 148 * ADAPT_BUFFER_SIZE - Wrap the plugin in a PluginBufferingAdapter
cannam@112 149 * permitting the host to provide audio input using any block
cannam@112 150 * size, with no overlap, regardless of the plugin's preferred
cannam@112 151 * block size (suitable for hosts that read from non-seekable
cannam@112 152 * streaming media, for example). This adapter introduces some
cannam@112 153 * run-time overhead and also changes the semantics of the plugin
cannam@112 154 * slightly (see the PluginBufferingAdapter header documentation
cannam@112 155 * for details).
cannam@112 156 *
cannam@112 157 * ADAPT_ALL_SAFE - Perform all available adaptations that are
cannam@112 158 * meaningful for the plugin and "safe". Currently this means to
cannam@112 159 * ADAPT_INPUT_DOMAIN if the plugin wants FrequencyDomain input;
cannam@112 160 * ADAPT_CHANNEL_COUNT always; and ADAPT_BUFFER_SIZE never.
cannam@112 161 *
cannam@112 162 * ADAPT_ALL - Perform all available adaptations that are
cannam@112 163 * meaningful for the plugin.
cannam@112 164 *
cannam@112 165 * See PluginInputDomainAdapter, PluginChannelAdapter and
cannam@112 166 * PluginBufferingAdapter for more details of the classes that the
cannam@112 167 * loader may use if these flags are set.
cannam@112 168 */
cannam@112 169 enum AdapterFlags {
cannam@112 170
cannam@112 171 ADAPT_INPUT_DOMAIN = 0x01,
cannam@112 172 ADAPT_CHANNEL_COUNT = 0x02,
cannam@112 173 ADAPT_BUFFER_SIZE = 0x04,
cannam@112 174
cannam@112 175 ADAPT_ALL_SAFE = 0x03,
cannam@112 176
cannam@112 177 ADAPT_ALL = 0xff
cannam@112 178 };
cannam@112 179
cannam@112 180 /**
cannam@112 181 * Load a Vamp plugin, given its identifying key. If the plugin
cannam@112 182 * could not be loaded, returns 0.
cannam@112 183 *
cannam@112 184 * The returned plugin should be deleted (using the standard C++
cannam@112 185 * delete keyword) after use.
cannam@112 186 *
cannam@112 187 * \param adapterFlags a bitwise OR of the values in the AdapterFlags
cannam@112 188 * enumeration, indicating under which circumstances an adapter should be
cannam@112 189 * used to wrap the original plugin. If adapterFlags is 0, no
cannam@112 190 * optional adapters will be used. Otherwise, the returned plugin
cannam@112 191 * may be of an adapter class type which will behave identically
cannam@112 192 * to the original plugin, apart from any particular features
cannam@112 193 * implemented by the adapter itself.
cannam@112 194 *
cannam@112 195 * \see AdapterFlags, PluginInputDomainAdapter, PluginChannelAdapter
cannam@112 196 */
cannam@112 197 Plugin *loadPlugin(PluginKey key,
cannam@112 198 float inputSampleRate,
cannam@112 199 int adapterFlags = 0);
cannam@112 200
cannam@112 201 /**
cannam@112 202 * Given a Vamp plugin library name and plugin identifier, return
cannam@112 203 * the corresponding plugin key in a form suitable for passing in to
cannam@112 204 * loadPlugin().
cannam@112 205 */
cannam@112 206 PluginKey composePluginKey(std::string libraryName,
cannam@112 207 std::string identifier);
cannam@112 208
cannam@112 209 /**
cannam@112 210 * Return the category hierarchy for a Vamp plugin, given its
cannam@112 211 * identifying key.
cannam@112 212 *
cannam@112 213 * If the plugin has no category information, return an empty
cannam@112 214 * hierarchy.
cannam@112 215 *
cannam@112 216 * \see PluginCategoryHierarchy
cannam@112 217 */
cannam@112 218 PluginCategoryHierarchy getPluginCategory(PluginKey plugin);
cannam@112 219
cannam@112 220 /**
cannam@112 221 * Return the file path of the dynamic library from which the
cannam@112 222 * given plugin will be loaded (if available).
cannam@112 223 */
cannam@112 224 std::string getLibraryPathForPlugin(PluginKey plugin);
cannam@112 225
cannam@112 226 protected:
cannam@112 227 PluginLoader();
cannam@112 228 virtual ~PluginLoader();
cannam@112 229
cannam@112 230 class Impl;
cannam@112 231 Impl *m_impl;
cannam@112 232
cannam@112 233 static PluginLoader *m_instance;
cannam@112 234 };
cannam@112 235
cannam@112 236 }
cannam@112 237
cannam@112 238 }
cannam@112 239
cannam@112 240 _VAMP_SDK_HOSTSPACE_END(PluginLoader.h)
cannam@112 241
cannam@112 242 #endif
cannam@112 243