annotate vamp-hostsdk/RequestResponse.h @ 456:86624d166f88 outputid-string-in-featureset

Introduce ListResponse type as well
author Chris Cannam
date Mon, 19 Sep 2016 14:10:19 +0100
parents 5c07a86abddd
children eb30742e5e43
rev   line source
Chris@423 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
Chris@423 2
Chris@423 3 /*
Chris@423 4 Vamp
Chris@423 5
Chris@423 6 An API for audio analysis and feature extraction plugins.
Chris@423 7
Chris@423 8 Centre for Digital Music, Queen Mary, University of London.
Chris@423 9 Copyright 2006-2016 Chris Cannam and QMUL.
Chris@423 10
Chris@423 11 Permission is hereby granted, free of charge, to any person
Chris@423 12 obtaining a copy of this software and associated documentation
Chris@423 13 files (the "Software"), to deal in the Software without
Chris@423 14 restriction, including without limitation the rights to use, copy,
Chris@423 15 modify, merge, publish, distribute, sublicense, and/or sell copies
Chris@423 16 of the Software, and to permit persons to whom the Software is
Chris@423 17 furnished to do so, subject to the following conditions:
Chris@423 18
Chris@423 19 The above copyright notice and this permission notice shall be
Chris@423 20 included in all copies or substantial portions of the Software.
Chris@423 21
Chris@423 22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
Chris@423 23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
Chris@423 24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
Chris@423 25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
Chris@423 26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
Chris@423 27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
Chris@423 28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Chris@423 29
Chris@423 30 Except as contained in this notice, the names of the Centre for
Chris@423 31 Digital Music; Queen Mary, University of London; and Chris Cannam
Chris@423 32 shall not be used in advertising or otherwise to promote the sale,
Chris@423 33 use or other dealings in this Software without prior written
Chris@423 34 authorization.
Chris@423 35 */
Chris@423 36
Chris@430 37 #ifndef VAMP_REQUEST_RESPONSE_H
Chris@430 38 #define VAMP_REQUEST_RESPONSE_H
Chris@423 39
Chris@423 40 #include "PluginStaticData.h"
Chris@423 41 #include "PluginConfiguration.h"
Chris@423 42
Chris@423 43 #include "hostguard.h"
Chris@423 44
Chris@423 45 #include <map>
Chris@423 46 #include <string>
Chris@423 47
Chris@429 48 _VAMP_SDK_HOSTSPACE_BEGIN(RequestResponse.h)
Chris@423 49
Chris@423 50 namespace Vamp {
Chris@423 51
Chris@423 52 class Plugin;
Chris@423 53
Chris@423 54 namespace HostExt {
Chris@423 55
Chris@423 56 /**
Chris@456 57 * \class ListResponse RequestResponse.h <vamp-hostsdk/RequestResponse.h>
Chris@456 58 *
Chris@456 59 * Vamp::HostExt::ListResponse is a structure containing the
Chris@456 60 * information returned by PluginLoader when asked to list static
Chris@456 61 * information about the available plugins.
Chris@456 62 *
Chris@456 63 * \see PluginLoader::listPluginData, PluginStaticData
Chris@456 64 *
Chris@456 65 * \note This class was introduced in version 2.7 of the Vamp plugin
Chris@456 66 * SDK, along with the PluginLoader method that returns this structure.
Chris@456 67 */
Chris@456 68 struct ListResponse
Chris@456 69 {
Chris@456 70 ListResponse() { } // empty by default
Chris@456 71
Chris@456 72 std::vector<PluginStaticData> pluginData;
Chris@456 73 };
Chris@456 74
Chris@456 75 /**
Chris@429 76 * \class LoadRequest RequestResponse.h <vamp-hostsdk/RequestResponse.h>
Chris@423 77 *
Chris@423 78 * Vamp::HostExt::LoadRequest is a structure containing the
Chris@423 79 * information necessary to load a plugin. When a request is made to
Chris@423 80 * load a plugin using a LoadRequest, the response is typically
Chris@423 81 * returned in a LoadResponse structure.
Chris@423 82 *
Chris@423 83 * \see LoadResponse
Chris@423 84 *
Chris@423 85 * \note This class was introduced in version 2.7 of the Vamp plugin
Chris@423 86 * SDK, along with the PluginLoader method that accepts this structure
Chris@423 87 * rather than accepting its elements individually.
Chris@423 88 */
Chris@423 89 struct LoadRequest
Chris@423 90 {
Chris@423 91 LoadRequest() : // invalid request by default
Chris@423 92 inputSampleRate(0.f),
Chris@423 93 adapterFlags(0) { }
Chris@425 94
Chris@425 95 /**
Chris@425 96 * PluginKey is a string type that is used to identify a plugin
Chris@425 97 * uniquely within the scope of "the current system". For further
Chris@425 98 * details \see PluginLoader::PluginKey.
Chris@425 99 */
Chris@425 100 typedef std::string PluginKey;
Chris@425 101
Chris@425 102 /**
Chris@425 103 * The identifying key for the plugin to be loaded.
Chris@425 104 */
Chris@425 105 PluginKey pluginKey;
Chris@425 106
Chris@425 107 /**
Chris@425 108 * Sample rate to be passed to the plugin's constructor.
Chris@425 109 */
Chris@423 110 float inputSampleRate;
Chris@425 111
Chris@425 112 /**
Chris@425 113 * A bitwise OR of the values in the PluginLoader::AdapterFlags
Chris@425 114 * enumeration, indicating under which circumstances an adapter
Chris@425 115 * should be used to wrap the original plugin. If adapterFlags is
Chris@425 116 * 0, no optional adapters will be used.
Chris@425 117 *
Chris@425 118 * \see PluginLoader::AdapterFlags, PluginLoader::loadPlugin
Chris@425 119 */
Chris@425 120 int adapterFlags;
Chris@423 121 };
Chris@423 122
Chris@423 123 /**
Chris@429 124 * \class LoadResponse RequestResponse.h <vamp-hostsdk/RequestResponse.h>
Chris@423 125 *
Chris@423 126 * Vamp::HostExt::LoadResponse is a structure containing the
Chris@423 127 * information returned by PluginLoader when asked to load a plugin
Chris@423 128 * using a LoadRequest.
Chris@423 129 *
Chris@423 130 * If the plugin could not be loaded, the plugin field will be 0.
Chris@423 131 *
Chris@423 132 * The caller takes ownership of the plugin contained here, which
Chris@423 133 * should be deleted (using the standard C++ delete keyword) after
Chris@423 134 * use.
Chris@423 135 *
Chris@423 136 * \see LoadRequest
Chris@423 137 *
Chris@423 138 * \note This class was introduced in version 2.7 of the Vamp plugin
Chris@423 139 * SDK, along with the PluginLoader method that returns this structure.
Chris@423 140 */
Chris@423 141 struct LoadResponse
Chris@423 142 {
Chris@423 143 LoadResponse() : // invalid (failed) response by default
Chris@423 144 plugin(0) { }
Chris@425 145
Chris@425 146 /**
Chris@425 147 * A pointer to the loaded plugin, or 0 if loading failed. Caller
Chris@425 148 * takes ownership of the plugin and must delete it after use.
Chris@425 149 */
Chris@423 150 Plugin *plugin;
Chris@425 151
Chris@425 152 /**
Chris@425 153 * The static data associated with the loaded plugin, that is, all
Chris@425 154 * information about it that does not depend on its configuration
Chris@425 155 * (parameters, programs, initialisation parameters). The contents
Chris@425 156 * of this structure are only valid if plugin is non-0.
Chris@426 157 *
Chris@426 158 * Much of the data in here is duplicated with the plugin itself.
Chris@425 159 */
Chris@423 160 PluginStaticData staticData;
Chris@425 161
Chris@425 162 /**
Chris@425 163 * The default configuration for this plugin, that is, default
Chris@425 164 * values for parameters etc. The contents of this structure are
Chris@425 165 * only valid if plugin is non-0.
Chris@425 166 */
Chris@423 167 PluginConfiguration defaultConfiguration;
Chris@423 168 };
Chris@423 169
Chris@430 170 /**
Chris@430 171 * \class ConfigurationRequest RequestResponse.h <vamp-hostsdk/RequestResponse.h>
Chris@430 172 *
Chris@430 173 * A wrapper for a plugin pointer and PluginConfiguration, bundling up
Chris@430 174 * the data needed to configure a plugin after it has been loaded.
Chris@430 175 *
Chris@430 176 * \see PluginConfiguration, ConfigurationResponse, LoadRequest, LoadResponse
Chris@431 177 *
Chris@431 178 * \note This class was introduced in version 2.7 of the Vamp plugin
Chris@431 179 * SDK, along with the PluginLoader method that returns this structure.
Chris@430 180 */
Chris@430 181 struct ConfigurationRequest
Chris@430 182 {
Chris@430 183 public:
Chris@430 184 ConfigurationRequest() : // invalid request by default
Chris@430 185 plugin(0) { }
Chris@430 186
Chris@430 187 Plugin *plugin;
Chris@430 188 PluginConfiguration configuration;
Chris@430 189 };
Chris@430 190
Chris@430 191 /**
Chris@430 192 * \class ConfigurationResponse RequestResponse.h <vamp-hostsdk/RequestResponse.h>
Chris@430 193 *
Chris@430 194 * The return value from a configuration request (i.e. setting the
Chris@430 195 * parameters and initialising the plugin). If the configuration was
Chris@430 196 * successful, the output list will contain the final
Chris@430 197 * post-initialisation output descriptors. If configuration failed,
Chris@430 198 * the output list will be empty.
Chris@430 199 *
Chris@430 200 * \see PluginConfiguration, ConfigurationRequest, LoadRequest, LoadResponse
Chris@431 201 *
Chris@431 202 * \note This class was introduced in version 2.7 of the Vamp plugin
Chris@431 203 * SDK, along with the PluginLoader method that returns this structure.
Chris@430 204 */
Chris@430 205 struct ConfigurationResponse
Chris@430 206 {
Chris@430 207 public:
Chris@455 208 ConfigurationResponse() : // failed by default
Chris@455 209 plugin(0) { }
Chris@430 210
Chris@455 211 Plugin *plugin;
Chris@430 212 Plugin::OutputList outputs;
Chris@430 213 };
Chris@430 214
Chris@431 215 /**
Chris@431 216 * \class ProcessRequest RequestResponse.h <vamp-hostsdk/RequestResponse.h>
Chris@431 217 *
Chris@431 218 * A structure that bundles the necessary data for making a process
Chris@431 219 * call: plugin, input buffers, and timestamp. Caller retains
Chris@431 220 * ownership of the plugin, but the buffers are passed "by value" to
Chris@431 221 * avoid ownership concerns.
Chris@431 222 *
Chris@431 223 * \see Plugin::process()
Chris@431 224 *
Chris@431 225 * \note This class was introduced in version 2.7 of the Vamp plugin
Chris@431 226 * SDK, but it is not currently used by the SDK. It is supplied as a
Chris@431 227 * convenience for code using the SDK, and for symmetry with the load
Chris@431 228 * and configuration request structs.
Chris@431 229 */
Chris@431 230 struct ProcessRequest
Chris@431 231 {
Chris@431 232 public:
Chris@431 233 ProcessRequest() : // invalid by default
Chris@431 234 plugin(0) { }
Chris@431 235
Chris@431 236 Plugin *plugin;
Chris@432 237 std::vector<std::vector<float> > inputBuffers;
Chris@431 238 RealTime timestamp;
Chris@431 239 };
Chris@431 240
Chris@431 241 /**
Chris@431 242 * \class ProcessResponse RequestResponse.h <vamp-hostsdk/RequestResponse.h>
Chris@431 243 *
Chris@431 244 * A structure that bundles the data returned by a process call and by
Chris@431 245 * Plugin::getRemainingFeatures(). This is simply a FeatureSet
Chris@454 246 * wrapper that happens to reference the plugin as well.
Chris@431 247 *
Chris@431 248 * \see Plugin::process(), Plugin::getRemainingFeatures()
Chris@431 249 *
Chris@431 250 * \note This class was introduced in version 2.7 of the Vamp plugin
Chris@431 251 * SDK, but it is not currently used by the SDK. It is supplied as a
Chris@431 252 * convenience for code using the SDK, and for symmetry with the load
Chris@431 253 * and configuration request structs.
Chris@431 254 */
Chris@431 255 struct ProcessResponse
Chris@431 256 {
Chris@431 257 public:
Chris@454 258 ProcessResponse() : // invalid by default
Chris@454 259 plugin(0) { }
Chris@431 260
Chris@454 261 Plugin *plugin;
Chris@431 262 Plugin::FeatureSet features;
Chris@431 263 };
Chris@431 264
Chris@455 265 /**
Chris@455 266 * \class FinishRequest RequestResponse.h <vamp-hostsdk/RequestResponse.h>
Chris@455 267 *
Chris@455 268 * A structure that bundles the necessary data for finishing
Chris@455 269 * processing, i.e. calling getRemainingFeatures(). This consists only
Chris@455 270 * of the plugin pointer. Caller retains ownership of the plugin.
Chris@455 271 *
Chris@455 272 * \see Plugin::getRemainingFeatures()
Chris@455 273 *
Chris@455 274 * \note This class was introduced in version 2.7 of the Vamp plugin
Chris@455 275 * SDK, but it is not currently used by the SDK. It is supplied as a
Chris@455 276 * convenience for code using the SDK, and for symmetry with the load
Chris@455 277 * and configuration request structs.
Chris@455 278 *
Chris@455 279 * \note The response to a finish request (getRemainingFeatures()) is
Chris@455 280 * a ProcessResponse, just as it is for a process request.
Chris@455 281 */
Chris@455 282 struct FinishRequest
Chris@455 283 {
Chris@455 284 public:
Chris@455 285 FinishRequest() : // invalid by default
Chris@455 286 plugin(0) { }
Chris@455 287
Chris@455 288 Plugin *plugin;
Chris@455 289 };
Chris@455 290
Chris@423 291 }
Chris@423 292
Chris@423 293 }
Chris@423 294
Chris@429 295 _VAMP_SDK_HOSTSPACE_END(RequestResponse.h)
Chris@423 296
Chris@423 297 #endif