Mercurial > hg > vamp-plugin-sdk

changeset 75:0f8524203677

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* doc updates
author cannam
date Thu, 07 Jun 2007 13:56:26 +0000
parents 64d45f526afc
children 6683f99107cf
files Doxyfile README vamp-sdk/doc-overview vamp-sdk/hostext/PluginChannelAdapter.h vamp-sdk/hostext/PluginInputDomainAdapter.h vamp-sdk/hostext/PluginLoader.cpp vamp-sdk/hostext/PluginLoader.h vamp-sdk/hostext/PluginWrapper.h
diffstat 8 files changed, 104 insertions(+), 53 deletions(-) [+]
line wrap: on
line diff
--- a/Doxyfile	Wed Jun 06 13:14:18 2007 +0000
+++ b/Doxyfile	Thu Jun 07 13:56:26 2007 +0000
@@ -450,7 +450,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = vamp vamp-sdk examples host
+INPUT                  = vamp vamp-sdk vamp-sdk/hostext examples host
 
 # If the value of the INPUT tag contains directories, you can use the
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
--- a/README	Wed Jun 06 13:14:18 2007 +0000
+++ b/README	Thu Jun 07 13:56:26 2007 +0000
@@ -79,7 +79,8 @@
 
  * vamp-sdk/hostext
 
-Additional C++ classes to make a host's life easier.
+Additional C++ classes to make a host's life easier (introduced in
+version 1.1 of the Vamp SDK).
 
 Vamp::HostExt::PluginLoader provides a very simple interface for a
 host to discover, load, and find out category information about the
@@ -95,9 +96,9 @@
 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.
+The PluginLoader class can also use the input domain and channel
+adapters automatically to make the entire conversion process
+transparent to the host if required.
 
  * examples
 
