annotate README.compat @ 467:bd8484e19353 vampipe

Fix long-standing memory leaks (parameter descriptors and feature list container) in plugin adapter
author Chris Cannam
date Fri, 14 Oct 2016 09:32:11 +0100
parents 53b0e7557c52
children
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@263 79 One of the changes in this version of the SDK is that separate
cannam@263 80 top-level C++ namespaces are used for classes compiled into plugins
cannam@263 81 (the _VampPlugin namespace) and hosts (the _VampHost namespace), to
cannam@263 82 avoid any confusion between host and plugin namespaces in unusual
cannam@266 83 linkage situations (as the host and plugin SDKs contain many of the
cannam@266 84 same classes, there is a risk that the wrong class may be picked up by
cannam@266 85 a stupid dynamic linker in cases where the host and plugin SDK
cannam@266 86 versions do not match). This additional namespace is added and opened
cannam@266 87 silently in a manner that is transparent in most circumstances, and
cannam@266 88 neither plugin nor host authors will normally need to know about it.
cannam@256 89
cannam@256 90 However, hosts that directly incorporate code from plugins, for
cannam@256 91 example to provide functionality that is the same as those plugins
cannam@265 92 without having to explicitly load them, will find that they cannot
cannam@265 93 resolve plugin symbols at link time because of this namespace
cannam@265 94 mismatch. To avoid this, you may define the preprocessor symbol
cannam@265 95 _VAMP_PLUGIN_IN_HOST_NAMESPACE when compiling the plugin code in the
cannam@265 96 context of the host, to ensure that both host and plugin code exist
cannam@265 97 within the same namespace.
cannam@256 98
cannam@256 99 (If your host does this, why not make it load the plugins dynamically
cannam@256 100 instead using the normal Vamp plugin loader method? There are many
cannam@256 101 advantages to that.)
cannam@263 102