changeset 50:b907557b2fb9

* Add a structure for API versioning

--- a/examples/plugins.cpp	Mon Feb 26 18:08:48 2007 +0000
+++ b/examples/plugins.cpp	Tue Feb 27 12:48:17 2007 +0000
@@ -47,8 +47,11 @@
 static Vamp::PluginAdapter<PercussionOnsetDetector> percussionOnsetAdapter;
 static Vamp::PluginAdapter<AmplitudeFollower> amplitudeAdapter;
 
-const VampPluginDescriptor *vampGetPluginDescriptor(unsigned int index)
+const VampPluginDescriptor *vampGetPluginDescriptor(unsigned int version,
+                                                    unsigned int index)
 {
+    if (version < 1) return 0;
+
     switch (index) {
     case  0: return zeroCrossingAdapter.getDescriptor();
     case  1: return spectralCentroidAdapter.getDescriptor();

--- a/host/vamp-simple-host.cpp	Mon Feb 26 18:08:48 2007 +0000
+++ b/host/vamp-simple-host.cpp	Tue Feb 27 12:48:17 2007 +0000
@@ -162,7 +162,7 @@
     int plugnumber = -1;
     const VampPluginDescriptor *descriptor = 0;
 
-    while ((descriptor = fn(index))) {
+    while ((descriptor = fn(VAMP_API_VERSION, index))) {
 
         Vamp::PluginHostAdapter plugin(descriptor, 48000);
         cerr << argv[0] << ": Plugin " << (index+1)
@@ -191,7 +191,7 @@
         }
     }
 
-    descriptor = fn(plugnumber);
+    descriptor = fn(VAMP_API_VERSION, plugnumber);
     if (!descriptor) {
         DLCLOSE(libraryHandle);
         return 0;
@@ -400,11 +400,12 @@
                     cerr << "\n  " << e->d_name << ":" << endl;
                     int index = 0;
                     const VampPluginDescriptor *descriptor = 0;
-                    while ((descriptor = fn(index))) {
+                    while ((descriptor = fn(VAMP_API_VERSION, index))) {
                         Vamp::PluginHostAdapter plugin(descriptor, 48000);
                         char c = char('A' + index);
                         if (c > 'Z') c = char('a' + (index - 26));
-                        cerr << "    [" << c << "] "
+                        cerr << "    [" << c << "] [v"
+                             << plugin.getVampApiVersion() << "] "
                              << plugin.getName()
                              << ", \"" << plugin.getIdentifier() << "\""
                              << " [" << plugin.getMaker()

--- a/vamp-sdk/PluginAdapter.cpp	Mon Feb 26 18:08:48 2007 +0000
+++ b/vamp-sdk/PluginAdapter.cpp	Tue Feb 27 12:48:17 2007 +0000
@@ -60,9 +60,20 @@
 
     Plugin *plugin = createPlugin(48000);
 
+    if (plugin->getVampApiVersion() != VAMP_API_VERSION) {
+        std::cerr << "Vamp::PluginAdapterBase::getDescriptor: ERROR: "
+                  << "Plugin object API version "
+                  << plugin->getVampApiVersion()
+                  << " does not match actual API version "
+                  << VAMP_API_VERSION << std::endl;
+        delete plugin;
+        return 0;
+    }
+
     m_parameters = plugin->getParameterDescriptors();
     m_programs = plugin->getPrograms();
-    
+
+    m_descriptor.vampApiVersion = plugin->getVampApiVersion();
     m_descriptor.identifier = strdup(plugin->getIdentifier().c_str());
     m_descriptor.name = strdup(plugin->getName().c_str());
     m_descriptor.description = strdup(plugin->getDescription().c_str());

--- a/vamp-sdk/PluginBase.h	Mon Feb 26 18:08:48 2007 +0000
+++ b/vamp-sdk/PluginBase.h	Tue Feb 27 12:48:17 2007 +0000
@@ -61,6 +61,11 @@
     virtual ~PluginBase() { }
 
     /**
+     * Get the Vamp API compatibility level of the plugin.
+     */
+    virtual unsigned int getVampApiVersion() const { return 1; }
+
+    /**
      * Get the computer-usable name of the plugin.  This should be
      * reasonably short and contain no whitespace or punctuation
      * characters.  It may only contain the characters [a-zA-Z0-9_].

--- a/vamp-sdk/PluginHostAdapter.cpp	Mon Feb 26 18:08:48 2007 +0000
+++ b/vamp-sdk/PluginHostAdapter.cpp	Tue Feb 27 12:48:17 2007 +0000
@@ -140,6 +140,12 @@
     }
 }
 
+unsigned int
+PluginHostAdapter::getVampApiVersion() const
+{
+    return m_descriptor->vampApiVersion;
+}
+
 std::string
 PluginHostAdapter::getIdentifier() const
 {

--- a/vamp-sdk/PluginHostAdapter.h	Mon Feb 26 18:08:48 2007 +0000
+++ b/vamp-sdk/PluginHostAdapter.h	Tue Feb 27 12:48:17 2007 +0000
@@ -59,6 +59,7 @@
 
     InputDomain getInputDomain() const;
 
+    unsigned int getVampApiVersion() const;
     std::string getIdentifier() const;
     std::string getName() const;
     std::string getDescription() const;

--- a/vamp/vamp.h	Mon Feb 26 18:08:48 2007 +0000
+++ b/vamp/vamp.h	Tue Feb 27 12:48:17 2007 +0000
@@ -58,12 +58,15 @@
 #endif
 
 /** 
- * Plugin API version. Incompatible changes to the API may be expected
- * prior to version 1.0.
+ * Plugin API version.  This is incremented when a change is made that
+ * changes the binary layout of the descriptor records.  When this
+ * happens, there should be a mechanism for retaining compatibility
+ * with older hosts and/or plugins.
+ *
+ * See also the vampApiVersion field in the plugin descriptor, and the
+ * hostApiVersion argument to the vampGetPluginDescriptor function.
  */
-#define VAMP_API_VERSION "1.0"
-#define VAMP_API_VERSION_MAJOR 1
-#define VAMP_API_VERSION_MINOR 0
+#define VAMP_API_VERSION 1
 
 typedef struct _VampParameterDescriptor
 {
@@ -202,6 +205,9 @@
 
 typedef struct _VampPluginDescriptor
 {
+    /** API version with which this descriptor is compatible. */
+    unsigned int vampApiVersion;
+
     /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
     const char *identifier;
 
@@ -308,11 +314,23 @@
 
 /** Get the descriptor for a given plugin index in this library.
     Return NULL if the index is outside the range of valid indices for
-    this plugin library. */
-const VampPluginDescriptor *vampGetPluginDescriptor(unsigned int index);
+    this plugin library.
+
+    The hostApiVersion argument tells the library code the highest
+    Vamp API version supported by the host.  The function should
+    return a plugin descriptor compatible with the highest API version
+    supported by the library that is no higher than that supported by
+    the host.  Provided the descriptor has the correct vampApiVersion
+    field for its actual compatibility level, the host should be able
+    to do the right thing with it: use it if possible, discard it
+    otherwise.
+*/
+const VampPluginDescriptor *vampGetPluginDescriptor
+    (unsigned int hostApiVersion, unsigned int index);
 
 /** Function pointer type for vampGetPluginDescriptor. */
-typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)(unsigned int);
+typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
+    (unsigned int, unsigned int);
 
 #ifdef __cplusplus
 }