changeset 423:8c45dee08a95 vampipe

Add PluginConfiguration, PluginStaticData, and LoadRequest structures, and use them in PluginLoader

--- a/Makefile.in	Thu Apr 14 14:23:48 2016 +0100
+++ b/Makefile.in	Thu May 12 12:22:02 2016 +0100
@@ -146,13 +146,16 @@
 		$(HOSTSDKDIR)/Plugin.h \
 		$(HOSTSDKDIR)/PluginBase.h \
 		$(HOSTSDKDIR)/PluginHostAdapter.h \
-		$(HOSTSDKDIR)/RealTime.h \
 		$(HOSTSDKDIR)/PluginBufferingAdapter.h \
 		$(HOSTSDKDIR)/PluginChannelAdapter.h \
 		$(HOSTSDKDIR)/PluginInputDomainAdapter.h \
 		$(HOSTSDKDIR)/PluginLoader.h \
 		$(HOSTSDKDIR)/PluginSummarisingAdapter.h \
 		$(HOSTSDKDIR)/PluginWrapper.h \
+		$(HOSTSDKDIR)/RealTime.h \
+		$(HOSTSDKDIR)/PluginConfiguration.h \
+		$(HOSTSDKDIR)/PluginStaticData.h \
+		$(HOSTSDKDIR)/LoadRequest.h \
 		$(HOSTSDKDIR)/hostguard.h \
 		$(HOSTSDKDIR)/host-c.h \
 		$(HOSTSDKDIR)/vamp-hostsdk.h

--- a/README	Thu Apr 14 14:23:48 2016 +0100
+++ b/README	Thu May 12 12:22:02 2016 +0100
@@ -12,6 +12,9 @@
 This is version 2.6 of the Vamp plugin Software Development Kit.
 
 Plugins and hosts built with this SDK are binary compatible with those
+built using any version 2.0 or newer of the SDK.
+
+Plugins and hosts built with this SDK are binary compatible with those
 built using version 1.0 of the SDK, with certain restrictions.  See
 the file README.compat for more details.
 
@@ -248,7 +251,7 @@
 Vamp and the Vamp SDK were designed and made at the Centre for Digital
 Music at Queen Mary, University of London.
 
-The SDK was written by Chris Cannam, copyright (c) 2005-2015
+The SDK was written by Chris Cannam, copyright (c) 2005-2016
 Chris Cannam and QMUL.
 
 Mark Sandler and Christian Landone provided ideas and direction, and

--- a/build/Makefile.mingw32	Thu Apr 14 14:23:48 2016 +0100
+++ b/build/Makefile.mingw32	Thu May 12 12:22:02 2016 +0100
@@ -132,6 +132,9 @@
 		$(HOSTSDKDIR)/PluginLoader.h \
 		$(HOSTSDKDIR)/PluginSummarisingAdapter.h \
 		$(HOSTSDKDIR)/PluginWrapper.h \
+		$(HOSTSDKDIR)/PluginConfiguration.h \
+		$(HOSTSDKDIR)/PluginStaticData.h \
+		$(HOSTSDKDIR)/LoadRequest.h \
 		$(HOSTSDKDIR)/hostguard.h \
 		$(HOSTSDKDIR)/host-c.h \
 		$(HOSTSDKDIR)/vamp-hostsdk.h

--- a/build/Makefile.mingw64	Thu Apr 14 14:23:48 2016 +0100
+++ b/build/Makefile.mingw64	Thu May 12 12:22:02 2016 +0100
@@ -132,6 +132,9 @@
 		$(HOSTSDKDIR)/PluginLoader.h \
 		$(HOSTSDKDIR)/PluginSummarisingAdapter.h \
 		$(HOSTSDKDIR)/PluginWrapper.h \
+		$(HOSTSDKDIR)/PluginConfiguration.h \
+		$(HOSTSDKDIR)/PluginStaticData.h \
+		$(HOSTSDKDIR)/LoadRequest.h \
 		$(HOSTSDKDIR)/hostguard.h \
 		$(HOSTSDKDIR)/host-c.h \
 		$(HOSTSDKDIR)/vamp-hostsdk.h

