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