comparison vamp-sdk/hostext/PluginLoader.h @ 64:9d3272c7db60

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