diff options
Diffstat (limited to 'core.lv2/lv2.h')
| -rw-r--r-- | core.lv2/lv2.h | 89 |
1 files changed, 34 insertions, 55 deletions
diff --git a/core.lv2/lv2.h b/core.lv2/lv2.h index 4e8d225..ce55d45 100644 --- a/core.lv2/lv2.h +++ b/core.lv2/lv2.h @@ -34,24 +34,21 @@ extern "C" { #endif /** - Plugin Handle. + Plugin Instance Handle. - This handle refers to a particular instance of a plugin. It is valid to + This is a handle for one particular instance of a plugin. It is valid to compare to NULL (or 0 for C++) but otherwise the host MUST NOT attempt to - interpret it. The plugin may use it to reference internal instance data. + interpret it. */ typedef void * LV2_Handle; /** Feature. - Features are used to provide an extensible interface to allow adding - arbitrary functionality to implementations without breaking API - compatibility. In particular, they may be passed by the host to the plugin's - instantiate method to provide additional functionality. Extensions that - describe a feature MUST specify the @a URI and format of @a data that needs - to be used here. The core LV2 specification does not define any features; - implementations are not required to use this facility. + Features allow hosts to make additional functionality available to plugins + without requiring modification to the LV2 API. Extensions may define new + features and specify the @ref URI and @ref data to be used if necessary. + Some features, such as lv2:isLive, do not require the host to pass data. */ typedef struct _LV2_Feature { /** @@ -65,27 +62,24 @@ typedef struct _LV2_Feature { Pointer to arbitrary data. The format of this data is defined by the extension which describes the - feature with the given @a URI. The core LV2 specification makes no - restrictions on the format of this data. If no data is required, this - may be set to NULL if the relevant extension explicitly allows this. + feature with the given @ref URI. */ void * data; } LV2_Feature; /** - Descriptor for an LV2 Plugin. + Plugin Descriptor. - This structure is used to describe a plugin. It provides the functions - necessary to instantiate and use a plugin. + This structure provides the core functions necessary to instantiate and use + a plugin. */ typedef struct _LV2_Descriptor { /** A globally unique, case-sensitive identifier for this plugin. - This MUST be a valid URI string as defined by RFC 3986. All plugins with - the same URI are compatible to some degree; see lv2.ttl and the <a - href="http://lv2plug.in/ns/lv2core">LV2 Ontology Documentation</a> for - details. + This MUST be a valid URI string as defined by RFC 3986. All plugins with + the same URI MUST be compatible to some degree, see + http://lv2plug.in/ns/lv2core for details. */ const char * URI; @@ -194,12 +188,12 @@ typedef struct _LV2_Descriptor { things that the plugin MUST NOT do within the run() function (see lv2.ttl for details). - As a special case, when @a sample_count == 0, the plugin should update + As a special case, when @c sample_count == 0, the plugin should update any output ports that represent a single instant in time (e.g. control ports, but not audio ports). This is particularly useful for latent plugins, which should update their latency output port so hosts can pre-roll plugins to compute latency. Plugins MUST NOT crash when - @a sample_count == 0. + @c sample_count == 0. @param instance Instance to be run. @@ -249,21 +243,11 @@ typedef struct _LV2_Descriptor { pointers to extend the LV2_Descriptor API. The actual type and meaning of the returned object MUST be specified - precisely by the extension if it defines any extra data. This function - MUST return NULL for any unsupported URI. If a plugin does not support - any extension data, this field may be NULL. - - @param uri URI of the extension. The plugin MUST return NULL if it does - not support the extension, but hosts MUST NOT use this as a discovery - mechanism. Hosts should only call this function for extensions known to - be supported by the plugin, as described in the plugin's RDF data. + precisely by the extension. This function MUST return NULL for any + unsupported URI. If a plugin does not support any extension data, this + field may be NULL. The host is never responsible for freeing the returned value. - - Note this function SHOULD return a struct (likely containing function - pointers) and NOT a direct function pointer. Casting void* to a function - pointer type is not portable, and returning a struct is much safer - since it is extensible (fields can be added without breaking the ABI). */ const void * (*extension_data)(const char * uri); } LV2_Descriptor; @@ -271,28 +255,23 @@ typedef struct _LV2_Descriptor { /** Prototype for plugin accessor function. - The exact mechanism by which plugin libraries are loaded is host and system - dependent, however all hosts need to know is the URI of the plugin they wish - to load. Plugins are discovered via RDF data (not by loading plugin - libraries). Documentation on best practices for plugin discovery can be - found at <http://lv2plug.in>, however it is expected that hosts use a - library to provide this functionality. - + Plugins are discovered by hosts using RDF data (not by loading libraries). + See http://lv2plug.in for details on the discovery process, though most + hosts should use an existing library to implement this functionality. + A plugin library MUST include a function called "lv2_descriptor" with this - prototype. This function MUST have C-style linkage (if you are using C++ + prototype. This function MUST have C-style linkage (if you are using C++ this is taken care of by the 'extern "C"' clause at the top of this file). - - A host will find the plugin's library via RDF data, get the lv2_descriptor() - function from it, and proceed from there. - - Plugins are accessed by index using values from 0 upwards. Out of range - indices MUST result in this function returning NULL, so the host can - enumerate plugins by increasing @a index until NULL is returned. - - Note that @a index has no meaning, hosts MUST NOT depend on it remaining - constant in any way. In other words, @a index is NOT a plugin ID. In - particular, hosts MUST NOT refer to plugins by library path and index in - persistent serialisations (e.g. save files). + + When it is time to load a plugin (designated by its URI), the host loads the + plugin's library, gets the lv2_descriptor() function from it, and uses this + function to find the LV2_Descriptor for the desired plugin. Plugins are + accessed by index using values from 0 upwards. This function MUST return + NULL for out of range indices, so the host can enumerate plugins by + increasing @c index until NULL is returned. + + Note that @c index has no meaning, hosts MUST NOT depend on it remaining + consistent between loads of the plugin library. */ const LV2_Descriptor * lv2_descriptor(uint32_t index); |