juce/source/src/audio/plugin_client/LV2/lv2.h

   1 /*
   2   LV2 - An audio plugin interface specification.
   3   Copyright (C) 2006-2011 Steve Harris, David Robillard.
   4
   5   Based on LADSPA:
   6   Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,
   7                           Stefan Westerfeld.
   8
   9   This header is free software; you can redistribute it and/or modify it
  10   under the terms of the GNU Lesser General Public License as published
  11   by the Free Software Foundation; either version 2.1 of the License,
  12   or (at your option) any later version.
  13
  14   This header is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   Lesser General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public
  20   License along with this library; if not, write to the Free Software
  21   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
  22   USA.
  23 */
  24
  25 /**
  26   @file lv2.h
  27   API for the LV2 specification <http://lv2plug.in/ns/lv2core>.
  28   Revision: 3.2
  29 */
  30
  31 #ifndef LV2_H_INCLUDED
  32 #define LV2_H_INCLUDED
  33
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /**
  41    Plugin Handle.
  42
  43    This handle refers to a particular instance of a plugin. It is valid to
  44    compare to NULL (or 0 for C++) but otherwise the host MUST NOT attempt to
  45    interpret it. The plugin may use it to reference internal instance data.
  46 */
  47 typedef void * LV2_Handle;
  48
  49 /**
  50    Feature.
  51
  52    Features are used to provide an extensible interface to allow adding
  53    arbitrary functionality to implementations without breaking API
  54    compatibility. In particular, they may be passed by the host to the plugin's
  55    instantiate method to provide additional functionality. Extensions that
  56    describe a feature MUST specify the @a URI and format of @a data that needs
  57    to be used here. The core LV2 specification does not define any features;
  58    implementations are not required to use this facility.
  59 */
  60 typedef struct _LV2_Feature {
  61         /**
  62            A globally unique, case-sensitive identifier (URI) for this feature.
  63
  64            This MUST be a valid URI string as defined by RFC 3986.
  65         */
  66         const char * URI;
  67
  68         /**
  69            Pointer to arbitrary data.
  70
  71            The format of this data is defined by the extension which describes the
  72            feature with the given @a URI. The core LV2 specification makes no
  73            restrictions on the format of this data. If no data is required, this
  74            may be set to NULL if the relevant extension explicitly allows this.
  75         */
  76         void * data;
  77 } LV2_Feature;
  78
  79 /**
  80    Descriptor for an LV2 Plugin.
  81
  82    This structure is used to describe a plugin. It provides the functions
  83    necessary to instantiate and use a plugin.
  84 */
  85 typedef struct _LV2_Descriptor {
  86         /**
  87            A globally unique, case-sensitive identifier for this plugin.
  88
  89            This MUST be a valid URI string as defined by RFC 3986. All plugins with
  90            the same URI are compatible to some degree; see lv2.ttl and the <a
  91            href="http://lv2plug.in/ns/lv2core">LV2 Ontology Documentation</a> for
  92            details.
  93         */
  94         const char * URI;
  95
  96         /**
  97            Instantiate the plugin.
  98
  99            Note that instance initialisation should generally occur in activate()
 100            rather than here. If a host calls instantiate(), it MUST call cleanup()
 101            at some point in the future.
 102
 103            @param descriptor Descriptor of the plugin to instantiate.
 104
 105            @param sample_rate Sample rate, in Hz, for the new plugin instance.
 106
 107            @param bundle_path Path to the LV2 bundle which contains this plugin
 108            binary. It MUST include the trailing directory separator (e.g. '/') so
 109            that simply appending a filename will yield the path to that file in the
 110            bundle.
 111
 112            @param features A NULL terminated array of LV2_Feature structs which
 113            represent the features the host supports. Plugins may refuse to
 114            instantiate if required features are not found here. However, hosts MUST
 115            NOT use this as a discovery mechanism: instead, use the RDF data to
 116            determine which features are required and do not attempt to instantiate
 117            unsupported plugins at all. This parameter MUST NOT be NULL, i.e. a host
 118            that supports no features MUST pass a single element array containing
 119            NULL.
 120
 121            @return A handle for the new plugin instance, or NULL if instantiation
 122            has failed.
 123         */
 124         LV2_Handle (*instantiate)(const struct _LV2_Descriptor * descriptor,
 125                                   double                         sample_rate,
 126                                   const char *                   bundle_path,
 127                                   const LV2_Feature *const *     features);
 128
 129         /**
 130            Connect a port on a plugin instance to a memory location.
 131
 132            Plugin writers should be aware that the host may elect to use the same
 133            buffer for more than one port and even use the same buffer for both
 134            input and output (see lv2:inPlaceBroken in lv2.ttl).
 135
 136            If the plugin has the feature lv2:hardRTCapable then there are various
 137            things that the plugin MUST NOT do within the connect_port() function;
 138            see lv2.ttl for details.
 139
 140            connect_port() MUST be called at least once for each port before run()
 141            is called, unless that port is lv2:connectionOptional. The plugin must
 142            pay careful attention to the block size passed to run() since the block
 143            allocated may only just be large enough to contain the data, and is not
 144            guaranteed to remain constant between run() calls.
 145
 146            connect_port() may be called more than once for a plugin instance to
 147            allow the host to change the buffers that the plugin is reading or
 148            writing. These calls may be made before or after activate() or
 149            deactivate() calls.
 150
 151            @param instance Plugin instance containing the port.
 152
 153            @param port Index of the port to connect. The host MUST NOT try to
 154            connect a port index that is not defined in the plugin's RDF data. If
 155            it does, the plugin's behaviour is undefined (a crash is likely).
 156
 157            @param data_location Pointer to data of the type defined by the port
 158            type in the plugin's RDF data (e.g. an array of float for an
 159            lv2:AudioPort). This pointer must be stored by the plugin instance and
 160            used to read/write data when run() is called. Data present at the time
 161            of the connect_port() call MUST NOT be considered meaningful.
 162         */
 163         void (*connect_port)(LV2_Handle instance,
 164                              uint32_t   port,
 165                              void *     data_location);
 166
 167         /**
 168            Initialise a plugin instance and activate it for use.
 169
 170            This is separated from instantiate() to aid real-time support and so
 171            that hosts can reinitialise a plugin instance by calling deactivate()
 172            and then activate(). In this case the plugin instance MUST reset all
 173            state information dependent on the history of the plugin instance except
 174            for any data locations provided by connect_port(). If there is nothing
 175            for activate() to do then this field may be NULL.
 176
 177            When present, hosts MUST call this function once before run() is called
 178            for the first time. This call SHOULD be made as close to the run() call
 179            as possible and indicates to real-time plugins that they are now live,
 180            however plugins MUST NOT rely on a prompt call to run() after
 181            activate().
 182
 183            The host MUST NOT call activate() again until deactivate() has been
 184            called first. If a host calls activate(), it MUST call deactivate() at
 185            some point in the future. Note that connect_port() may be called before
 186            or after activate().
 187         */
 188         void (*activate)(LV2_Handle instance);
 189
 190         /**
 191            Run a plugin instance for a block.
 192
 193            Note that if an activate() function exists then it must be called before
 194            run(). If deactivate() is called for a plugin instance then run() may
 195            not be called until activate() has been called again.
 196
 197            If the plugin has the feature lv2:hardRTCapable then there are various
 198            things that the plugin MUST NOT do within the run() function (see
 199            lv2.ttl for details).
 200
 201            As a special case, when @a sample_count == 0, the plugin should update
 202            any output ports that represent a single instant in time (e.g. control
 203            ports, but not audio ports). This is particularly useful for latent
 204            plugins, which should update their latency output port so hosts can
 205            pre-roll plugins to compute latency. Plugins MUST NOT crash when
 206            @a sample_count == 0.
 207
 208            @param instance Instance to be run.
 209
 210            @param sample_count The block size (in samples) for which the plugin
 211            instance must run.
 212         */
 213         void (*run)(LV2_Handle instance,
 214                     uint32_t   sample_count);
 215
 216         /**
 217            Deactivate a plugin instance (counterpart to activate()).
 218
 219            Hosts MUST deactivate all activated instances after they have been run()
 220            for the last time. This call SHOULD be made as close to the last run()
 221            call as possible and indicates to real-time plugins that they are no
 222            longer live, however plugins MUST NOT rely on prompt deactivation. If
 223            there is nothing for deactivate() to do then this field may be NULL
 224
 225            Deactivation is not similar to pausing since the plugin instance will be
 226            reinitialised by activate(). However, deactivate() itself MUST NOT fully
 227            reset plugin state. For example, the host may deactivate a plugin, then
 228            store its state (using some extension to do so).
 229
 230            Hosts MUST NOT call deactivate() unless activate() was previously
 231            called. Note that connect_port() may be called before or after
 232            deactivate().
 233         */
 234         void (*deactivate)(LV2_Handle instance);
 235
 236         /**
 237            Clean up a plugin instance (counterpart to instantiate()).
 238
 239            Once an instance of a plugin has been finished with it must be deleted
 240            using this function. The instance handle passed ceases to be valid after
 241            this call.
 242
 243            If activate() was called for a plugin instance then a corresponding call
 244            to deactivate() MUST be made before cleanup() is called. Hosts MUST NOT
 245            call cleanup() unless instantiate() was previously called.
 246         */
 247         void (*cleanup)(LV2_Handle instance);
 248
 249         /**
 250            Return additional plugin data defined by some extenion.
 251
 252            A typical use of this facility is to return a struct containing function
 253            pointers to extend the LV2_Descriptor API.
 254
 255            The actual type and meaning of the returned object MUST be specified
 256            precisely by the extension if it defines any extra data. This function
 257            MUST return NULL for any unsupported URI. If a plugin does not support
 258            any extension data, this field may be NULL.
 259
 260            @param uri URI of the extension. The plugin MUST return NULL if it does
 261            not support the extension, but hosts MUST NOT use this as a discovery
 262            mechanism. Hosts should only call this function for extensions known to
 263            be supported by the plugin, as described in the plugin's RDF data.
 264
 265            The host is never responsible for freeing the returned value.
 266
 267            Note this function SHOULD return a struct (likely containing function
 268            pointers) and NOT a direct function pointer. Casting void* to a function
 269            pointer type is not portable, and returning a struct is much safer
 270            since it is extensible (fields can be added without breaking the ABI).
 271         */
 272         const void * (*extension_data)(const char * uri);
 273 } LV2_Descriptor;
 274
 275 /**
 276    Prototype for plugin accessor function.
 277
 278    The exact mechanism by which plugin libraries are loaded is host and system
 279    dependent, however all hosts need to know is the URI of the plugin they wish
 280    to load. Plugins are discovered via RDF data (not by loading plugin
 281    libraries). Documentation on best practices for plugin discovery can be
 282    found at <http://lv2plug.in>, however it is expected that hosts use a
 283    library to provide this functionality.
 284
 285    A plugin library MUST include a function called "lv2_descriptor" with this
 286    prototype. This function MUST have C-style linkage (if you are using C++
 287    this is taken care of by the 'extern "C"' clause at the top of this file).
 288
 289    A host will find the plugin's library via RDF data, get the lv2_descriptor()
 290    function from it, and proceed from there.
 291
 292    Plugins are accessed by index using values from 0 upwards. Out of range
 293    indices MUST result in this function returning NULL, so the host can
 294    enumerate plugins by increasing @a index until NULL is returned.
 295
 296    Note that @a index has no meaning, hosts MUST NOT depend on it remaining
 297    constant in any way. In other words, @a index is NOT a plugin ID.  In
 298    particular, hosts MUST NOT refer to plugins by library path and index in
 299    persistent serialisations (e.g. save files).
 300 */
 301 const LV2_Descriptor * lv2_descriptor(uint32_t index);
 302
 303 /**
 304    Type of the lv2_descriptor() function in a plugin library.
 305 */
 306 typedef const LV2_Descriptor *
 307 (*LV2_Descriptor_Function)(uint32_t index);
 308
 309 /**
 310   Put this (LV2_SYMBOL_EXPORT) before any functions that are to be loaded
 311   by the host as a symbol from the dynamic library.
 312 */
 313 #ifdef WIN32
 314 #define LV2_SYMBOL_EXPORT __declspec(dllexport)
 315 #else
 316 #define LV2_SYMBOL_EXPORT
 317 #endif
 318
 319 #ifdef __cplusplus
 320 }
 321 #endif
 322
 323 #endif /* LV2_H_INCLUDED */