annotate vamp-sdk/PluginBase.h @ 230:5ee166dccfff distinct-libraries

* Add include guards; make code compile!
author cannam
date Fri, 07 Nov 2008 14:11:39 +0000
parents 31eda4b11f2b
children 521734d2b498
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@230 37 #ifndef _VAMP_SDK_PLUGIN_BASE_H_
cannam@230 38 #define _VAMP_SDK_PLUGIN_BASE_H_
cannam@0 39
cannam@0 40 #include <string>
cannam@0 41 #include <vector>
cannam@0 42
cannam@230 43 #include "plugguard.h"
cannam@230 44 _VAMP_SDK_HEADER_BEGIN(PluginBase.h)
cannam@24 45
cannam@0 46 namespace Vamp {
cannam@0 47
cannam@0 48 /**
cannam@0 49 * A base class for plugins with optional configurable parameters,
cannam@53 50 * programs, etc. The Vamp::Plugin is derived from this, and
cannam@53 51 * individual Vamp plugins should derive from that.
cannam@0 52 *
cannam@53 53 * This class does not provide the necessary interfaces to instantiate
cannam@53 54 * or run a plugin. It only specifies an interface for retrieving
cannam@53 55 * those controls that the host may wish to show to the user for
cannam@53 56 * editing. It could meaningfully be subclassed by real-time plugins
cannam@53 57 * or other sorts of plugin as well as Vamp plugins.
cannam@0 58 */
cannam@0 59
cannam@0 60 class PluginBase
cannam@0 61 {
cannam@0 62 public:
cannam@20 63 virtual ~PluginBase() { }
cannam@20 64
cannam@0 65 /**
cannam@50 66 * Get the Vamp API compatibility level of the plugin.
cannam@50 67 */
cannam@167 68 virtual unsigned int getVampApiVersion() const { return 2; }
cannam@50 69
cannam@50 70 /**
cannam@0 71 * Get the computer-usable name of the plugin. This should be
cannam@0 72 * reasonably short and contain no whitespace or punctuation
cannam@134 73 * characters. It may only contain the characters [a-zA-Z0-9_-].
cannam@47 74 * This is the authoritative way for a program to identify a
cannam@47 75 * plugin within a given library.
cannam@47 76 *
cannam@47 77 * This text may be visible to the user, but it should not be the
cannam@47 78 * main text used to identify a plugin to the user (that will be
cannam@49 79 * the name, below).
cannam@49 80 *
cannam@49 81 * Example: "zero_crossings"
cannam@49 82 */
cannam@49 83 virtual std::string getIdentifier() const = 0;
cannam@49 84
cannam@49 85 /**
cannam@49 86 * Get a human-readable name or title of the plugin. This
cannam@49 87 * should be brief and self-contained, as it may be used to
cannam@49 88 * identify the plugin to the user in isolation (i.e. without also
cannam@49 89 * showing the plugin's "identifier").
cannam@49 90 *
cannam@49 91 * Example: "Zero Crossings"
cannam@0 92 */
cannam@0 93 virtual std::string getName() const = 0;
cannam@0 94
cannam@0 95 /**
cannam@49 96 * Get a human-readable description for the plugin, typically
cannam@49 97 * a line of text that may optionally be displayed in addition
cannam@49 98 * to the plugin's "name". May be empty if the name has said
cannam@49 99 * it all already.
cannam@49 100 *
cannam@49 101 * Example: "Detect and count zero crossing points"
cannam@0 102 */
cannam@0 103 virtual std::string getDescription() const = 0;
cannam@0 104
cannam@0 105 /**
cannam@0 106 * Get the name of the author or vendor of the plugin in
cannam@47 107 * human-readable form. This should be a short identifying text,
cannam@47 108 * as it may be used to label plugins from the same source in a
cannam@47 109 * menu or similar.
cannam@0 110 */
cannam@0 111 virtual std::string getMaker() const = 0;
cannam@0 112
cannam@0 113 /**
cannam@47 114 * Get the copyright statement or licensing summary for the
cannam@47 115 * plugin. This can be an informative text, without the same
cannam@47 116 * presentation constraints as mentioned for getMaker above.
cannam@47 117 */
cannam@47 118 virtual std::string getCopyright() const = 0;
cannam@47 119
cannam@47 120 /**
cannam@0 121 * Get the version number of the plugin.
cannam@0 122 */
cannam@0 123 virtual int getPluginVersion() const = 0;
cannam@0 124
cannam@0 125
cannam@0 126 struct ParameterDescriptor
cannam@0 127 {
cannam@0 128 /**
cannam@0 129 * The name of the parameter, in computer-usable form. Should
cannam@0 130 * be reasonably short, and may only contain the characters
cannam@134 131 * [a-zA-Z0-9_-].
cannam@0 132 */
cannam@49 133 std::string identifier;
cannam@49 134
cannam@49 135 /**
cannam@49 136 * The human-readable name of the parameter.
cannam@49 137 */
cannam@0 138 std::string name;
cannam@0 139
cannam@0 140 /**
cannam@49 141 * A human-readable short text describing the parameter. May be
cannam@49 142 * empty if the name has said it all already.
cannam@0 143 */
cannam@0 144 std::string description;
cannam@0 145
cannam@0 146 /**
cannam@0 147 * The unit of the parameter, in human-readable form.
cannam@0 148 */
cannam@0 149 std::string unit;
cannam@0 150
cannam@0 151 /**
cannam@0 152 * The minimum value of the parameter.
cannam@0 153 */
cannam@0 154 float minValue;
cannam@0 155
cannam@0 156 /**
cannam@0 157 * The maximum value of the parameter.
cannam@0 158 */
cannam@0 159 float maxValue;
cannam@0 160
cannam@0 161 /**
cannam@24 162 * The default value of the parameter. The plugin should
cannam@24 163 * ensure that parameters have this value on initialisation
cannam@24 164 * (i.e. the host is not required to explicitly set parameters
cannam@24 165 * if it wants to use their default values).
cannam@0 166 */
cannam@0 167 float defaultValue;
cannam@0 168
cannam@0 169 /**
cannam@0 170 * True if the parameter values are quantized to a particular
cannam@0 171 * resolution.
cannam@0 172 */
cannam@0 173 bool isQuantized;
cannam@0 174
cannam@0 175 /**
cannam@0 176 * Quantization resolution of the parameter values (e.g. 1.0
cannam@0 177 * if they are all integers). Undefined if isQuantized is
cannam@0 178 * false.
cannam@0 179 */
cannam@0 180 float quantizeStep;
cannam@9 181
cannam@9 182 /**
cannam@9 183 * Names for the quantized values. If isQuantized is true,
cannam@9 184 * this may either be empty or contain one string for each of
cannam@9 185 * the quantize steps from minValue up to maxValue inclusive.
cannam@9 186 * Undefined if isQuantized is false.
cannam@9 187 *
cannam@9 188 * If these names are provided, they should be shown to the
cannam@9 189 * user in preference to the values themselves. The user may
cannam@9 190 * never see the actual numeric values unless they are also
cannam@9 191 * encoded in the names.
cannam@9 192 */
cannam@9 193 std::vector<std::string> valueNames;
cannam@167 194
cannam@167 195 ParameterDescriptor() : // the defaults are invalid: you must set them
cannam@167 196 minValue(0), maxValue(0), defaultValue(0), isQuantized(false) { }
cannam@0 197 };
cannam@0 198
cannam@0 199 typedef std::vector<ParameterDescriptor> ParameterList;
cannam@0 200
cannam@0 201 /**
cannam@0 202 * Get the controllable parameters of this plugin.
cannam@0 203 */
cannam@0 204 virtual ParameterList getParameterDescriptors() const {
cannam@0 205 return ParameterList();
cannam@0 206 }
cannam@0 207
cannam@0 208 /**
cannam@49 209 * Get the value of a named parameter. The argument is the identifier
cannam@0 210 * field from that parameter's descriptor.
cannam@0 211 */
cannam@0 212 virtual float getParameter(std::string) const { return 0.0; }
cannam@0 213
cannam@0 214 /**
cannam@49 215 * Set a named parameter. The first argument is the identifier field
cannam@0 216 * from that parameter's descriptor.
cannam@0 217 */
cannam@0 218 virtual void setParameter(std::string, float) { }
cannam@0 219
cannam@0 220
cannam@0 221 typedef std::vector<std::string> ProgramList;
cannam@0 222
cannam@0 223 /**
cannam@64 224 * Get the program settings available in this plugin. A program
cannam@64 225 * is a named shorthand for a set of parameter values; changing
cannam@64 226 * the program may cause the plugin to alter the values of its
cannam@64 227 * published parameters (and/or non-public internal processing
cannam@64 228 * parameters). The host should re-read the plugin's parameter
cannam@64 229 * values after setting a new program.
cannam@64 230 *
cannam@0 231 * The programs must have unique names.
cannam@0 232 */
cannam@0 233 virtual ProgramList getPrograms() const { return ProgramList(); }
cannam@0 234
cannam@0 235 /**
cannam@0 236 * Get the current program.
cannam@0 237 */
cannam@0 238 virtual std::string getCurrentProgram() const { return ""; }
cannam@0 239
cannam@0 240 /**
cannam@0 241 * Select a program. (If the given program name is not one of the
cannam@0 242 * available programs, do nothing.)
cannam@0 243 */
cannam@0 244 virtual void selectProgram(std::string) { }
cannam@47 245
cannam@47 246 /**
cannam@47 247 * Get the type of plugin. This is to be implemented by the
cannam@47 248 * immediate subclass, not by actual plugins. Do not attempt to
cannam@47 249 * implement this in plugin code.
cannam@47 250 */
cannam@47 251 virtual std::string getType() const = 0;
cannam@0 252 };
cannam@0 253
cannam@0 254 }
cannam@0 255
cannam@230 256 _VAMP_SDK_HEADER_END(PluginBase.h)
cannam@230 257
cannam@0 258 #endif