--- a/build/Makefile.osx	Thu Apr 14 14:23:48 2016 +0100
+++ b/build/Makefile.osx	Thu May 12 12:22:02 2016 +0100
@@ -140,6 +140,9 @@
 		$(HOSTSDKDIR)/PluginLoader.h \
 		$(HOSTSDKDIR)/PluginSummarisingAdapter.h \
 		$(HOSTSDKDIR)/PluginWrapper.h \
+		$(HOSTSDKDIR)/PluginConfiguration.h \
+		$(HOSTSDKDIR)/PluginStaticData.h \
+		$(HOSTSDKDIR)/LoadRequest.h \
 		$(HOSTSDKDIR)/hostguard.h \
 		$(HOSTSDKDIR)/host-c.h \
 		$(HOSTSDKDIR)/vamp-hostsdk.h

--- a/build/Makefile.osx.106	Thu Apr 14 14:23:48 2016 +0100
+++ b/build/Makefile.osx.106	Thu May 12 12:22:02 2016 +0100
@@ -161,7 +161,11 @@
 		$(HOSTSDKDIR)/PluginLoader.h \
 		$(HOSTSDKDIR)/PluginSummarisingAdapter.h \
 		$(HOSTSDKDIR)/PluginWrapper.h \
+		$(HOSTSDKDIR)/PluginConfiguration.h \
+		$(HOSTSDKDIR)/PluginStaticData.h \
+		$(HOSTSDKDIR)/LoadRequest.h \
 		$(HOSTSDKDIR)/hostguard.h \
+		$(HOSTSDKDIR)/host-c.h \
 		$(HOSTSDKDIR)/vamp-hostsdk.h
 
 SDK_OBJECTS	= \

--- a/src/vamp-hostsdk/PluginLoader.cpp	Thu Apr 14 14:23:48 2016 +0100
+++ b/src/vamp-hostsdk/PluginLoader.cpp	Thu May 12 12:22:02 2016 +0100
@@ -6,7 +6,7 @@
     An API for audio analysis and feature extraction plugins.
 
     Centre for Digital Music, Queen Mary, University of London.
-    Copyright 2006-2009 Chris Cannam and QMUL.
+    Copyright 2006-2016 Chris Cannam and QMUL.
   
     Permission is hereby granted, free of charge, to any person
     obtaining a copy of this software and associated documentation
@@ -66,6 +66,10 @@
                        float inputSampleRate,
                        int adapterFlags);
 
+    LoadResponse loadPlugin(LoadRequest req);
+
+    Plugin::OutputList configurePlugin(Plugin *plugin, PluginConfiguration config);
+    
     PluginKey composePluginKey(string libraryName, string identifier);
 
     PluginCategoryHierarchy getPluginCategory(PluginKey key);
@@ -152,6 +156,18 @@
     return m_impl->loadPlugin(key, inputSampleRate, adapterFlags);
 }
 
+LoadResponse
+PluginLoader::loadPlugin(LoadRequest req)
+{
+    return m_impl->loadPlugin(req);
+}
+
+Plugin::OutputList
+PluginLoader::configurePlugin(Plugin *plugin, PluginConfiguration config)
+{
+    return m_impl->configurePlugin(plugin, config);
+}
+
 PluginLoader::PluginKey
 PluginLoader::composePluginKey(string libraryName, string identifier) 
 {
@@ -382,6 +398,57 @@
     return 0;
 }
 
