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