Mercurial > hg > vamp-plugin-sdk
changeset 256:3d98dd2ba0d6
* Add documentation about backward compatibility
| author | cannam |
|---|---|
| date | Fri, 14 Nov 2008 10:59:48 +0000 |
| parents | 88ef5ffdbe8d |
| children | f80e34e36a79 |
| files | README README.compat |
| diffstat | 2 files changed, 102 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/README Wed Nov 12 14:11:01 2008 +0000 +++ b/README Fri Nov 14 10:59:48 2008 +0000 @@ -10,9 +10,12 @@ to produce descriptive output (measurements or semantic observations). This is version 2.0 of the Vamp plugin Software Development Kit. + Plugins and hosts built with this SDK are binary compatible with those -built using version 1.0 of the SDK. See CHANGELOG for a list of the -changes in this release. +built using version 1.0 of the SDK, with certain restrictions. See +the file README.compat for more details. + +See the file CHANGELOG for a list of the changes in this release. A documentation guide to writing plugins using the Vamp SDK can be found at http://www.vamp-plugins.org/guide.pdf .
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.compat Fri Nov 14 10:59:48 2008 +0000 @@ -0,0 +1,97 @@ + +Backward Compatibility Statement for Vamp Plugin SDK version 2.0 +================================================================ + +Plugin binary compatibility +--------------------------- +Version 2.0 of the Vamp plugin binary interface is backward compatible +with version 1.0. + +A plugin that was compiled and (statically) linked using version 1.x +of the SDK should load and run without modification in a host that was +compiled and linked using version 2.0 of the SDK. + +A plugin that was compiled and (statically) linked using version 2.0 +of the SDK should load and run in a host that was compiled and linked +using version 1.x of the SDK. However, the 1.x host will be unable to +see any durations that the plugin specifies for its returned features, +as there was no support for duration in version 1 of the Vamp plugin +interface. + +Plugin/host version discrimination +---------------------------------- +A Vamp plugin library receives the Vamp SDK version number for the +host as the first argument to its vampGetPluginDescriptor function. +It may use this information to provide different behaviour depending +on the version of the host. + +For example, the plugin may structure its outputs differently in older +hosts that do not support feature duration. Or, if the plugins rely +on version 2.0 features, the library could make itself invisible to +older hosts (returning no plugin descriptors). + +The version argument passed to vampGetPluginDescriptor will be 1 for +Vamp 1.x hosts or 2 for Vamp 2.0 hosts. (Plugin libraries should +behave as for version 2 if passed a version number greater than 2.) + +Plugin SDK library compatibility +-------------------------------- +For plugin code, version 2.0 of the Vamp plugin SDK is source +compatible but not library ABI compatible with version 1.x. + +Plugins written for version 1.x should compile and link without +modification using version 2.0. Plugins dynamically linked against +version 1.x SDK libraries will need to be rebuilt if they are to work +with version 2.0 libraries. To avoid dynamic library resolution +issues, it is generally preferable to link the SDK statically when +distributing binary plugins. + +Host SDK library compatibility +------------------------------ +For host code, version 2.0 of the Vamp plugin SDK is neither source +nor binary compatible with version 1.x. + +The host SDK header include location has moved for version 2.0; hosts +should now only include headers from the vamp-hostsdk/ include +directory -- the vamp-sdk/ directory is reserved for inclusion in +plugin code only. There is also no longer a separate subdirectory for +hostext headers. + +Hosts written for version 1.x will therefore need to have their +#include directives updated as follows: + + Old New + + <vamp-sdk/PluginBase.h> <vamp-hostsdk/PluginBase.h> + <vamp-sdk/Plugin.h> <vamp-hostsdk/Plugin.h> + <vamp-sdk/RealTime.h> <vamp-hostsdk/RealTime.h> + <vamp-sdk/hostext/PluginLoader.h> <vamp-hostsdk/PluginLoader.h> + <vamp-sdk/hostext/PluginBufferingAdapter.h> <vamp-hostsdk/PluginBufferingAdapter.h> + <vamp-sdk/hostext/PluginChannelAdapter.h> <vamp-hostsdk/PluginChannelAdapter.h> + <vamp-sdk/hostext/PluginInputDomainAdapter.h> <vamp-hostsdk/PluginInputDomainAdapter.h> + <vamp-sdk/PluginHostAdapter.h> <vamp-hostsdk/PluginHostAdapter.h> + +For most hosts, these should be the only changes necessary; the actual +code remains the same. + +Hosts that incorporate plugin code +---------------------------------- +One of the changes in this version of the SDK is that classes compiled +into plugins are now internally enclosed in a special C++ namespace +(the _VampPlugin namespace) to avoid any confusion between host and +plugin namespaces in unusual linkage situations. This is handled +transparently in most circumstances, and neither plugin nor host +authors will normally need to care about it. + +However, hosts that directly incorporate code from plugins, for +example to provide functionality that is the same as those plugins +without having to explicitly load them, may find that they can no +longer resolve plugin functions at link time because of this namespace +mismatch. To avoid this, the host build process should define the +preprocessor flag VAMP_NO_PLUGIN_NAMESPACE when compiling the plugin +code to ensure that both host and plugin code exist at the same level +of namespace. + +(If your host does this, why not make it load the plugins dynamically +instead using the normal Vamp plugin loader method? There are many +advantages to that.)