aboutsummaryrefslogtreecommitdiffstats
path: root/core.lv2/lv2.ttl
diff options
context:
space:
mode:
Diffstat (limited to 'core.lv2/lv2.ttl')
-rw-r--r--core.lv2/lv2.ttl71
1 files changed, 69 insertions, 2 deletions
diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl
index 23f014d..c3abdbf 100644
--- a/core.lv2/lv2.ttl
+++ b/core.lv2/lv2.ttl
@@ -67,7 +67,7 @@ more details.
doap:name "LV2" ;
doap:homepage <http://lv2plug.in> ;
doap:created "2004-04-21" ;
- doap:shortdesc "An audio processing plugin specification" ;
+ doap:shortdesc "An audio plugin interface specification" ;
doap:programming-language "C" ;
doap:release [
doap:revision "4" ;
@@ -83,7 +83,74 @@ more details.
foaf:name "David Robillard" ;
foaf:homepage <http://drobilla.net/> ;
rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
- ] .
+ ] ; rdfs:comment """
+<h4>Overview</h4>
+There are a large number of open source and free software synthesis packages in
+use or development at this time. This API ("LV2") attempts to give programmers
+the ability to write simple "plugin" audio processors in C/C++ and link
+them dynamically ("plug" them) into a range of these packages ("hosts").
+It should be possible for any host and any plugin to communicate completely
+through this interface.
+
+This API is deliberately as short and simple as possible. The information
+required to use a plugin is in a companion data (RDF) file. The shared
+library portion of the API does not contain enough information to make use
+of the plugin possible; the data file is mandatory.
+
+Plugins can operate on any type of data. Plugins have "ports" that are
+inputs or outputs and each plugin is "run" for a "block" corresponding to
+a short time interval measured in samples. The plugin may assume that all
+its input and output ports have been connected to the relevant data location
+(using the connect_port() function) before it is asked to run, unless the
+port has been set "connection optional" in the plugin's data file.
+
+This "core" specification defines two types of port data, equivalent to those
+in LADSPA: control rate and audio rate. Audio rate data is communicated using
+arrays with one <code>float</code> element per sample processed, allowing
+a block of audio to be processed by the plugin in a single pass. Control
+rate data is communicated using single <code>float</code> values. Control
+rate data has a single value at the start of a call to the run() function
+which is considered valid for the duration of the call to run(). Thus the
+"control rate" is determined by the block size, controlled by the host.
+
+Plugins reside in shared object files suitable for dynamic linking (e.g. by
+dlopen() and family). This file provides one or many plugins via the
+lv2_descriptor() function. These plugins can be instantiated to create
+"plugin instances", which can be connected together to perform tasks.
+
+This API contains very limited error-handling.
+
+<h4>Threading Rules</h4> Certain hosts may need to call the functions
+provided by a plugin from multiple threads. For this to be safe, the plugin
+must be written so that those functions can be executed simultaneously
+without problems. To facilitate this, the functions provided by a plugin
+are divided into classes:
+
+<dl>
+<dt>Discovery Class</dt>
+<dd>lv2_descriptor(), extension_data()</dd>
+<dt>Instantiation Class</dt>
+<dd>instantiate(), cleanup(), activate(), deactivate()</dd>
+<dt>Audio Class</dt>
+<dd>run(), connect_port()</dd>
+</dl>
+
+Extensions to this specification which add new functions MUST declare in
+which of these classes the functions belong, or define new classes for them.
+The rules that hosts MUST follow are:
+
+<ul>
+<li>When a function is running for a plugin instance, no other
+ function in the same class may run for that instance.</li>
+<li>When a function from the Discovery class is running, no other
+ functions in the same shared object file may run.</li>
+<li>When a function from the Instantiation class is running for a plugin
+ instance, no other functions for that instance may run.</li>
+</ul>
+Any simultaneous calls that are not explicitly forbidden by these rules
+are allowed. For example, a host may call run() for two different plugin
+instances simultaneously.
+""" .