DPF

DISTRHO Plugin Framework
Log | Files | Refs | Submodules | README | LICENSE

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 */