annotate vamp-sdk/hostext/PluginLoader.h @ 69:3456fe86d385

* Switch PluginLoader to an m_impl structure to make it generally nicer
author cannam
date Wed, 06 Jun 2007 09:49:50 +0000
parents 9d3272c7db60
children 64697dca0d48
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@64 9 Copyright 2006 Chris Cannam.
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@64 62 * But it's recommended, for sound practical reasons.
cannam@64 63 */
cannam@64 64
cannam@64 65 class PluginLoader
cannam@64 66 {
cannam@64 67 public:
cannam@64 68 /**
cannam@64 69 * PluginLoader is a singleton class. This function returns a
cannam@64 70 * pointer to the single instance of it. Use this to obtain your
cannam@64 71 * loader object.
cannam@64 72 */
cannam@64 73 static PluginLoader *getInstance();
cannam@64 74
cannam@64 75 /**
cannam@64 76 * PluginKey is a string type that is used to identify a plugin
cannam@64 77 * uniquely within the scope of "the current system". It consists
cannam@64 78 * of the base name of the plugin library, a colon separator, and
cannam@64 79 * the identifier string for the plugin. It is only meaningful in
cannam@64 80 * the context of a given plugin path (the one returned by
cannam@64 81 * PluginHostAdapter::getPluginPath()).
cannam@64 82 *
cannam@64 83 * Use composePluginKey to construct a plugin key from a known
cannam@64 84 * plugin library name and identifier.
cannam@64 85 */
cannam@64 86 typedef std::string PluginKey;
cannam@64 87
cannam@64 88 /**
cannam@64 89 * PluginKeyList is a sequence of plugin keys, such as returned by
cannam@64 90 * a plugin lookup function.
cannam@64 91 */
cannam@64 92 typedef std::vector<PluginKey> PluginKeyList;
cannam@64 93
cannam@64 94 /**
cannam@64 95 * PluginCategoryHierarchy is a sequence of general->specific
cannam@64 96 * category names, as may be associated with a single plugin.
cannam@64 97 * This sequence describes the location of a plugin within a
cannam@64 98 * category forest, containing the human-readable names of the
cannam@64 99 * plugin's category tree root, followed by each of the nodes down
cannam@64 100 * to the leaf containing the plugin.
cannam@64 101 */
cannam@64 102 typedef std::vector<std::string> PluginCategoryHierarchy;
cannam@64 103
cannam@64 104 /**
cannam@64 105 * Search for all available Vamp plugins, and return a list of
cannam@64 106 * them in the order in which they were found.
cannam@64 107 */
cannam@64 108 PluginKeyList listPlugins();
cannam@64 109
cannam@64 110 /**
cannam@64 111 * AdapterFlags contains a set of values that may be OR'd together
cannam@64 112 * to indicate in which circumstances PluginLoader should use a
cannam@64 113 * plugin adapter to make a plugin easier to use for a host that
cannam@64 114 * does not want to cater for complex features.
cannam@64 115 *
cannam@64 116 * The available flags are:
cannam@64 117 *
cannam@64 118 * ADAPT_INPUT_DOMAIN - If the plugin expects frequency domain
cannam@64 119 * input, wrap it in a PluginInputDomainAdapter that automatically
cannam@64 120 * converts the plugin to one that expects time-domain input.
cannam@64 121 * This enables a host to accommodate time- and frequency-domain
cannam@64 122 * plugins without needing to do any conversion itself.
cannam@64 123 *
cannam@64 124 * ADAPT_CHANNEL_COUNT - Wrap the plugin in a PluginChannelAdapter
cannam@64 125 * to handle any mismatch between the number of channels of audio
cannam@64 126 * the plugin can handle and the number available in the host.
cannam@64 127 * This enables a host to use plugins that may require the input
cannam@64 128 * to be mixed down to mono, etc., without having to worry about
cannam@64 129 * doing that itself.
cannam@64 130 *
cannam@64 131 * See PluginInputDomainAdapter and PluginChannelAdapter for more
cannam@64 132 * details of the classes that the loader may use if these flags
cannam@64 133 * are set.
cannam@64 134 */
cannam@64 135 enum AdapterFlags {
cannam@64 136 ADAPT_INPUT_DOMAIN = 0x01,
cannam@64 137 ADAPT_CHANNEL_COUNT = 0x02,
cannam@64 138 ADAPT_ALL = 0xff
cannam@64 139 };
cannam@64 140
cannam@64 141 /**
cannam@64 142 * Load a Vamp plugin, given its identifying key. If the plugin
cannam@64 143 * could not be loaded, returns 0.
cannam@64 144 *
cannam@64 145 * adapterFlags is a bitwise OR of the values in the AdapterFlags
cannam@64 146 * enum, indicating under which circumstances an adapter should be
cannam@64 147 * used to wrap the original plugin. See AdapterFlags for more
cannam@64 148 * details. If adapterFlags is 0, no optional adapters will be
cannam@64 149 * used.
cannam@64 150 *
cannam@64 151 * The returned plugin should be deleted (using the standard C++
cannam@64 152 * delete) after use.
cannam@64 153 */
cannam@64 154 Plugin *loadPlugin(PluginKey key,
cannam@64 155 float inputSampleRate,
cannam@64 156 int adapterFlags = 0);
cannam@64 157
cannam@64 158 /**
cannam@64 159 * Given a Vamp plugin library name and plugin identifier, return
cannam@64 160 * the corresponding plugin key in a form suitable for passing in to
cannam@64 161 * loadPlugin.
cannam@64 162 */
cannam@64 163 PluginKey composePluginKey(std::string libraryName,
cannam@64 164 std::string identifier);
cannam@64 165
cannam@64 166 /**
cannam@64 167 * Return the category hierarchy for a Vamp plugin, given its
cannam@64 168 * identifying key. See PluginCategoryHierarchy documentation for
cannam@64 169 * more details.
cannam@64 170 *
cannam@64 171 * If the plugin has no category information, return an empty
cannam@64 172 * hierarchy.
cannam@64 173 */
cannam@64 174 PluginCategoryHierarchy getPluginCategory(PluginKey plugin);
cannam@64 175
cannam@64 176 /**
cannam@64 177 * Return the file path of the dynamic library from which the
cannam@64 178 * given plugin will be loaded (if available).
cannam@64 179 */
cannam@64 180 std::string getLibraryPathForPlugin(PluginKey plugin);
cannam@64 181
cannam@64 182 protected:
cannam@64 183 PluginLoader();
cannam@64 184 virtual ~PluginLoader();
cannam@64 185
cannam@69 186 class Impl;
cannam@69 187 Impl *m_impl;
cannam@64 188
cannam@64 189 static PluginLoader *m_instance;
cannam@64 190 };
cannam@64 191
cannam@64 192 }
cannam@64 193
cannam@64 194 }
cannam@64 195
cannam@64 196 #endif
cannam@64 197