annotate vamp-sdk/PluginBase.h @ 43:3bbe244611bb

* Update version number to 1.0, some textual tweaks
author cannam
date Tue, 31 Oct 2006 19:55:47 +0000
parents 13eae6cc6bac
children be8fdfe25693
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@0 64 * Get the computer-usable name of the plugin. This should be
cannam@0 65 * reasonably short and contain no whitespace or punctuation
cannam@0 66 * characters. It may be shown to the user, but it won't be the
cannam@0 67 * main method for a user to identify a plugin (that will be the
cannam@24 68 * description, below). This may only contain the characters
cannam@24 69 * [a-zA-Z0-9_].
cannam@0 70 */
cannam@0 71 virtual std::string getName() const = 0;
cannam@0 72
cannam@0 73 /**
cannam@0 74 * Get a human-readable description of the plugin. This should be
cannam@0 75 * self-contained, as it may be shown to the user in isolation
cannam@0 76 * without also showing the plugin's "name".
cannam@0 77 */
cannam@0 78 virtual std::string getDescription() const = 0;
cannam@0 79
cannam@0 80 /**
cannam@0 81 * Get the name of the author or vendor of the plugin in
cannam@0 82 * human-readable form.
cannam@0 83 */
cannam@0 84 virtual std::string getMaker() const = 0;
cannam@0 85
cannam@0 86 /**
cannam@0 87 * Get the version number of the plugin.
cannam@0 88 */
cannam@0 89 virtual int getPluginVersion() const = 0;
cannam@0 90
cannam@0 91 /**
cannam@0 92 * Get the copyright statement or licensing summary of the plugin.
cannam@0 93 */
cannam@0 94 virtual std::string getCopyright() const = 0;
cannam@0 95
cannam@0 96 /**
cannam@0 97 * Get the type of plugin (e.g. DSSI, etc). This is likely to be
cannam@0 98 * implemented by the immediate subclass, not by actual plugins.
cannam@0 99 */
cannam@0 100 virtual std::string getType() const = 0;
cannam@0 101
cannam@0 102
cannam@0 103 struct ParameterDescriptor
cannam@0 104 {
cannam@0 105 /**
cannam@0 106 * The name of the parameter, in computer-usable form. Should
cannam@0 107 * be reasonably short, and may only contain the characters
cannam@0 108 * [a-zA-Z0-9_].
cannam@0 109 */
cannam@0 110 std::string name;
cannam@0 111
cannam@0 112 /**
cannam@0 113 * The human-readable name of the parameter.
cannam@0 114 */
cannam@0 115 std::string description;
cannam@0 116
cannam@0 117 /**
cannam@0 118 * The unit of the parameter, in human-readable form.
cannam@0 119 */
cannam@0 120 std::string unit;
cannam@0 121
cannam@0 122 /**
cannam@0 123 * The minimum value of the parameter.
cannam@0 124 */
cannam@0 125 float minValue;
cannam@0 126
cannam@0 127 /**
cannam@0 128 * The maximum value of the parameter.
cannam@0 129 */
cannam@0 130 float maxValue;
cannam@0 131
cannam@0 132 /**
cannam@24 133 * The default value of the parameter. The plugin should
cannam@24 134 * ensure that parameters have this value on initialisation
cannam@24 135 * (i.e. the host is not required to explicitly set parameters
cannam@24 136 * if it wants to use their default values).
cannam@0 137 */
cannam@0 138 float defaultValue;
cannam@0 139
cannam@0 140 /**
cannam@0 141 * True if the parameter values are quantized to a particular
cannam@0 142 * resolution.
cannam@0 143 */
cannam@0 144 bool isQuantized;
cannam@0 145
cannam@0 146 /**
cannam@0 147 * Quantization resolution of the parameter values (e.g. 1.0
cannam@0 148 * if they are all integers). Undefined if isQuantized is
cannam@0 149 * false.
cannam@0 150 */
cannam@0 151 float quantizeStep;
cannam@9 152
cannam@9 153 /**
cannam@9 154 * Names for the quantized values. If isQuantized is true,
cannam@9 155 * this may either be empty or contain one string for each of
cannam@9 156 * the quantize steps from minValue up to maxValue inclusive.
cannam@9 157 * Undefined if isQuantized is false.
cannam@9 158 *
cannam@9 159 * If these names are provided, they should be shown to the
cannam@9 160 * user in preference to the values themselves. The user may
cannam@9 161 * never see the actual numeric values unless they are also
cannam@9 162 * encoded in the names.
cannam@9 163 */
cannam@9 164 std::vector<std::string> valueNames;
cannam@0 165 };
cannam@0 166
cannam@0 167 typedef std::vector<ParameterDescriptor> ParameterList;
cannam@0 168
cannam@0 169 /**
cannam@0 170 * Get the controllable parameters of this plugin.
cannam@0 171 */
cannam@0 172 virtual ParameterList getParameterDescriptors() const {
cannam@0 173 return ParameterList();
cannam@0 174 }
cannam@0 175
cannam@0 176 /**
cannam@0 177 * Get the value of a named parameter. The argument is the name
cannam@0 178 * field from that parameter's descriptor.
cannam@0 179 */
cannam@0 180 virtual float getParameter(std::string) const { return 0.0; }
cannam@0 181
cannam@0 182 /**
cannam@0 183 * Set a named parameter. The first argument is the name field
cannam@0 184 * from that parameter's descriptor.
cannam@0 185 */
cannam@0 186 virtual void setParameter(std::string, float) { }
cannam@0 187
cannam@0 188
cannam@0 189 typedef std::vector<std::string> ProgramList;
cannam@0 190
cannam@0 191 /**
cannam@0 192 * Get the program settings available in this plugin.
cannam@0 193 * The programs must have unique names.
cannam@0 194 */
cannam@0 195 virtual ProgramList getPrograms() const { return ProgramList(); }
cannam@0 196
cannam@0 197 /**
cannam@0 198 * Get the current program.
cannam@0 199 */
cannam@0 200 virtual std::string getCurrentProgram() const { return ""; }
cannam@0 201
cannam@0 202 /**
cannam@0 203 * Select a program. (If the given program name is not one of the
cannam@0 204 * available programs, do nothing.)
cannam@0 205 */
cannam@0 206 virtual void selectProgram(std::string) { }
cannam@0 207 };
cannam@0 208
cannam@0 209 }
cannam@0 210
cannam@0 211 #endif