Chris@23: Chris@23: Backward Compatibility Statement for Vamp Plugin SDK version 2.0 Chris@23: ================================================================ Chris@23: Chris@23: Plugin binary compatibility Chris@23: --------------------------- Chris@23: Version 2.0 of the Vamp plugin binary interface is backward compatible Chris@23: with version 1.0. Chris@23: Chris@23: A plugin that was compiled and (statically) linked using version 1.x Chris@23: of the SDK should load and run without modification in a host that was Chris@23: compiled and linked using version 2.0 of the SDK. Chris@23: Chris@23: A plugin that was compiled and (statically) linked using version 2.0 Chris@23: of the SDK should load and run in a host that was compiled and linked Chris@23: using version 1.x of the SDK. However, the 1.x host will be unable to Chris@23: see any durations that the plugin specifies for its returned features, Chris@23: as there was no support for duration in version 1 of the Vamp plugin Chris@23: interface. Chris@23: Chris@23: Plugin/host version discrimination Chris@23: ---------------------------------- Chris@23: A Vamp plugin library receives the Vamp SDK version number for the Chris@23: host as the first argument to its vampGetPluginDescriptor function. Chris@23: It may use this information to provide different behaviour depending Chris@23: on the version of the host. Chris@23: Chris@23: For example, the plugin may structure its outputs differently in older Chris@23: hosts that do not support feature duration. Or, if the plugins rely Chris@23: on version 2.0 features, the library could make itself invisible to Chris@23: older hosts (returning no plugin descriptors). Chris@23: Chris@23: The version argument passed to vampGetPluginDescriptor will be 1 for Chris@23: Vamp 1.x hosts or 2 for Vamp 2.0 hosts. (Plugin libraries should Chris@23: behave as for version 2 if passed a version number greater than 2.) Chris@23: Chris@23: Plugin SDK library compatibility Chris@23: -------------------------------- Chris@23: For plugin code, version 2.0 of the Vamp plugin SDK is source Chris@23: compatible but not library ABI compatible with version 1.x. Chris@23: Chris@23: Plugins written for version 1.x should compile and link without Chris@23: modification using version 2.0. Plugins dynamically linked against Chris@23: version 1.x SDK libraries will need to be rebuilt if they are to work Chris@23: with version 2.0 libraries. To avoid dynamic library resolution Chris@23: issues, it is generally preferable to link the SDK statically when Chris@23: distributing binary plugins. Chris@23: Chris@23: Host SDK library compatibility Chris@23: ------------------------------ Chris@23: For host code, version 2.0 of the Vamp plugin SDK is neither source Chris@23: nor binary compatible with version 1.x. Chris@23: Chris@23: The host SDK header include location has moved for version 2.0; hosts Chris@23: should now only include headers from the vamp-hostsdk/ include Chris@23: directory -- the vamp-sdk/ directory is reserved for inclusion in Chris@23: plugin code only. There is also no longer a separate subdirectory for Chris@23: hostext headers. Chris@23: Chris@23: Hosts written for version 1.x will therefore need to have their Chris@23: #include directives updated as follows: Chris@23: Chris@23: Old New Chris@23: Chris@23: Chris@23: Chris@23: Chris@23: Chris@23: Chris@23: Chris@23: Chris@23: Chris@23: Chris@23: For most hosts, these should be the only changes necessary; the actual Chris@23: code remains the same. Chris@23: Chris@23: Hosts that incorporate plugin code Chris@23: ---------------------------------- Chris@23: One of the changes in this version of the SDK is that separate Chris@23: top-level C++ namespaces are used for classes compiled into plugins Chris@23: (the _VampPlugin namespace) and hosts (the _VampHost namespace), to Chris@23: avoid any confusion between host and plugin namespaces in unusual Chris@23: linkage situations (as the host and plugin SDKs contain many of the Chris@23: same classes, there is a risk that the wrong class may be picked up by Chris@23: a stupid dynamic linker in cases where the host and plugin SDK Chris@23: versions do not match). This additional namespace is added and opened Chris@23: silently in a manner that is transparent in most circumstances, and Chris@23: neither plugin nor host authors will normally need to know about it. Chris@23: Chris@23: However, hosts that directly incorporate code from plugins, for Chris@23: example to provide functionality that is the same as those plugins Chris@23: without having to explicitly load them, will find that they cannot Chris@23: resolve plugin symbols at link time because of this namespace Chris@23: mismatch. To avoid this, you may define the preprocessor symbol Chris@23: _VAMP_PLUGIN_IN_HOST_NAMESPACE when compiling the plugin code in the Chris@23: context of the host, to ensure that both host and plugin code exist Chris@23: within the same namespace. Chris@23: Chris@23: (If your host does this, why not make it load the plugins dynamically Chris@23: instead using the normal Vamp plugin loader method? There are many Chris@23: advantages to that.) Chris@23: