changeset 62:fe5486ee1c70 host-factory-stuff

* Documentation

--- a/README	Fri Jun 01 13:53:42 2007 +0000
+++ b/README	Fri Jun 01 15:00:51 2007 +0000
@@ -77,6 +77,28 @@
 plugin's C API back into a Vamp::Plugin object.  Hosts should link
 with -lvamp-hostsdk.
 
+ * vamp-sdk/hostext
+
+Additional C++ classes to make a host's life easier.
+
+Vamp::HostExt::PluginLoader provides a very simple interface for a
+host to discover, load, and find out category information about the
+available plugins.  Most "casual" Vamp hosts will probably want to use
+this class.
+
+Vamp::HostExt::PluginInputDomainAdapter provides a simple means for
+hosts to handle plugins that expect frequency-domain input, without
+having to convert the input themselves.
+
+Vamp::HostExt::PluginChannelAdapter provides a simple means for hosts
+to use plugins that do not necessarily support the same number of
+audio channels as they have available, without having to apply a
+channel management / mixdown policy themselves.
+
+The PluginLoader can use the input domain and channel adapters
+automatically to make the entire conversion process transparent to the
+host if required.
+
  * examples
 
 Example plugins implemented using the C++ classes.  ZeroCrossing

--- a/vamp-sdk/hostext/PluginChannelAdapter.h	Fri Jun 01 13:53:42 2007 +0000
+++ b/vamp-sdk/hostext/PluginChannelAdapter.h	Fri Jun 01 15:00:51 2007 +0000
@@ -78,6 +78,22 @@
  *
  * Hosts requiring a different channel policy from the above will need
  * to implement it themselves, instead of using PluginChannelAdapter.
+ *
+ * Note that PluginChannelAdapter does not override the minimum and
+ * maximum channel counts returned by the wrapped plugin.  The host
+ * will need to be aware that it is using a PluginChannelAdapter, and
+ * be prepared to ignore these counts as necessary.  (This contrasts
+ * with the approach used in PluginInputDomainAdapter, which aims to
+ * make the host completely unaware of which underlying input domain
+ * is in fact in use.)
+ * 
+ * The rationale for this is that a host may wish to use the
+ * PluginChannelAdapter but still discriminate in some way on the
+ * basis of the number of channels actually supported.  For example, a
+ * simple stereo audio host may prefer to reject plugins that require
+ * more than two channels on the grounds that doesn't actually
+ * understand what they are for, rather than allow the channel adapter
+ * to make a potentially meaningless channel conversion for them.
  */
 
 class PluginChannelAdapter : public PluginWrapper

