annotate README.compat @ 256:3d98dd2ba0d6

* Add documentation about backward compatibility
author cannam
date Fri, 14 Nov 2008 10:59:48 +0000
parents
children 4454843ff384
rev   line source
cannam@256 1
cannam@256 2 Backward Compatibility Statement for Vamp Plugin SDK version 2.0
cannam@256 3 ================================================================
cannam@256 4
cannam@256 5 Plugin binary compatibility
cannam@256 6 ---------------------------
cannam@256 7 Version 2.0 of the Vamp plugin binary interface is backward compatible
cannam@256 8 with version 1.0.
cannam@256 9
cannam@256 10 A plugin that was compiled and (statically) linked using version 1.x
cannam@256 11 of the SDK should load and run without modification in a host that was
cannam@256 12 compiled and linked using version 2.0 of the SDK.
cannam@256 13
cannam@256 14 A plugin that was compiled and (statically) linked using version 2.0
cannam@256 15 of the SDK should load and run in a host that was compiled and linked
cannam@256 16 using version 1.x of the SDK. However, the 1.x host will be unable to
cannam@256 17 see any durations that the plugin specifies for its returned features,
cannam@256 18 as there was no support for duration in version 1 of the Vamp plugin
cannam@256 19 interface.
cannam@256 20
cannam@256 21 Plugin/host version discrimination
cannam@256 22 ----------------------------------
cannam@256 23 A Vamp plugin library receives the Vamp SDK version number for the
cannam@256 24 host as the first argument to its vampGetPluginDescriptor function.
cannam@256 25 It may use this information to provide different behaviour depending
cannam@256 26 on the version of the host.
cannam@256 27
cannam@256 28 For example, the plugin may structure its outputs differently in older
cannam@256 29 hosts that do not support feature duration. Or, if the plugins rely
cannam@256 30 on version 2.0 features, the library could make itself invisible to
cannam@256 31 older hosts (returning no plugin descriptors).
cannam@256 32
cannam@256 33 The version argument passed to vampGetPluginDescriptor will be 1 for
cannam@256 34 Vamp 1.x hosts or 2 for Vamp 2.0 hosts. (Plugin libraries should
cannam@256 35 behave as for version 2 if passed a version number greater than 2.)
cannam@256 36
cannam@256 37 Plugin SDK library compatibility
cannam@256 38 --------------------------------
cannam@256 39 For plugin code, version 2.0 of the Vamp plugin SDK is source
cannam@256 40 compatible but not library ABI compatible with version 1.x.
cannam@256 41
cannam@256 42 Plugins written for version 1.x should compile and link without
cannam@256 43 modification using version 2.0. Plugins dynamically linked against
cannam@256 44 version 1.x SDK libraries will need to be rebuilt if they are to work
cannam@256 45 with version 2.0 libraries. To avoid dynamic library resolution
cannam@256 46 issues, it is generally preferable to link the SDK statically when
cannam@256 47 distributing binary plugins.
cannam@256 48
cannam@256 49 Host SDK library compatibility
cannam@256 50 ------------------------------
cannam@256 51 For host code, version 2.0 of the Vamp plugin SDK is neither source
cannam@256 52 nor binary compatible with version 1.x.
cannam@256 53
cannam@256 54 The host SDK header include location has moved for version 2.0; hosts
cannam@256 55 should now only include headers from the vamp-hostsdk/ include
cannam@256 56 directory -- the vamp-sdk/ directory is reserved for inclusion in
cannam@256 57 plugin code only. There is also no longer a separate subdirectory for
cannam@256 58 hostext headers.
cannam@256 59
cannam@256 60 Hosts written for version 1.x will therefore need to have their
cannam@256 61 #include directives updated as follows:
cannam@256 62
cannam@256 63 Old New
cannam@256 64
cannam@256 65 <vamp-sdk/PluginBase.h> <vamp-hostsdk/PluginBase.h>
cannam@256 66 <vamp-sdk/Plugin.h> <vamp-hostsdk/Plugin.h>
cannam@256 67 <vamp-sdk/RealTime.h> <vamp-hostsdk/RealTime.h>
cannam@256 68 <vamp-sdk/hostext/PluginLoader.h> <vamp-hostsdk/PluginLoader.h>
cannam@256 69 <vamp-sdk/hostext/PluginBufferingAdapter.h> <vamp-hostsdk/PluginBufferingAdapter.h>
cannam@256 70 <vamp-sdk/hostext/PluginChannelAdapter.h> <vamp-hostsdk/PluginChannelAdapter.h>
cannam@256 71 <vamp-sdk/hostext/PluginInputDomainAdapter.h> <vamp-hostsdk/PluginInputDomainAdapter.h>
cannam@256 72 <vamp-sdk/PluginHostAdapter.h> <vamp-hostsdk/PluginHostAdapter.h>
cannam@256 73
cannam@256 74 For most hosts, these should be the only changes necessary; the actual
cannam@256 75 code remains the same.
cannam@256 76
cannam@256 77 Hosts that incorporate plugin code
cannam@256 78 ----------------------------------
cannam@256 79 One of the changes in this version of the SDK is that classes compiled
cannam@256 80 into plugins are now internally enclosed in a special C++ namespace
cannam@256 81 (the _VampPlugin namespace) to avoid any confusion between host and
cannam@256 82 plugin namespaces in unusual linkage situations. This is handled
cannam@256 83 transparently in most circumstances, and neither plugin nor host
cannam@256 84 authors will normally need to care about it.
cannam@256 85
cannam@256 86 However, hosts that directly incorporate code from plugins, for
cannam@256 87 example to provide functionality that is the same as those plugins
cannam@256 88 without having to explicitly load them, may find that they can no
cannam@256 89 longer resolve plugin functions at link time because of this namespace
cannam@256 90 mismatch. To avoid this, the host build process should define the
cannam@256 91 preprocessor flag VAMP_NO_PLUGIN_NAMESPACE when compiling the plugin
cannam@256 92 code to ensure that both host and plugin code exist at the same level
cannam@256 93 of namespace.
cannam@256 94
cannam@256 95 (If your host does this, why not make it load the plugins dynamically
cannam@256 96 instead using the normal Vamp plugin loader method? There are many
cannam@256 97 advantages to that.)