Mercurial > hg > pub > prymula > com

comparison DPF-Prymula-audioplugins/dpf/distrho/src/lv2/lv2.h @ 3:84e66ea83026

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
DPF-Prymula-audioplugins-0.231015-2
author prymula <prymula76@outlook.com>
date Mon, 16 Oct 2023 21:53:34 +0200
parents
children
comparison
equal deleted inserted replaced
2:cf2cb71d31dd 3:84e66ea83026
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 */