annotate README.compat @ 256:3d98dd2ba0d6

* Add documentation about backward compatibility

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 classes compiled
into plugins are now internally enclosed in a special C++ namespace
(the _VampPlugin namespace) to avoid any confusion between host and
plugin namespaces in unusual linkage situations.  This is handled
transparently in most circumstances, and neither plugin nor host
authors will normally need to care 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, may find that they can no
longer resolve plugin functions at link time because of this namespace
mismatch.  To avoid this, the host build process should define the
preprocessor flag VAMP_NO_PLUGIN_NAMESPACE when compiling the plugin
code to ensure that both host and plugin code exist at the same level
of 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.)