aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2011-10-26 19:53:59 +0000
committerDavid Robillard <d@drobilla.net>2011-10-26 19:53:59 +0000
commite4810455eca0f51f7236e0e3f62bea9f96436621 (patch)
treefdb0a3f1b8daf53b44b571373227a9d657ab298c
parent2f2e2fc2dd54cf2e932db54d91c01ad2812a0c8c (diff)
downloadlv2-e4810455eca0f51f7236e0e3f62bea9f96436621.tar.xz
Rewrite and clean up some documentation.
-rw-r--r--core.lv2/ChangeLog2
-rw-r--r--core.lv2/lv2.h89
-rw-r--r--core.lv2/lv2.ttl35
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>