annotate vamp-hostsdk/PluginLoader.h @ 307:ebc47e614cf5

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