From e4810455eca0f51f7236e0e3f62bea9f96436621 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 26 Oct 2011 19:53:59 +0000 Subject: Rewrite and clean up some documentation. --- core.lv2/ChangeLog | 2 +- core.lv2/lv2.h | 89 +++++++++++++++++++++--------------------------------- 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 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 LV2 Ontology Documentation 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 , 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 bundle directory. The code contains only the executable portions of the plugin which inherently must 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 Python script -which generated this page). LV2 itself and extensions are distributed -similarly.

+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.

An LV2 plugin library is suitable for dynamic loading (e.g. via dlopen()) and provides one or more into several threading classes:

- - - - - - - - - - - - - - - + + + + + + + + +
Discovery ClassInstantiation ClassAudio Class
lv2_descriptor()LV2_Descriptor::instantiate()LV2_Descriptor::run()
LV2_Descriptor::extension_data()LV2_Descriptor::cleanup()LV2_Descriptor::connect_port()
Discovery ClassInstantiation ClassAudio Class
lv2_descriptor()LV2_Descriptor::instantiate()LV2_Descriptor::run()
LV2_Descriptor::extension_data()LV2_Descriptor::cleanup()LV2_Descriptor::connect_port()
LV2_Descriptor::activate()
LV2_Descriptor::deactivate()
-- cgit v1.2.1