+LoadResponse
+PluginLoader::Impl::loadPlugin(LoadRequest req)
+{
+    Plugin *plugin = loadPlugin(req.pluginKey,
+                                req.inputSampleRate,
+                                req.adapterFlags);
+    LoadResponse response;
+    if (!plugin) return response;
+
+    response.plugin = plugin;
+    response.staticData = PluginStaticData::fromPlugin
+        (req.pluginKey,
+         getPluginCategory(req.pluginKey),
+         plugin);
+
+    int defaultChannels = 0;
+    if (plugin->getMinChannelCount() == plugin->getMaxChannelCount()) {
+        defaultChannels = plugin->getMinChannelCount();
+    }
+    
+    response.defaultConfiguration = PluginConfiguration::fromPlugin
+        (plugin,
+         defaultChannels,
+         plugin->getPreferredStepSize(),
+         plugin->getPreferredBlockSize());
+    
+    return response;
+}
+
+Plugin::OutputList
+PluginLoader::Impl::configurePlugin(Plugin *plugin, PluginConfiguration config)
+{
+    for (PluginConfiguration::ParameterMap::const_iterator i =
+             config.parameterValues.begin();
+         i != config.parameterValues.end(); ++i) {
+        plugin->setParameter(i->first, i->second);
+    }
+
+    if (config.currentProgram != "") {
+        plugin->selectProgram(config.currentProgram);
+    }
+
+    if (plugin->initialise(config.channelCount,
+                           config.stepSize,
+                           config.blockSize)) {
+        return plugin->getOutputDescriptors();
+    } else {
+        return Plugin::OutputList();
+    }
+}
+
 void
 PluginLoader::Impl::generateTaxonomy()
 {

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/vamp-hostsdk/LoadRequest.h	Thu May 12 12:22:02 2016 +0100
@@ -0,0 +1,115 @@
+/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
+
+/*
+    Vamp
+
+    An API for audio analysis and feature extraction plugins.
+
+    Centre for Digital Music, Queen Mary, University of London.
+    Copyright 2006-2016 Chris Cannam and QMUL.
+  
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use, copy,
+    modify, merge, publish, distribute, sublicense, and/or sell copies
+    of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
+    ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+    Except as contained in this notice, the names of the Centre for
+    Digital Music; Queen Mary, University of London; and Chris Cannam
+    shall not be used in advertising or otherwise to promote the sale,
+    use or other dealings in this Software without prior written
+    authorization.
+*/
+
+#ifndef VAMP_LOAD_REQUEST_H
+#define VAMP_LOAD_REQUEST_H
+
+#include "PluginStaticData.h"
+#include "PluginConfiguration.h"
+
+#include "hostguard.h"
+
+#include <map>
+#include <string>
+
+_VAMP_SDK_HOSTSPACE_BEGIN(LoadRequest.h)
+
+namespace Vamp {
+
+class Plugin;
+
+namespace HostExt {
+
+/**
+ * \class LoadRequest LoadRequest.h <vamp-hostsdk/LoadRequest.h>
+ * 
+ * Vamp::HostExt::LoadRequest is a structure containing the
+ * information necessary to load a plugin. When a request is made to
+ * load a plugin using a LoadRequest, the response is typically
+ * returned in a LoadResponse structure.
+ *
+ * \see LoadResponse
+ *
+ * \note This class was introduced in version 2.7 of the Vamp plugin
+ * SDK, along with the PluginLoader method that accepts this structure
+ * rather than accepting its elements individually.
+ */
+struct LoadRequest
+{
+    LoadRequest() : // invalid request by default
+	inputSampleRate(0.f),
+	adapterFlags(0) { }
+    
+    std::string pluginKey; //!!! separate out key from PluginLoader??
+    float inputSampleRate;
+    int adapterFlags; //!!! from PluginLoader::AdapterFlags, but how best to handle?
+};
+
+/**
+ * \class LoadResponse LoadResponse.h <vamp-hostsdk/LoadResponse.h>
+ * 
+ * Vamp::HostExt::LoadResponse is a structure containing the
+ * information returned by PluginLoader when asked to load a plugin
+ * using a LoadRequest.
+ *
+ * If the plugin could not be loaded, the plugin field will be 0.
+ *
+ * The caller takes ownership of the plugin contained here, which
+ * should be deleted (using the standard C++ delete keyword) after
+ * use.
+ *
+ * \see LoadRequest
+ *
+ * \note This class was introduced in version 2.7 of the Vamp plugin
+ * SDK, along with the PluginLoader method that returns this structure.
+ */
+struct LoadResponse
+{
+    LoadResponse() : // invalid (failed) response by default
+	plugin(0) { }
+    
+    Plugin *plugin;
+    PluginStaticData staticData;
+    PluginConfiguration defaultConfiguration;
+};
+
+}
+
+}
+
+_VAMP_SDK_HOSTSPACE_END(LoadRequest.h)
+
+#endif

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/vamp-hostsdk/PluginConfiguration.h	Thu May 12 12:22:02 2016 +0100
@@ -0,0 +1,111 @@
+/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
+
+/*
+    Vamp
+
+    An API for audio analysis and feature extraction plugins.
+
+    Centre for Digital Music, Queen Mary, University of London.
+    Copyright 2006-2016 Chris Cannam and QMUL.
+  
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use, copy,
+    modify, merge, publish, distribute, sublicense, and/or sell copies
+    of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
+    ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+    Except as contained in this notice, the names of the Centre for
+    Digital Music; Queen Mary, University of London; and Chris Cannam
+    shall not be used in advertising or otherwise to promote the sale,
+    use or other dealings in this Software without prior written
+    authorization.
+*/
+
+#ifndef VAMP_PLUGIN_CONFIGURATION_H
+#define VAMP_PLUGIN_CONFIGURATION_H
+
+#include "hostguard.h"
+
+#include <map>
+#include <string>
+
+_VAMP_SDK_HOSTSPACE_BEGIN(PluginConfiguration.h)
+
+namespace Vamp {
+
+namespace HostExt {
+
+/**
+ * \class PluginConfiguration PluginConfiguration.h <vamp-hostsdk/PluginConfiguration.h>
+ * 
+ * Vamp::HostExt::PluginConfiguration is a structure bundling together
+ * data that affect the configuration of a plugin: parameter values,
+ * programs, and initialisation settings. Although an interactive Vamp
+ * plugin host may configure a plugin in stages, for example to take
+ * into account that a plugin's preferred step and block size may
+ * change when its parameters are changed, a batch host or a host
+ * supporting store and recall of configurations may wish to keep all
+ * configuration settings together.
+ *
+ * \note This class was introduced in version 2.7 of the Vamp plugin
+ * SDK.
+ */
+struct PluginConfiguration
+{
+    PluginConfiguration() : // invalid configuration by default
+	channelCount(0), stepSize(0), blockSize(0) { }
+	
+    int channelCount;
+    int stepSize;
+    int blockSize;
+    typedef std::map<std::string, float> ParameterMap;
+    ParameterMap parameterValues;
+    std::string currentProgram;
+
+    static PluginConfiguration
+    fromPlugin(Plugin *p,
+	       int channelCount,
+	       int stepSize,
+	       int blockSize) {
+	
+	PluginConfiguration c;
+	
+	c.channelCount = channelCount;
+	c.stepSize = stepSize;
+	c.blockSize = blockSize;
+
+	PluginBase::ParameterList params = p->getParameterDescriptors();
+	for (PluginBase::ParameterList::const_iterator i = params.begin();
+	     i != params.end(); ++i) {
+	    std::string pid = i->identifier;
+	    c.parameterValues[pid] = p->getParameter(pid);
+	}
+	
+	if (!p->getPrograms().empty()) {
+	    c.currentProgram = p->getCurrentProgram();
+	}
+
+	return c;
+    }
+};
+
+}
+
+}
+
+_VAMP_SDK_HOSTSPACE_END(PluginConfiguration.h)
+
+#endif

--- a/vamp-hostsdk/PluginLoader.h	Thu Apr 14 14:23:48 2016 +0100
+++ b/vamp-hostsdk/PluginLoader.h	Thu May 12 12:22:02 2016 +0100
@@ -43,6 +43,7 @@
 
 #include "hostguard.h"
 #include "PluginWrapper.h"
+#include "LoadRequest.h"
 
 _VAMP_SDK_HOSTSPACE_BEGIN(PluginLoader.h)
 
@@ -202,6 +203,34 @@
                        int adapterFlags = 0);
 
     /**
+     * Load a Vamp plugin, given its key, inputSampleRate and the
+     * adapter flags, bundled into a LoadRequest structure. The loaded
+     * plugin is returned along with its static data and default
+     * configuration in a LoadResponse.
+     * 
+     * \see AdapterFlags, PluginInputDomainAdapter, PluginChannelAdapter, LoadRequest, LoadResponse
+     */
+    LoadResponse loadPlugin(LoadRequest req);
+
+    /**
+     * Configure and initialise a Vamp plugin. This applies the
+     * parameter and program settings found in the supplied
+     * PluginConfiguration structure and initialises the plugin. (Many
+     * hosts will prefer to do this themselves in stages, by calling
+     * methods on the plugin directly.)
+     *
+     * Returns the result of calling getOutputDescriptors() on the
+     * configured and initialised plugin, representing the outputs of
+     * the plugin following configuration (since output ranges etc can
+     * depend on the parameters). If plugin initialisation fails,
+     * returns an empty list.
+     *
+     * \see PluginConfiguration
+     */
+    Plugin::OutputList configurePlugin(Plugin *plugin,
+                                       PluginConfiguration configuration);
+    
+    /**
      * Given a Vamp plugin library name and plugin identifier, return
      * the corresponding plugin key in a form suitable for passing in to
      * loadPlugin().

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/vamp-hostsdk/PluginStaticData.h	Thu May 12 12:22:02 2016 +0100
@@ -0,0 +1,127 @@
+/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
+
+/*
+    Vamp
+
+    An API for audio analysis and feature extraction plugins.
+
+    Centre for Digital Music, Queen Mary, University of London.
+    Copyright 2006-2016 Chris Cannam and QMUL.
+  
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use, copy,
+    modify, merge, publish, distribute, sublicense, and/or sell copies
+    of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
+    ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+    Except as contained in this notice, the names of the Centre for
+    Digital Music; Queen Mary, University of London; and Chris Cannam
+    shall not be used in advertising or otherwise to promote the sale,
+    use or other dealings in this Software without prior written
+    authorization.
+*/
+
+#ifndef VAMP_PLUGIN_STATIC_DATA_H
+#define VAMP_PLUGIN_STATIC_DATA_H
+
+#include "hostguard.h"
+#include "Plugin.h"
+
+_VAMP_SDK_HOSTSPACE_BEGIN(PluginStaticData.h)
+
+namespace Vamp {
+
+namespace HostExt {
+
+/**
+ * \class PluginStaticData PluginStaticData.h <vamp-hostsdk/PluginStaticData.h>
+ * 
+ * Vamp::HostExt::PluginStaticData is a structure bundling together
+ * all the information about a plugin that cannot be changed by the
+ * plugin after it is loaded. That is, everything that does not depend
+ * on a parameter or initialisation setting.
+ *
+ * \note This class was introduced in version 2.7 of the Vamp plugin
+ * SDK and is used only by host SDK functions that were also
+ * introduced in that release (or newer).
+ */
+struct PluginStaticData
+{
+public:
+    struct Basic {
+	std::string identifier;
+	std::string name;
+	std::string description;
+    };
+
+    PluginStaticData() : // invalid static data by default
+	pluginVersion(0), minChannelCount(0), maxChannelCount(0),
+	inputDomain(Plugin::TimeDomain) { }
+
+    std::string pluginKey;
+    Basic basic;
+    std::string maker;
+    std::string copyright;
+    int pluginVersion;
+    std::vector<std::string> category;
+    int minChannelCount;
+    int maxChannelCount;
+    PluginBase::ParameterList parameters;
+    PluginBase::ProgramList programs;
+    Plugin::InputDomain inputDomain;
+    std::vector<Basic> basicOutputInfo;
+
+    static PluginStaticData
+    fromPlugin(std::string pluginKey,
+	       std::vector<std::string> category,
+	       Plugin *p) {
+
+	PluginStaticData d;
+	d.pluginKey = pluginKey;
+	d.basic.identifier = p->getIdentifier();
+	d.basic.name = p->getName();
+	d.basic.description = p->getDescription();
+	d.maker = p->getMaker();
+	d.copyright = p->getCopyright();
+	d.pluginVersion = p->getPluginVersion();
+	d.category = category;
+	d.minChannelCount = p->getMinChannelCount();
+	d.maxChannelCount = p->getMaxChannelCount();
+	d.parameters = p->getParameterDescriptors();
+	d.programs = p->getPrograms();
+	d.inputDomain = p->getInputDomain();
+
+	Plugin::OutputList outputs = p->getOutputDescriptors();
+	for (Plugin::OutputList::const_iterator i = outputs.begin();
+	     i != outputs.end(); ++i) {
+	    Basic b;
+	    b.identifier = i->identifier;
+	    b.name = i->name;
+	    b.description = i->description;
+	    d.basicOutputInfo.push_back(b);
+	}
+
+	return d;
+    }
+};
+
+}
+
+}
+
+_VAMP_SDK_HOSTSPACE_END(PluginStaticData.h)
+
+#endif