annotate vamp-sdk/PluginBase.h @ 50:b907557b2fb9

* Add a structure for API versioning
author cannam
date Tue, 27 Feb 2007 12:48:17 +0000
parents aa64a46320d4
children 74822738965b
rev   line source
cannam@0 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
cannam@0 2
cannam@0 3 /*
cannam@2 4 Vamp
cannam@2 5
cannam@2 6 An API for audio analysis and feature extraction plugins.
cannam@2 7
cannam@0 8 Centre for Digital Music, Queen Mary, University of London.
cannam@2 9 Copyright 2006 Chris Cannam.
cannam@2 10
cannam@2 11 Permission is hereby granted, free of charge, to any person
cannam@2 12 obtaining a copy of this software and associated documentation
cannam@2 13 files (the "Software"), to deal in the Software without
cannam@2 14 restriction, including without limitation the rights to use, copy,
cannam@2 15 modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@2 16 of the Software, and to permit persons to whom the Software is
cannam@2 17 furnished to do so, subject to the following conditions:
cannam@2 18
cannam@2 19 The above copyright notice and this permission notice shall be
cannam@2 20 included in all copies or substantial portions of the Software.
cannam@2 21
cannam@2 22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@2 23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@2 24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@6 25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
cannam@2 26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@2 27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@2 28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@2 29
cannam@2 30 Except as contained in this notice, the names of the Centre for
cannam@2 31 Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@2 32 shall not be used in advertising or otherwise to promote the sale,
cannam@2 33 use or other dealings in this Software without prior written
cannam@2 34 authorization.
cannam@0 35 */
cannam@0 36
cannam@0 37 #ifndef _VAMP_PLUGIN_BASE_H_
cannam@0 38 #define _VAMP_PLUGIN_BASE_H_
cannam@0 39
cannam@0 40 #include <string>
cannam@0 41 #include <vector>
cannam@0 42
cannam@43 43 #define VAMP_SDK_VERSION "1.0"
cannam@24 44
cannam@0 45 namespace Vamp {
cannam@0 46
cannam@0 47 /**
cannam@0 48 * A base class for plugins with optional configurable parameters,
cannam@0 49 * programs, etc.
cannam@0 50 *
cannam@0 51 * This does not provide the necessary interfaces to instantiate or
cannam@0 52 * run a plugin -- that depends on the plugin subclass, as different
cannam@0 53 * plugin types may have quite different operating structures. This
cannam@0 54 * class just specifies the necessary interface to show editable
cannam@0 55 * controls for the plugin to the user.
cannam@0 56 */
cannam@0 57
cannam@0 58 class PluginBase
cannam@0 59 {
cannam@0 60 public:
cannam@20 61 virtual ~PluginBase() { }
cannam@20 62
cannam@0 63 /**
cannam@50 64 * Get the Vamp API compatibility level of the plugin.
cannam@50 65 */
cannam@50 66 virtual unsigned int getVampApiVersion() const { return 1; }
cannam@50 67
cannam@50 68 /**
cannam@0 69 * Get the computer-usable name of the plugin. This should be
cannam@0 70 * reasonably short and contain no whitespace or punctuation
cannam@47 71 * characters. It may only contain the characters [a-zA-Z0-9_].
cannam@47 72 * This is the authoritative way for a program to identify a
cannam@47 73 * plugin within a given library.
cannam@47 74 *
cannam@47 75 * This text may be visible to the user, but it should not be the
cannam@47 76 * main text used to identify a plugin to the user (that will be
cannam@49 77 * the name, below).
cannam@49 78 *
cannam@49 79 * Example: "zero_crossings"
cannam@49 80 */
cannam@49 81 virtual std::string getIdentifier() const = 0;
cannam@49 82
cannam@49 83 /**
cannam@49 84 * Get a human-readable name or title of the plugin. This
cannam@49 85 * should be brief and self-contained, as it may be used to
cannam@49 86 * identify the plugin to the user in isolation (i.e. without also
cannam@49 87 * showing the plugin's "identifier").
cannam@49 88 *
cannam@49 89 * Example: "Zero Crossings"
cannam@0 90 */
cannam@0 91 virtual std::string getName() const = 0;
cannam@0 92
cannam@0 93 /**
cannam@49 94 * Get a human-readable description for the plugin, typically
cannam@49 95 * a line of text that may optionally be displayed in addition
cannam@49 96 * to the plugin's "name". May be empty if the name has said
cannam@49 97 * it all already.
cannam@49 98 *
cannam@49 99 * Example: "Detect and count zero crossing points"
cannam@0 100 */
cannam@0 101 virtual std::string getDescription() const = 0;
cannam@0 102
cannam@0 103 /**
cannam@0 104 * Get the name of the author or vendor of the plugin in
cannam@47 105 * human-readable form. This should be a short identifying text,
cannam@47 106 * as it may be used to label plugins from the same source in a
cannam@47 107 * menu or similar.
cannam@0 108 */
cannam@0 109 virtual std::string getMaker() const = 0;
cannam@0 110
cannam@0 111 /**
cannam@47 112 * Get the copyright statement or licensing summary for the
cannam@47 113 * plugin. This can be an informative text, without the same
cannam@47 114 * presentation constraints as mentioned for getMaker above.
cannam@47 115 */
cannam@47 116 virtual std::string getCopyright() const = 0;
cannam@47 117
cannam@47 118 /**
cannam@0 119 * Get the version number of the plugin.
cannam@0 120 */
cannam@0 121 virtual int getPluginVersion() const = 0;
cannam@0 122
cannam@0 123
cannam@0 124 struct ParameterDescriptor
cannam@0 125 {
cannam@0 126 /**
cannam@0 127 * The name of the parameter, in computer-usable form. Should
cannam@0 128 * be reasonably short, and may only contain the characters
cannam@0 129 * [a-zA-Z0-9_].
cannam@0 130 */
cannam@49 131 std::string identifier;
cannam@49 132
cannam@49 133 /**
cannam@49 134 * The human-readable name of the parameter.
cannam@49 135 */
cannam@0 136 std::string name;
cannam@0 137
cannam@0 138 /**
cannam@49 139 * A human-readable short text describing the parameter. May be
cannam@49 140 * empty if the name has said it all already.
cannam@0 141 */
cannam@0 142 std::string description;
cannam@0 143
cannam@0 144 /**
cannam@0 145 * The unit of the parameter, in human-readable form.
cannam@0 146 */
cannam@0 147 std::string unit;
cannam@0 148
cannam@0 149 /**
cannam@0 150 * The minimum value of the parameter.
cannam@0 151 */
cannam@0 152 float minValue;
cannam@0 153
cannam@0 154 /**
cannam@0 155 * The maximum value of the parameter.
cannam@0 156 */
cannam@0 157 float maxValue;
cannam@0 158
cannam@0 159 /**
cannam@24 160 * The default value of the parameter. The plugin should
cannam@24 161 * ensure that parameters have this value on initialisation
cannam@24 162 * (i.e. the host is not required to explicitly set parameters
cannam@24 163 * if it wants to use their default values).
cannam@0 164 */
cannam@0 165 float defaultValue;
cannam@0 166
cannam@0 167 /**
cannam@0 168 * True if the parameter values are quantized to a particular
cannam@0 169 * resolution.
cannam@0 170 */
cannam@0 171 bool isQuantized;
cannam@0 172
cannam@0 173 /**
cannam@0 174 * Quantization resolution of the parameter values (e.g. 1.0
cannam@0 175 * if they are all integers). Undefined if isQuantized is
cannam@0 176 * false.
cannam@0 177 */
cannam@0 178 float quantizeStep;
cannam@9 179
cannam@9 180 /**
cannam@9 181 * Names for the quantized values. If isQuantized is true,
cannam@9 182 * this may either be empty or contain one string for each of
cannam@9 183 * the quantize steps from minValue up to maxValue inclusive.
cannam@9 184 * Undefined if isQuantized is false.
cannam@9 185 *
cannam@9 186 * If these names are provided, they should be shown to the
cannam@9 187 * user in preference to the values themselves. The user may
cannam@9 188 * never see the actual numeric values unless they are also
cannam@9 189 * encoded in the names.
cannam@9 190 */
cannam@9 191 std::vector<std::string> valueNames;
cannam@0 192 };
cannam@0 193
cannam@0 194 typedef std::vector<ParameterDescriptor> ParameterList;
cannam@0 195
cannam@0 196 /**
cannam@0 197 * Get the controllable parameters of this plugin.
cannam@0 198 */
cannam@0 199 virtual ParameterList getParameterDescriptors() const {
cannam@0 200 return ParameterList();
cannam@0 201 }
cannam@0 202
cannam@0 203 /**
cannam@49 204 * Get the value of a named parameter. The argument is the identifier
cannam@0 205 * field from that parameter's descriptor.
cannam@0 206 */
cannam@0 207 virtual float getParameter(std::string) const { return 0.0; }
cannam@0 208
cannam@0 209 /**
cannam@49 210 * Set a named parameter. The first argument is the identifier field
cannam@0 211 * from that parameter's descriptor.
cannam@0 212 */
cannam@0 213 virtual void setParameter(std::string, float) { }
cannam@0 214
cannam@0 215
cannam@0 216 typedef std::vector<std::string> ProgramList;
cannam@0 217
cannam@0 218 /**
cannam@0 219 * Get the program settings available in this plugin.
cannam@0 220 * The programs must have unique names.
cannam@0 221 */
cannam@0 222 virtual ProgramList getPrograms() const { return ProgramList(); }
cannam@0 223
cannam@0 224 /**
cannam@0 225 * Get the current program.
cannam@0 226 */
cannam@0 227 virtual std::string getCurrentProgram() const { return ""; }
cannam@0 228
cannam@0 229 /**
cannam@0 230 * Select a program. (If the given program name is not one of the
cannam@0 231 * available programs, do nothing.)
cannam@0 232 */
cannam@0 233 virtual void selectProgram(std::string) { }
cannam@47 234
cannam@47 235 /**
cannam@47 236 * Get the type of plugin. This is to be implemented by the
cannam@47 237 * immediate subclass, not by actual plugins. Do not attempt to
cannam@47 238 * implement this in plugin code.
cannam@47 239 */
cannam@47 240 virtual std::string getType() const = 0;
cannam@0 241 };
cannam@0 242
cannam@0 243 }
cannam@0 244
cannam@0 245 #endif