From 5c0e357c9167dc0bd17d5c365786b392ab456baf Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Tue, 5 Oct 2010 18:51:31 +0000
Subject: Move textey documentation to lv2.ttl (for nice generated
 documentation). Update somewhat cobwebby documentation. Clean up and shrink
 lv2.h.

---
 core.lv2/lv2.ttl | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 69 insertions(+), 2 deletions(-)

(limited to 'core.lv2/lv2.ttl')

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.
+""" .
 
 
 
-- 
cgit v1.2.1