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