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