cannam@64: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
cannam@64: 
cannam@64: /*
cannam@64:     Vamp
cannam@64: 
cannam@64:     An API for audio analysis and feature extraction plugins.
cannam@64: 
cannam@64:     Centre for Digital Music, Queen Mary, University of London.
cannam@71:     Copyright 2006-2007 Chris Cannam and QMUL.
cannam@64:   
cannam@64:     Permission is hereby granted, free of charge, to any person
cannam@64:     obtaining a copy of this software and associated documentation
cannam@64:     files (the "Software"), to deal in the Software without
cannam@64:     restriction, including without limitation the rights to use, copy,
cannam@64:     modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@64:     of the Software, and to permit persons to whom the Software is
cannam@64:     furnished to do so, subject to the following conditions:
cannam@64: 
cannam@64:     The above copyright notice and this permission notice shall be
cannam@64:     included in all copies or substantial portions of the Software.
cannam@64: 
cannam@64:     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@64:     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@64:     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@64:     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
cannam@64:     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@64:     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@64:     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@64: 
cannam@64:     Except as contained in this notice, the names of the Centre for
cannam@64:     Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@64:     shall not be used in advertising or otherwise to promote the sale,
cannam@64:     use or other dealings in this Software without prior written
cannam@64:     authorization.
cannam@64: */
cannam@64: 
cannam@64: #ifndef _VAMP_PLUGIN_LOADER_H_
cannam@64: #define _VAMP_PLUGIN_LOADER_H_
cannam@64: 
cannam@64: #include <vector>
cannam@64: #include <string>
cannam@64: #include <map>
cannam@64: 
cannam@64: #include "PluginWrapper.h"
cannam@64: 
cannam@64: namespace Vamp {
cannam@64: 
cannam@64: class Plugin;
cannam@64: 
cannam@64: namespace HostExt {
cannam@64: 
cannam@64: /**
cannam@64:  * Vamp::HostExt::PluginLoader is a convenience class for discovering
cannam@64:  * and loading Vamp plugins using the typical plugin-path, library
cannam@64:  * naming, and categorisation conventions described in the Vamp SDK
cannam@64:  * documentation.  This class is intended to greatly simplify the task
cannam@64:  * of becoming a Vamp plugin host for any C++ application.
cannam@64:  * 
cannam@64:  * Hosts are not required by the Vamp specification to use the same
cannam@64:  * plugin search path and naming conventions as implemented by this
cannam@64:  * class, and are certainly not required to use this actual class.
cannam@64:  * But it's recommended, for sound practical reasons.
cannam@64:  */
cannam@64: 
cannam@64: class PluginLoader
cannam@64: {
cannam@64: public:
cannam@64:     /**
cannam@64:      * PluginLoader is a singleton class.  This function returns a
cannam@64:      * pointer to the single instance of it.  Use this to obtain your
cannam@64:      * loader object.
cannam@64:      */
cannam@64:     static PluginLoader *getInstance();
cannam@64: 
cannam@64:     /**
cannam@64:      * PluginKey is a string type that is used to identify a plugin
cannam@64:      * uniquely within the scope of "the current system".  It consists
cannam@73:      * of the lower-cased base name of the plugin library, a colon
cannam@73:      * separator, and the identifier string for the plugin.  It is
cannam@73:      * only meaningful in the context of a given plugin path (the one
cannam@73:      * returned by PluginHostAdapter::getPluginPath()).
cannam@64:      *
cannam@64:      * Use composePluginKey to construct a plugin key from a known
cannam@64:      * plugin library name and identifier.
cannam@73:      *
cannam@73:      * Note: the fact that the library component of the key is
cannam@73:      * lower-cased implies that library names are matched
cannam@73:      * case-insensitively by the PluginLoader class, regardless of the
cannam@73:      * case sensitivity of the underlying filesystem.  (Plugin
cannam@73:      * identifiers _are_ case sensitive, however.)  Also, it is not
cannam@73:      * possible to portably extract a working library name from a
cannam@73:      * plugin key, as the result may fail on case-sensitive
cannam@73:      * filesystems.  Use getLibraryPathForPlugin instead.
cannam@64:      */
cannam@64:     typedef std::string PluginKey;
cannam@64: 
cannam@64:     /**
cannam@64:      * PluginKeyList is a sequence of plugin keys, such as returned by
cannam@64:      * a plugin lookup function.
cannam@64:      */
cannam@64:     typedef std::vector<PluginKey> PluginKeyList;
cannam@64: 
cannam@64:     /**
cannam@64:      * PluginCategoryHierarchy is a sequence of general->specific
cannam@64:      * category names, as may be associated with a single plugin.
cannam@64:      * This sequence describes the location of a plugin within a
cannam@64:      * category forest, containing the human-readable names of the
cannam@64:      * plugin's category tree root, followed by each of the nodes down
cannam@64:      * to the leaf containing the plugin.
cannam@64:      */
cannam@64:     typedef std::vector<std::string> PluginCategoryHierarchy;
cannam@64: 
cannam@64:     /**
cannam@64:      * Search for all available Vamp plugins, and return a list of
cannam@64:      * them in the order in which they were found.
cannam@64:      */
cannam@64:     PluginKeyList listPlugins();
cannam@64: 
cannam@64:     /**
cannam@64:      * AdapterFlags contains a set of values that may be OR'd together
cannam@64:      * to indicate in which circumstances PluginLoader should use a
cannam@64:      * plugin adapter to make a plugin easier to use for a host that
cannam@64:      * does not want to cater for complex features.
cannam@64:      *
cannam@64:      * The available flags are:
cannam@64:      * 
cannam@64:      * ADAPT_INPUT_DOMAIN - If the plugin expects frequency domain
cannam@64:      * input, wrap it in a PluginInputDomainAdapter that automatically
cannam@64:      * converts the plugin to one that expects time-domain input.
cannam@64:      * This enables a host to accommodate time- and frequency-domain
cannam@64:      * plugins without needing to do any conversion itself.
cannam@64:      *
cannam@64:      * ADAPT_CHANNEL_COUNT - Wrap the plugin in a PluginChannelAdapter
cannam@64:      * to handle any mismatch between the number of channels of audio
cannam@64:      * the plugin can handle and the number available in the host.
cannam@64:      * This enables a host to use plugins that may require the input
cannam@64:      * to be mixed down to mono, etc., without having to worry about
cannam@64:      * doing that itself.
cannam@64:      * 
cannam@64:      * See PluginInputDomainAdapter and PluginChannelAdapter for more
cannam@64:      * details of the classes that the loader may use if these flags
cannam@64:      * are set.
cannam@64:      */
cannam@64:     enum AdapterFlags {
cannam@64:         ADAPT_INPUT_DOMAIN  = 0x01,
cannam@64:         ADAPT_CHANNEL_COUNT = 0x02,
cannam@64:         ADAPT_ALL           = 0xff
cannam@64:     };
cannam@64: 
cannam@64:     /**
cannam@64:      * Load a Vamp plugin, given its identifying key.  If the plugin
cannam@64:      * could not be loaded, returns 0.
cannam@64:      *
cannam@64:      * adapterFlags is a bitwise OR of the values in the AdapterFlags
cannam@64:      * enum, indicating under which circumstances an adapter should be
cannam@64:      * used to wrap the original plugin.  See AdapterFlags for more
cannam@64:      * details.  If adapterFlags is 0, no optional adapters will be
cannam@64:      * used.
cannam@64:      *
cannam@64:      * The returned plugin should be deleted (using the standard C++
cannam@64:      * delete) after use.
cannam@64:      */
cannam@64:     Plugin *loadPlugin(PluginKey key,
cannam@64:                        float inputSampleRate,
cannam@64:                        int adapterFlags = 0);
cannam@64: 
cannam@64:     /**
cannam@64:      * Given a Vamp plugin library name and plugin identifier, return
cannam@64:      * the corresponding plugin key in a form suitable for passing in to
cannam@64:      * loadPlugin.
cannam@64:      */
cannam@64:     PluginKey composePluginKey(std::string libraryName,
cannam@64:                                std::string identifier);
cannam@64: 
cannam@64:     /**
cannam@64:      * Return the category hierarchy for a Vamp plugin, given its
cannam@64:      * identifying key.  See PluginCategoryHierarchy documentation for
cannam@64:      * more details.
cannam@64:      *
cannam@64:      * If the plugin has no category information, return an empty
cannam@64:      * hierarchy.
cannam@64:      */
cannam@64:     PluginCategoryHierarchy getPluginCategory(PluginKey plugin);
cannam@64: 
cannam@64:     /**
cannam@64:      * Return the file path of the dynamic library from which the
cannam@64:      * given plugin will be loaded (if available).
cannam@64:      */
cannam@64:     std::string getLibraryPathForPlugin(PluginKey plugin);
cannam@64: 
cannam@64: protected:
cannam@64:     PluginLoader();
cannam@64:     virtual ~PluginLoader();
cannam@64: 
cannam@69:     class Impl;
cannam@69:     Impl *m_impl;
cannam@64: 
cannam@64:     static PluginLoader *m_instance;
cannam@64: };
cannam@64: 
cannam@64: }
cannam@64: 
cannam@64: }
cannam@64: 
cannam@64: #endif
cannam@64: