diff options
| -rw-r--r-- | core.lv2/ChangeLog | 2 | ||||
| -rw-r--r-- | core.lv2/lv2.h | 89 | ||||
| -rw-r--r-- | core.lv2/lv2.ttl | 35 |
3 files changed, 49 insertions, 77 deletions
diff --git a/core.lv2/ChangeLog b/core.lv2/ChangeLog index 2a86606..643b2cf 100644 --- a/core.lv2/ChangeLog +++ b/core.lv2/ChangeLog @@ -3,7 +3,7 @@ lv2core (UNRELEASED) unstable; urgency=low * Remove lv2config in favour of the convention that extension bundles simply install headers to standard URI-like include paths * Switch to simple BSD-style (ISC) license (with permission of all - contributors to lv2.h and it's ancestor, ladspa.h) + contributors to lv2.h and its ancestor, ladspa.h) -- David Robillard <d@drobilla.net> UNRELEASED 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); diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl index f77a2c4..d18c865 100644 --- a/core.lv2/lv2.ttl +++ b/core.lv2/lv2.ttl @@ -97,12 +97,11 @@ Code, data, and any other resources (e.g. waveforms) are shipped together in a <q>bundle</q> directory. The code contains only the executable portions of the plugin which inherently <em>must</em> be written in code. All other data is provided in the data file(s). This makes plugin data flexible and extensible, -and allows the host to do everything but run the plugin without executing any -code at all. Among other advantages, this makes hosts more robust (broken -plugins can't crash a host during discovery) and allows non-C programs to work -with LV2 data (such as the pure <a href="http://python.org">Python</a> script -which generated this page). LV2 itself and extensions are distributed -similarly.</p> +and allows the host to do everything but run the plugin without loading or +executing any code. Among other advantages, this makes hosts more robust +(broken plugins can't crash a host during discovery) and allows generic tools +and non-C programs to work with LV2 data. LV2 itself and extensions are +distributed in a similar way.</p> <p>An LV2 plugin library is suitable for dynamic loading (e.g. via <code>dlopen()</code>) and provides one or more <a @@ -132,21 +131,15 @@ controlled by the host (and not necessarily constant).</p> into several threading classes:</p> <table> -<tr> - <th>Discovery Class</th> - <th>Instantiation Class</th> - <th>Audio Class</th> -</tr> -<tr> - <td>lv2_descriptor()</td> - <td>LV2_Descriptor::instantiate()</td> - <td>LV2_Descriptor::run()</td> -</tr> -<tr> - <td>LV2_Descriptor::extension_data()</td> - <td>LV2_Descriptor::cleanup()</td> - <td>LV2_Descriptor::connect_port()</td> -</tr> +<tr><th>Discovery Class</th> + <th>Instantiation Class</th> + <th>Audio Class</th></tr> +<tr><td>lv2_descriptor()</td> + <td>LV2_Descriptor::instantiate()</td> + <td>LV2_Descriptor::run()</td></tr> +<tr><td>LV2_Descriptor::extension_data()</td> + <td>LV2_Descriptor::cleanup()</td> + <td>LV2_Descriptor::connect_port()</td></tr> <tr><td></td><td>LV2_Descriptor::activate()</td><td></td></tr> <tr><td></td><td>LV2_Descriptor::deactivate()</td><td></td></tr> </table> |