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