annotate src/vamp-plugin-sdk-2.5/README.compat @ 108:1813f30f2f15

Update Vamp plugin SDK to 2.5

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.)