--- a/vamp-sdk/hostext/PluginInputDomainAdapter.h	Fri Jun 01 13:53:42 2007 +0000
+++ b/vamp-sdk/hostext/PluginInputDomainAdapter.h	Fri Jun 01 15:00:51 2007 +0000
@@ -44,27 +44,34 @@
 namespace HostExt {
 
 /**
- * An adapter that converts time-domain input into frequency-domain
- * input for plugins that need it.  In every other respect this
- * adapter behaves like the plugin it wraps.  The wrapped plugin may
- * be a time-domain plugin, in which case this wrapper does nothing.
+ * PluginInputDomainAdapter is a Vamp plugin adapter that converts
+ * time-domain input into frequency-domain input for plugins that need
+ * it.  This permits a host to use time- and frequency-domain plugins
+ * interchangeably without needing to handle the conversion itself.
  *
- * Uses a Hanning windowed FFT.  The FFT implementation is not the
- * fastest, so a host can do much better if it cares enough, but it is
- * simple and self-contained.
+ * This adapter uses a basic Hanning windowed FFT that supports
+ * power-of-two block sizes only.  If a frequency domain plugin
+ * requests a non-power-of-two blocksize, the adapter will adjust it
+ * to a nearby power of two instead.  Thus, getPreferredBlockSize()
+ * will always return a power of two if the wrapped plugin is a
+ * frequency domain one.  If the plugin doesn't accept the adjusted
+ * power of two block size, initialise() will fail.
  *
- * Note that this adapter does not support non-power-of-two block
- * sizes.
+ * The adapter provides no way for the host to discover whether the
+ * underlying plugin is actually a time or frequency domain plugin
+ * (except that if the preferred block size is not a power of two, it
+ * must be a time domain plugin).
+ *
+ * The FFT implementation is simple and self-contained, but unlikely
+ * to be the fastest available: a host can usually do better if it
+ * cares enough.
+ *
+ * In every respect other than its input domain handling, the
+ * PluginInputDomainAdapter behaves identically to the plugin that it
+ * wraps.  The wrapped plugin will be deleted when the wrapper is
+ * deleted.
  */
 
-//!!! It would also be nice to have a channel wrapper, which deals
-//with mixing down channels if the plugin needs a different number
-//from the input source.  It would have some sort of mixdown/channel
-//input policy selection.  Probably this class and that one should
-//both inherit a PluginAdapter class which contains a plugin and
-//delegates all calls through to it; the subclass can then override
-//only the ones it needs to handle.
-
 class PluginInputDomainAdapter : public PluginWrapper
 {
 public:

--- a/vamp-sdk/hostext/PluginLoader.h	Fri Jun 01 13:53:42 2007 +0000
+++ b/vamp-sdk/hostext/PluginLoader.h	Fri Jun 01 15:00:51 2007 +0000
@@ -49,31 +49,134 @@
 
 namespace HostExt {
 
+/**
+ * Vamp::HostExt::PluginLoader is a convenience class for discovering
+ * and loading Vamp plugins using the typical plugin-path, library
+ * naming, and categorisation conventions described in the Vamp SDK
+ * documentation.  This class is intended to greatly simplify the task
+ * of becoming a Vamp plugin host for any C++ application.
+ * 
+ * Hosts are not required by the Vamp specification to use the same
+ * plugin search path and naming conventions as implemented by this
+ * class, and are certainly not required to use this actual class.
+ * But it's recommended, for sound practical reasons.
+ */
+
 class PluginLoader
 {
 public:
+    /**
+     * PluginLoader is a singleton class.  This function returns a
+     * pointer to the single instance of it.  Use this to obtain your
+     * loader object.
+     */
     static PluginLoader *getInstance();
 
+    /**
+     * PluginKey is a string type that is used to identify a plugin
+     * uniquely within the scope of "the current system".  It consists
+     * of the base name of the plugin library, a colon separator, and
+     * the identifier string for the plugin.  It is only meaningful in
+     * the context of a given plugin path (the one returned by
+     * PluginHostAdapter::getPluginPath()).
+     *
+     * Use composePluginKey to construct a plugin key from a known
+     * plugin library name and identifier.
+     */
     typedef std::string PluginKey;
+
+    /**
+     * PluginKeyList is a sequence of plugin keys, such as returned by
+     * a plugin lookup function.
+     */
     typedef std::vector<PluginKey> PluginKeyList;
+
+    /**
+     * PluginCategoryHierarchy is a sequence of general->specific
+     * category names, as may be associated with a single plugin.
+     * This sequence describes the location of a plugin within a
+     * category forest, containing the human-readable names of the
+     * plugin's category tree root, followed by each of the nodes down
+     * to the leaf containing the plugin.
+     */
     typedef std::vector<std::string> PluginCategoryHierarchy;
 
-    PluginKeyList listPlugins(); //!!! pass in version number?
+    /**
+     * Search for all available Vamp plugins, and return a list of
+     * them in the order in which they were found.
+     */
+    PluginKeyList listPlugins();
 
-    PluginKey composePluginKey(std::string libraryName, std::string identifier);
-
+    /**
+     * AdapterFlags contains a set of values that may be OR'd together
+     * to indicate in which circumstances PluginLoader should use a
+     * plugin adapter to make a plugin easier to use for a host that
+     * does not want to cater for complex features.
+     *
+     * The available flags are:
+     * 
+     * ADAPT_INPUT_DOMAIN - If the plugin expects frequency domain
+     * input, wrap it in a PluginInputDomainAdapter that automatically
+     * converts the plugin to one that expects time-domain input.
+     * This enables a host to accommodate time- and frequency-domain
+     * plugins without needing to do any conversion itself.
+     *
+     * ADAPT_CHANNEL_COUNT - Wrap the plugin in a PluginChannelAdapter
+     * to handle any mismatch between the number of channels of audio
+     * the plugin can handle and the number available in the host.
+     * This enables a host to use plugins that may require the input
+     * to be mixed down to mono, etc., without having to worry about
+     * doing that itself.
+     * 
+     * See PluginInputDomainAdapter and PluginChannelAdapter for more
+     * details of the classes that the loader may use if these flags
+     * are set.
+     */
     enum AdapterFlags {
         ADAPT_INPUT_DOMAIN  = 0x01,
         ADAPT_CHANNEL_COUNT = 0x02,
         ADAPT_ALL           = 0xff
     };
 
-    Plugin *loadPlugin(PluginKey plugin,
+    /**
+     * Load a Vamp plugin, given its identifying key.  If the plugin
+     * could not be loaded, returns 0.
+     *
+     * adapterFlags is a bitwise OR of the values in the AdapterFlags
+     * enum, indicating under which circumstances an adapter should be
+     * used to wrap the original plugin.  See AdapterFlags for more
+     * details.  If adapterFlags is 0, no optional adapters will be
+     * used.
+     *
+     * The returned plugin should be deleted (using the standard C++
+     * delete) after use.
+     */
+    Plugin *loadPlugin(PluginKey key,
                        float inputSampleRate,
                        int adapterFlags = 0);
 
+    /**
+     * Given a Vamp plugin library name and plugin identifier, return
+     * the corresponding plugin key in a form suitable for passing in to
+     * loadPlugin.
+     */
+    PluginKey composePluginKey(std::string libraryName,
+                               std::string identifier);
+
+    /**
+     * Return the category hierarchy for a Vamp plugin, given its
+     * identifying key.  See PluginCategoryHierarchy documentation for
+     * more details.
+     *
+     * If the plugin has no category information, return an empty
+     * hierarchy.
+     */
     PluginCategoryHierarchy getPluginCategory(PluginKey plugin);
 
+    /**
+     * Return the file path of the dynamic library from which the
+     * given plugin will be loaded (if available).
+     */
     std::string getLibraryPathForPlugin(PluginKey plugin);
 
 protected:

--- a/vamp-sdk/hostext/PluginWrapper.h	Fri Jun 01 13:53:42 2007 +0000
+++ b/vamp-sdk/hostext/PluginWrapper.h	Fri Jun 01 15:00:51 2007 +0000
@@ -43,6 +43,15 @@
 
 namespace HostExt {
 
+/**
+ * PluginWrapper is a simple base class for adapter plugins.  It takes
+ * a pointer to a "to be wrapped" Vamp plugin on construction, and
+ * provides implementations of all the Vamp plugin methods that simply
+ * delegate through to the wrapped plugin.  A subclass can therefore
+ * override only the methods that are meaningful for the particular
+ * adapter.
+ */
+
 class PluginWrapper : public Plugin
 {
 public: