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

Update Vamp plugin SDK to 2.5

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/vamp-plugin-sdk-2.5/README.compat	Thu May 09 10:52:46 2013 +0100
@@ -0,0 +1,102 @@
+
+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.)
+