1 /* 2 LV2 - An audio plugin interface specification. 3 Copyright 2006-2012 Steve Harris, David Robillard. 4 5 Based on LADSPA, Copyright 2000-2002 Richard W.E. Furse, 6 Paul Barton-Davis, Stefan Westerfeld. 7 8 Permission to use, copy, modify, and/or distribute this software for any 9 purpose with or without fee is hereby granted, provided that the above 10 copyright notice and this permission notice appear in all copies. 11 12 THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19 */ 20 21 /** 22 @file lv2.h 23 API for the LV2 specification <http://lv2plug.in/ns/lv2core>. 24 Revision: 12.0 25 */ 26 27 #ifndef LV2_H_INCLUDED 28 #define LV2_H_INCLUDED 29 30 #include <stdint.h> 31 32 #define LV2_CORE_URI "http://lv2plug.in/ns/lv2core" 33 #define LV2_CORE_PREFIX LV2_CORE_URI "#" 34 35 #define LV2_CORE__AllpassPlugin LV2_CORE_PREFIX "AllpassPlugin" 36 #define LV2_CORE__AmplifierPlugin LV2_CORE_PREFIX "AmplifierPlugin" 37 #define LV2_CORE__AnalyserPlugin LV2_CORE_PREFIX "AnalyserPlugin" 38 #define LV2_CORE__AudioPort LV2_CORE_PREFIX "AudioPort" 39 #define LV2_CORE__BandpassPlugin LV2_CORE_PREFIX "BandpassPlugin" 40 #define LV2_CORE__CVPort LV2_CORE_PREFIX "CVPort" 41 #define LV2_CORE__ChorusPlugin LV2_CORE_PREFIX "ChorusPlugin" 42 #define LV2_CORE__CombPlugin LV2_CORE_PREFIX "CombPlugin" 43 #define LV2_CORE__CompressorPlugin LV2_CORE_PREFIX "CompressorPlugin" 44 #define LV2_CORE__ConstantPlugin LV2_CORE_PREFIX "ConstantPlugin" 45 #define LV2_CORE__ControlPort LV2_CORE_PREFIX "ControlPort" 46 #define LV2_CORE__ConverterPlugin LV2_CORE_PREFIX "ConverterPlugin" 47 #define LV2_CORE__DelayPlugin LV2_CORE_PREFIX "DelayPlugin" 48 #define LV2_CORE__DistortionPlugin LV2_CORE_PREFIX "DistortionPlugin" 49 #define LV2_CORE__DynamicsPlugin LV2_CORE_PREFIX "DynamicsPlugin" 50 #define LV2_CORE__EQPlugin LV2_CORE_PREFIX "EQPlugin" 51 #define LV2_CORE__EnvelopePlugin LV2_CORE_PREFIX "EnvelopePlugin" 52 #define LV2_CORE__ExpanderPlugin LV2_CORE_PREFIX "ExpanderPlugin" 53 #define LV2_CORE__ExtensionData LV2_CORE_PREFIX "ExtensionData" 54 #define LV2_CORE__Feature LV2_CORE_PREFIX "Feature" 55 #define LV2_CORE__FilterPlugin LV2_CORE_PREFIX "FilterPlugin" 56 #define LV2_CORE__FlangerPlugin LV2_CORE_PREFIX "FlangerPlugin" 57 #define LV2_CORE__FunctionPlugin LV2_CORE_PREFIX "FunctionPlugin" 58 #define LV2_CORE__GatePlugin LV2_CORE_PREFIX "GatePlugin" 59 #define LV2_CORE__GeneratorPlugin LV2_CORE_PREFIX "GeneratorPlugin" 60 #define LV2_CORE__HighpassPlugin LV2_CORE_PREFIX "HighpassPlugin" 61 #define LV2_CORE__InputPort LV2_CORE_PREFIX "InputPort" 62 #define LV2_CORE__InstrumentPlugin LV2_CORE_PREFIX "InstrumentPlugin" 63 #define LV2_CORE__LimiterPlugin LV2_CORE_PREFIX "LimiterPlugin" 64 #define LV2_CORE__LowpassPlugin LV2_CORE_PREFIX "LowpassPlugin" 65 #define LV2_CORE__MixerPlugin LV2_CORE_PREFIX "MixerPlugin" 66 #define LV2_CORE__ModulatorPlugin LV2_CORE_PREFIX "ModulatorPlugin" 67 #define LV2_CORE__MultiEQPlugin LV2_CORE_PREFIX "MultiEQPlugin" 68 #define LV2_CORE__OscillatorPlugin LV2_CORE_PREFIX "OscillatorPlugin" 69 #define LV2_CORE__OutputPort LV2_CORE_PREFIX "OutputPort" 70 #define LV2_CORE__ParaEQPlugin LV2_CORE_PREFIX "ParaEQPlugin" 71 #define LV2_CORE__PhaserPlugin LV2_CORE_PREFIX "PhaserPlugin" 72 #define LV2_CORE__PitchPlugin LV2_CORE_PREFIX "PitchPlugin" 73 #define LV2_CORE__Plugin LV2_CORE_PREFIX "Plugin" 74 #define LV2_CORE__PluginBase LV2_CORE_PREFIX "PluginBase" 75 #define LV2_CORE__Point LV2_CORE_PREFIX "Point" 76 #define LV2_CORE__Port LV2_CORE_PREFIX "Port" 77 #define LV2_CORE__PortProperty LV2_CORE_PREFIX "PortProperty" 78 #define LV2_CORE__Resource LV2_CORE_PREFIX "Resource" 79 #define LV2_CORE__ReverbPlugin LV2_CORE_PREFIX "ReverbPlugin" 80 #define LV2_CORE__ScalePoint LV2_CORE_PREFIX "ScalePoint" 81 #define LV2_CORE__SimulatorPlugin LV2_CORE_PREFIX "SimulatorPlugin" 82 #define LV2_CORE__SpatialPlugin LV2_CORE_PREFIX "SpatialPlugin" 83 #define LV2_CORE__Specification LV2_CORE_PREFIX "Specification" 84 #define LV2_CORE__SpectralPlugin LV2_CORE_PREFIX "SpectralPlugin" 85 #define LV2_CORE__UtilityPlugin LV2_CORE_PREFIX "UtilityPlugin" 86 #define LV2_CORE__WaveshaperPlugin LV2_CORE_PREFIX "WaveshaperPlugin" 87 #define LV2_CORE__appliesTo LV2_CORE_PREFIX "appliesTo" 88 #define LV2_CORE__binary LV2_CORE_PREFIX "binary" 89 #define LV2_CORE__connectionOptional LV2_CORE_PREFIX "connectionOptional" 90 #define LV2_CORE__control LV2_CORE_PREFIX "control" 91 #define LV2_CORE__default LV2_CORE_PREFIX "default" 92 #define LV2_CORE__designation LV2_CORE_PREFIX "designation" 93 #define LV2_CORE__documentation LV2_CORE_PREFIX "documentation" 94 #define LV2_CORE__enumeration LV2_CORE_PREFIX "enumeration" 95 #define LV2_CORE__extensionData LV2_CORE_PREFIX "extensionData" 96 #define LV2_CORE__freeWheeling LV2_CORE_PREFIX "freeWheeling" 97 #define LV2_CORE__hardRTCapable LV2_CORE_PREFIX "hardRTCapable" 98 #define LV2_CORE__inPlaceBroken LV2_CORE_PREFIX "inPlaceBroken" 99 #define LV2_CORE__index LV2_CORE_PREFIX "index" 100 #define LV2_CORE__integer LV2_CORE_PREFIX "integer" 101 #define LV2_CORE__isLive LV2_CORE_PREFIX "isLive" 102 #define LV2_CORE__latency LV2_CORE_PREFIX "latency" 103 #define LV2_CORE__maximum LV2_CORE_PREFIX "maximum" 104 #define LV2_CORE__microVersion LV2_CORE_PREFIX "microVersion" 105 #define LV2_CORE__minimum LV2_CORE_PREFIX "minimum" 106 #define LV2_CORE__minorVersion LV2_CORE_PREFIX "minorVersion" 107 #define LV2_CORE__name LV2_CORE_PREFIX "name" 108 #define LV2_CORE__optionalFeature LV2_CORE_PREFIX "optionalFeature" 109 #define LV2_CORE__port LV2_CORE_PREFIX "port" 110 #define LV2_CORE__portProperty LV2_CORE_PREFIX "portProperty" 111 #define LV2_CORE__project LV2_CORE_PREFIX "project" 112 #define LV2_CORE__prototype LV2_CORE_PREFIX "prototype" 113 #define LV2_CORE__reportsLatency LV2_CORE_PREFIX "reportsLatency" 114 #define LV2_CORE__requiredFeature LV2_CORE_PREFIX "requiredFeature" 115 #define LV2_CORE__sampleRate LV2_CORE_PREFIX "sampleRate" 116 #define LV2_CORE__scalePoint LV2_CORE_PREFIX "scalePoint" 117 #define LV2_CORE__symbol LV2_CORE_PREFIX "symbol" 118 #define LV2_CORE__toggled LV2_CORE_PREFIX "toggled" 119 120 #ifdef __cplusplus 121 extern "C" { 122 #endif 123 124 /** 125 Plugin Instance Handle. 126 127 This is a handle for one particular instance of a plugin. It is valid to 128 compare to NULL (or 0 for C++) but otherwise the host MUST NOT attempt to 129 interpret it. 130 */ 131 typedef void * LV2_Handle; 132 133 /** 134 Feature. 135 136 Features allow hosts to make additional functionality available to plugins 137 without requiring modification to the LV2 API. Extensions may define new 138 features and specify the @ref URI and @ref data to be used if necessary. 139 Some features, such as lv2:isLive, do not require the host to pass data. 140 */ 141 typedef struct _LV2_Feature { 142 /** 143 A globally unique, case-sensitive identifier (URI) for this feature. 144 145 This MUST be a valid URI string as defined by RFC 3986. 146 */ 147 const char * URI; 148 149 /** 150 Pointer to arbitrary data. 151 152 The format of this data is defined by the extension which describes the 153 feature with the given @ref URI. 154 */ 155 void * data; 156 } LV2_Feature; 157 158 /** 159 Plugin Descriptor. 160 161 This structure provides the core functions necessary to instantiate and use 162 a plugin. 163 */ 164 typedef struct _LV2_Descriptor { 165 /** 166 A globally unique, case-sensitive identifier for this plugin. 167 168 This MUST be a valid URI string as defined by RFC 3986. All plugins with 169 the same URI MUST be compatible to some degree, see 170 http://lv2plug.in/ns/lv2core for details. 171 */ 172 const char * URI; 173 174 /** 175 Instantiate the plugin. 176 177 Note that instance initialisation should generally occur in activate() 178 rather than here. If a host calls instantiate(), it MUST call cleanup() 179 at some point in the future. 180 181 @param descriptor Descriptor of the plugin to instantiate. 182 183 @param sample_rate Sample rate, in Hz, for the new plugin instance. 184 185 @param bundle_path Path to the LV2 bundle which contains this plugin 186 binary. It MUST include the trailing directory separator (e.g. '/') so 187 that simply appending a filename will yield the path to that file in the 188 bundle. 189 190 @param features A NULL terminated array of LV2_Feature structs which 191 represent the features the host supports. Plugins may refuse to 192 instantiate if required features are not found here. However, hosts MUST 193 NOT use this as a discovery mechanism: instead, use the RDF data to 194 determine which features are required and do not attempt to instantiate 195 unsupported plugins at all. This parameter MUST NOT be NULL, i.e. a host 196 that supports no features MUST pass a single element array containing 197 NULL. 198 199 @return A handle for the new plugin instance, or NULL if instantiation 200 has failed. 201 */ 202 LV2_Handle (*instantiate)(const struct _LV2_Descriptor * descriptor, 203 double sample_rate, 204 const char * bundle_path, 205 const LV2_Feature *const * features); 206 207 /** 208 Connect a port on a plugin instance to a memory location. 209 210 Plugin writers should be aware that the host may elect to use the same 211 buffer for more than one port and even use the same buffer for both 212 input and output (see lv2:inPlaceBroken in lv2.ttl). 213 214 If the plugin has the feature lv2:hardRTCapable then there are various 215 things that the plugin MUST NOT do within the connect_port() function; 216 see lv2core.ttl for details. 217 218 connect_port() MUST be called at least once for each port before run() 219 is called, unless that port is lv2:connectionOptional. The plugin must 220 pay careful attention to the block size passed to run() since the block 221 allocated may only just be large enough to contain the data, and is not 222 guaranteed to remain constant between run() calls. 223 224 connect_port() may be called more than once for a plugin instance to 225 allow the host to change the buffers that the plugin is reading or 226 writing. These calls may be made before or after activate() or 227 deactivate() calls. 228 229 @param instance Plugin instance containing the port. 230 231 @param port Index of the port to connect. The host MUST NOT try to 232 connect a port index that is not defined in the plugin's RDF data. If 233 it does, the plugin's behaviour is undefined (a crash is likely). 234 235 @param data_location Pointer to data of the type defined by the port 236 type in the plugin's RDF data (e.g. an array of float for an 237 lv2:AudioPort). This pointer must be stored by the plugin instance and 238 used to read/write data when run() is called. Data present at the time 239 of the connect_port() call MUST NOT be considered meaningful. 240 */ 241 void (*connect_port)(LV2_Handle instance, 242 uint32_t port, 243 void * data_location); 244 245 /** 246 Initialise a plugin instance and activate it for use. 247 248 This is separated from instantiate() to aid real-time support and so 249 that hosts can reinitialise a plugin instance by calling deactivate() 250 and then activate(). In this case the plugin instance MUST reset all 251 state information dependent on the history of the plugin instance except 252 for any data locations provided by connect_port(). If there is nothing 253 for activate() to do then this field may be NULL. 254 255 When present, hosts MUST call this function once before run() is called 256 for the first time. This call SHOULD be made as close to the run() call 257 as possible and indicates to real-time plugins that they are now live, 258 however plugins MUST NOT rely on a prompt call to run() after 259 activate(). 260 261 The host MUST NOT call activate() again until deactivate() has been 262 called first. If a host calls activate(), it MUST call deactivate() at 263 some point in the future. Note that connect_port() may be called before 264 or after activate(). 265 */ 266 void (*activate)(LV2_Handle instance); 267 268 /** 269 Run a plugin instance for a block. 270 271 Note that if an activate() function exists then it must be called before 272 run(). If deactivate() is called for a plugin instance then run() may 273 not be called until activate() has been called again. 274 275 If the plugin has the feature lv2:hardRTCapable then there are various 276 things that the plugin MUST NOT do within the run() function (see 277 lv2core.ttl for details). 278 279 As a special case, when @p sample_count == 0, the plugin should update 280 any output ports that represent a single instant in time (e.g. control 281 ports, but not audio ports). This is particularly useful for latent 282 plugins, which should update their latency output port so hosts can 283 pre-roll plugins to compute latency. Plugins MUST NOT crash when 284 @p sample_count == 0. 285 286 @param instance Instance to be run. 287 288 @param sample_count The block size (in samples) for which the plugin 289 instance must run. 290 */ 291 void (*run)(LV2_Handle instance, 292 uint32_t sample_count); 293 294 /** 295 Deactivate a plugin instance (counterpart to activate()). 296 297 Hosts MUST deactivate all activated instances after they have been run() 298 for the last time. This call SHOULD be made as close to the last run() 299 call as possible and indicates to real-time plugins that they are no 300 longer live, however plugins MUST NOT rely on prompt deactivation. If 301 there is nothing for deactivate() to do then this field may be NULL 302 303 Deactivation is not similar to pausing since the plugin instance will be 304 reinitialised by activate(). However, deactivate() itself MUST NOT fully 305 reset plugin state. For example, the host may deactivate a plugin, then 306 store its state (using some extension to do so). 307 308 Hosts MUST NOT call deactivate() unless activate() was previously 309 called. Note that connect_port() may be called before or after 310 deactivate(). 311 */ 312 void (*deactivate)(LV2_Handle instance); 313 314 /** 315 Clean up a plugin instance (counterpart to instantiate()). 316 317 Once an instance of a plugin has been finished with it must be deleted 318 using this function. The instance handle passed ceases to be valid after 319 this call. 320 321 If activate() was called for a plugin instance then a corresponding call 322 to deactivate() MUST be made before cleanup() is called. Hosts MUST NOT 323 call cleanup() unless instantiate() was previously called. 324 */ 325 void (*cleanup)(LV2_Handle instance); 326 327 /** 328 Return additional plugin data defined by some extenion. 329 330 A typical use of this facility is to return a struct containing function 331 pointers to extend the LV2_Descriptor API. 332 333 The actual type and meaning of the returned object MUST be specified 334 precisely by the extension. This function MUST return NULL for any 335 unsupported URI. If a plugin does not support any extension data, this 336 field may be NULL. 337 338 The host is never responsible for freeing the returned value. 339 */ 340 const void * (*extension_data)(const char * uri); 341 } LV2_Descriptor; 342 343 /** 344 Put this (LV2_SYMBOL_EXPORT) before any functions that are to be loaded 345 by the host as a symbol from the dynamic library. 346 */ 347 #ifdef _WIN32 348 # define LV2_SYMBOL_EXPORT __declspec(dllexport) 349 #else 350 # define LV2_SYMBOL_EXPORT 351 #endif 352 353 /** 354 Prototype for plugin accessor function. 355 356 Plugins are discovered by hosts using RDF data (not by loading libraries). 357 See http://lv2plug.in for details on the discovery process, though most 358 hosts should use an existing library to implement this functionality. 359 360 This is the simple plugin discovery API, suitable for most statically 361 defined plugins. Advanced plugins that need access to their bundle during 362 discovery can use lv2_lib_descriptor() instead. Plugin libraries MUST 363 include a function called "lv2_descriptor" or "lv2_lib_descriptor" with 364 C-style linkage, but SHOULD provide "lv2_descriptor" wherever possible. 365 366 When it is time to load a plugin (designated by its URI), the host loads the 367 plugin's library, gets the lv2_descriptor() function from it, and uses this 368 function to find the LV2_Descriptor for the desired plugin. Plugins are 369 accessed by index using values from 0 upwards. This function MUST return 370 NULL for out of range indices, so the host can enumerate plugins by 371 increasing @p index until NULL is returned. 372 373 Note that @p index has no meaning, hosts MUST NOT depend on it remaining 374 consistent between loads of the plugin library. 375 */ 376 LV2_SYMBOL_EXPORT 377 const LV2_Descriptor * lv2_descriptor(uint32_t index); 378 379 /** 380 Type of the lv2_descriptor() function in a library (old discovery API). 381 */ 382 typedef const LV2_Descriptor * 383 (*LV2_Descriptor_Function)(uint32_t index); 384 385 /** 386 Handle for a library descriptor. 387 */ 388 typedef void* LV2_Lib_Handle; 389 390 /** 391 Descriptor for a plugin library. 392 393 To access a plugin library, the host creates an LV2_Lib_Descriptor via the 394 lv2_lib_descriptor() function in the shared object. 395 */ 396 typedef struct { 397 /** 398 Opaque library data which must be passed as the first parameter to all 399 the methods of this struct. 400 */ 401 LV2_Lib_Handle handle; 402 403 /** 404 The total size of this struct. This allows for this struct to be 405 expanded in the future if necessary. This MUST be set by the library to 406 sizeof(LV2_Lib_Descriptor). The host MUST NOT access any fields of this 407 struct beyond get_plugin() unless this field indicates they are present. 408 */ 409 uint32_t size; 410 411 /** 412 Destroy this library descriptor and free all related resources. 413 */ 414 void (*cleanup)(LV2_Lib_Handle handle); 415 416 /** 417 Plugin accessor. 418 419 Plugins are accessed by index using values from 0 upwards. Out of range 420 indices MUST result in this function returning NULL, so the host can 421 enumerate plugins by increasing @a index until NULL is returned. 422 */ 423 const LV2_Descriptor * (*get_plugin)(LV2_Lib_Handle handle, 424 uint32_t index); 425 } LV2_Lib_Descriptor; 426 427 /** 428 Prototype for library accessor function. 429 430 This is the more advanced discovery API, which allows plugin libraries to 431 access their bundles during discovery, which makes it possible for plugins to 432 be dynamically defined by files in their bundle. This API also has an 433 explicit cleanup function, removing any need for non-portable shared library 434 destructors. Simple plugins that do not require these features may use 435 lv2_descriptor() instead. 436 437 This is the entry point for a plugin library. Hosts load this symbol from 438 the library and call this function to obtain a library descriptor which can 439 be used to access all the contained plugins. The returned object must not 440 be destroyed (using LV2_Lib_Descriptor::cleanup()) until all plugins loaded 441 from that library have been destroyed. 442 */ 443 const LV2_Lib_Descriptor * 444 lv2_lib_descriptor(const char * bundle_path, 445 const LV2_Feature *const * features); 446 447 /** 448 Type of the lv2_lib_descriptor() function in an LV2 library. 449 */ 450 typedef const LV2_Lib_Descriptor * 451 (*LV2_Lib_Descriptor_Function)(const char * bundle_path, 452 const LV2_Feature *const * features); 453 454 #ifdef __cplusplus 455 } 456 #endif 457 458 #endif /* LV2_H_INCLUDED */ 459