@@ -117,8 +118,8 @@
 Requires libsndfile (http://www.mega-nerd.com/libsndfile/).
 
 If you don't have libsndfile, you may want to edit the Makefile to
-change the default build target from "all" to "sdk" so as to compile
-only the SDK.
+change the default build target from "all" to "sdk", so as to compile
+only the SDK and not the host.
 
 
 Plugin Lookup and Categorisation
@@ -127,14 +128,20 @@
 The Vamp API does not officially specify how to load plugin libraries
 or where to find them.  However, the SDK does include a function
 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
-directory search path that hosts may use for plugin libraries.
+directory search path that hosts may use for plugin libraries, and a
+class (Vamp::HostExt::PluginLoader) that implements a sensible
+cross-platform lookup policy using this path.  We recommend using this
+class in your host unless you have a good reason not to want to.  This
+implementation also permits the user to set the environment variable
+VAMP_PATH to override the default path if desired.
 
-Our suggestion for a host is to search each directory in this path for
-.DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib (on
-OS/X) files, then to load each one and perform a dynamic name lookup
-on the vampGetPluginDescriptor function to enumerate the plugins in
-the library.  The example host has some code that may help, but this
-operation will necessarily be system-dependent.
+The policy used by Vamp::HostExt::PluginLoader -- and our
+recommendation for any host -- is to search each directory in the path
+returned by getPluginPath for .DLL (on Windows), .so (on Linux,
+Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and
+perform a dynamic name lookup on the vampGetPluginDescriptor function
+to enumerate the plugins in the library.  This operation will
+necessarily be system-dependent.
 
 Vamp also has an informal convention for sorting plugins into
 functional categories.  In addition to the library file itself, a
@@ -149,7 +156,8 @@
 category tree for display to the user.  The expectation is that
 advanced users may also choose to set up their own preferred category
 trees, which is why this information is not queried as part of the
-Vamp API itself.
+Vamp plugin's API itself.  The Vamp::HostExt::PluginLoader class also
+provides support for plugin category lookup using this scheme.
 
 
 Building and Installing the SDK and Examples
--- a/vamp-sdk/doc-overview	Wed Jun 06 13:14:18 2007 +0000
+++ b/vamp-sdk/doc-overview	Thu Jun 07 13:56:26 2007 +0000
@@ -44,11 +44,37 @@
 
 \section hosts For Hosts
 
-Hosts will usually want to use a Vamp::PluginHostAdapter to convert
-each plugin's exposed C API back into a useful Vamp::Plugin object.
+Hosts will normally use a Vamp::PluginHostAdapter to convert each
+plugin's exposed C API back into a useful Vamp::Plugin C++ object.
+
+Starting with version 1.1 of the Vamp SDK, there are several classes
+in the Vamp::HostExt namespace that aim to make the host's life as
+easy as possible:
+
+ - 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 class can also use the input domain and channel
+adapters automatically to make the entire conversion process
+transparent to the host if required.
 
 Hosts should link with -lvamp-hostsdk.
 
+(The following notes in this section are mostly relevant for
+developers that are not using the HostExt classes, or that wish to
+know more about the policy they implement.)
+
 The Vamp API does not officially specify how to load plugin libraries
 or where to find them.  However, the SDK does include a function
 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
@@ -78,8 +104,8 @@
 trees, which is why this information is not queried as part of the
 Vamp API itself.
 
-There is an example host in the "host" directory from
-which code may be drawn.
+There is an example host in the "host" directory from which code may
+be drawn.
 
 \section license License
 
--- a/vamp-sdk/hostext/PluginChannelAdapter.h	Wed Jun 06 13:14:18 2007 +0000
+++ b/vamp-sdk/hostext/PluginChannelAdapter.h	Thu Jun 07 13:56:26 2007 +0000
@@ -55,27 +55,27 @@
  *
  * PluginChannelAdapter implements the following policy:
  *
- * -- If the plugin supports the provided number of channels directly,
- * PluginChannelAdapter will just run the plugin as normal.
+ *  - If the plugin supports the provided number of channels directly,
+ *  PluginChannelAdapter will just run the plugin as normal.
  *
- * -- If the plugin only supports exactly one channel but more than
- * one channel is provided, PluginChannelAdapter will use the mean of
- * the channels.  This ensures that the resulting values remain within
- * the same magnitude range as expected for mono data.
+ *  - If the plugin only supports exactly one channel but more than
+ *  one channel is provided, PluginChannelAdapter will use the mean of
+ *  the channels.  This ensures that the resulting values remain
+ *  within the same magnitude range as expected for mono data.
  *
- * -- If the plugin requires more than one channel but exactly one is
- * provided, the provided channel will be duplicated across all the
- * plugin input channels.
+ *  - If the plugin requires more than one channel but exactly one is
+ *  provided, the provided channel will be duplicated across all the
+ *  plugin input channels.
  *
  * If none of the above apply:
  * 
- * -- If the plugin requires more channels than are provided, the
- * minimum acceptable number of channels will be produced by adding
- * empty (zero valued) channels to those provided.
+ *  - If the plugin requires more channels than are provided, the
+ *  minimum acceptable number of channels will be produced by adding
+ *  empty (zero valued) channels to those provided.
  *
- * -- If the plugin requires fewer channels than are provided, the
- * maximum acceptable number of channels will be produced by
- * discarding the excess channels.
+ *  - If the plugin requires fewer channels than are provided, the
+ *  maximum acceptable number of channels will be produced by
+ *  discarding the excess channels.
  *
  * Hosts requiring a different channel policy from the above will need
  * to implement it themselves, instead of using PluginChannelAdapter.
@@ -100,6 +100,8 @@
  * PluginChannelAdapter behaves identically to the plugin that it
  * wraps.  The wrapped plugin will be deleted when the wrapper is
  * deleted.
+ *
+ * \note This class was introduced version 1.1 of the Vamp plugin SDK.
  */
 
 class PluginChannelAdapter : public PluginWrapper
--- a/vamp-sdk/hostext/PluginInputDomainAdapter.h	Wed Jun 06 13:14:18 2007 +0000
+++ b/vamp-sdk/hostext/PluginInputDomainAdapter.h	Thu Jun 07 13:56:26 2007 +0000
@@ -70,6 +70,8 @@
  * PluginInputDomainAdapter behaves identically to the plugin that it
  * wraps.  The wrapped plugin will be deleted when the wrapper is
  * deleted.
+ *
+ * \note This class was introduced version 1.1 of the Vamp plugin SDK.
  */
 
 class PluginInputDomainAdapter : public PluginWrapper
--- a/vamp-sdk/hostext/PluginLoader.cpp	Wed Jun 06 13:14:18 2007 +0000
+++ b/vamp-sdk/hostext/PluginLoader.cpp	Thu Jun 07 13:56:26 2007 +0000
@@ -40,6 +40,7 @@
 #include "PluginChannelAdapter.h"
 
 #include <fstream>
+#include <cctype> // tolower
 
 #ifdef _WIN32
 
@@ -216,7 +217,7 @@
                 // as it came from the plugin key
                 string temp = *fi;
                 for (size_t i = 0; i < temp.length(); ++i) {
-                    temp[i] = std::tolower(temp[i]);
+                    temp[i] = tolower(temp[i]);
                 }
                 string::size_type pi = temp.find('.');
                 if (pi == string::npos) {
@@ -275,7 +276,7 @@
     if (li != string::npos) basename = basename.substr(0, li);
 
     for (size_t i = 0; i < basename.length(); ++i) {
-        basename[i] = std::tolower(basename[i]);
+        basename[i] = tolower(basename[i]);
     }
 
     return basename + ":" + identifier;
--- a/vamp-sdk/hostext/PluginLoader.h	Wed Jun 06 13:14:18 2007 +0000
+++ b/vamp-sdk/hostext/PluginLoader.h	Thu Jun 07 13:56:26 2007 +0000
@@ -59,16 +59,17 @@
  * 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.
+ * But we do strongly recommend it.
+ *
+ * \note This class was introduced version 1.1 of the Vamp plugin SDK.
  */
 
 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.
+     * Obtain a pointer to the singleton instance of PluginLoader.
+     * Use this to obtain your loader object.
      */
     static PluginLoader *getInstance();
 
@@ -80,7 +81,7 @@
      * 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
+     * Use composePluginKey() to construct a plugin key from a known
      * plugin library name and identifier.
      *
      * Note: the fact that the library component of the key is
@@ -90,13 +91,13 @@
      * identifiers _are_ case sensitive, however.)  Also, it is not
      * possible to portably extract a working library name from a
      * plugin key, as the result may fail on case-sensitive
-     * filesystems.  Use getLibraryPathForPlugin instead.
+     * filesystems.  Use getLibraryPathForPlugin() instead.
      */
     typedef std::string PluginKey;
 
     /**
      * PluginKeyList is a sequence of plugin keys, such as returned by
-     * a plugin lookup function.
+     * listPlugins().
      */
     typedef std::vector<PluginKey> PluginKeyList;
 
@@ -107,6 +108,8 @@
      * 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.
+     *
+     * \see getPluginCategory()
      */
     typedef std::vector<std::string> PluginCategoryHierarchy;
 
@@ -136,6 +139,8 @@
      * 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.
+     *
+     * ADAPT_ALL - Perform all available adaptations, where meaningful.
      * 
      * See PluginInputDomainAdapter and PluginChannelAdapter for more
      * details of the classes that the loader may use if these flags
@@ -151,14 +156,18 @@
      * 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 keyword) after use.
      *
-     * The returned plugin should be deleted (using the standard C++
-     * delete) after use.
+     * \param adapterFlags a bitwise OR of the values in the AdapterFlags
+     * enumeration, indicating under which circumstances an adapter should be
+     * used to wrap the original plugin.  If adapterFlags is 0, no
+     * optional adapters will be used.  Otherwise, the returned plugin
+     * may be of an adapter class type which will behave identically
+     * to the original plugin, apart from any particular features
+     * implemented by the adapter itself.
+     * 
+     * \see AdapterFlags, PluginInputDomainAdapter, PluginChannelAdapter
      */
     Plugin *loadPlugin(PluginKey key,
                        float inputSampleRate,
@@ -167,18 +176,19 @@
     /**
      * Given a Vamp plugin library name and plugin identifier, return
      * the corresponding plugin key in a form suitable for passing in to
-     * loadPlugin.
+     * 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.
+     * identifying key.
      *
      * If the plugin has no category information, return an empty
      * hierarchy.
+     *
+     * \see PluginCategoryHierarchy
      */
     PluginCategoryHierarchy getPluginCategory(PluginKey plugin);
 
--- a/vamp-sdk/hostext/PluginWrapper.h	Wed Jun 06 13:14:18 2007 +0000
+++ b/vamp-sdk/hostext/PluginWrapper.h	Thu Jun 07 13:56:26 2007 +0000
@@ -50,6 +50,8 @@
  * delegate through to the wrapped plugin.  A subclass can therefore
  * override only the methods that are meaningful for the particular
  * adapter.
+ *
+ * \note This class was introduced version 1.1 of the Vamp plugin SDK.
  */
 
 class PluginWrapper : public Plugin