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