annotate vamp-sdk/hostext/PluginLoader.h @ 75:0f8524203677

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