# HG changeset patch # User cannam # Date 1172580497 0 # Node ID b907557b2fb9579bcd48ea8d0b7cb2b3892f409a # Parent aa64a46320d475bed6a5ecad4dc1407805bed677 * Add a structure for API versioning diff -r aa64a46320d4 -r b907557b2fb9 examples/plugins.cpp --- 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 percussionOnsetAdapter; static Vamp::PluginAdapter 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(); diff -r aa64a46320d4 -r b907557b2fb9 host/vamp-simple-host.cpp --- 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() diff -r aa64a46320d4 -r b907557b2fb9 vamp-sdk/PluginAdapter.cpp --- 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()); diff -r aa64a46320d4 -r b907557b2fb9 vamp-sdk/PluginBase.h --- 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_]. diff -r aa64a46320d4 -r b907557b2fb9 vamp-sdk/PluginHostAdapter.cpp --- 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 { diff -r aa64a46320d4 -r b907557b2fb9 vamp-sdk/PluginHostAdapter.h --- 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; diff -r aa64a46320d4 -r b907557b2fb9 vamp/vamp.h --- 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 }