aboutsummaryrefslogtreecommitdiffstats
path: root/core.lv2/lv2.ttl
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2010-11-26 20:25:02 +0000
committerDavid Robillard <d@drobilla.net>2010-11-26 20:25:02 +0000
commite0c4fb1bc1c66e5655a41ddcbfaafb07e32b93a2 (patch)
treea73d27c9839bd99ef8e14ac3efec8d59d21c756d /core.lv2/lv2.ttl
parenta31c23155b8b1902f70a63a12d7c09822dacda04 (diff)
downloadlv2-e0c4fb1bc1c66e5655a41ddcbfaafb07e32b93a2.tar.xz
Mark up documentation with lv2:documentation as per discussion on lv2-dev.
Use unified lv2plug.in style for ontology documentation.
Diffstat (limited to 'core.lv2/lv2.ttl')
-rw-r--r--core.lv2/lv2.ttl108
1 files changed, 52 insertions, 56 deletions
diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl
index c3abdbf..68c8891 100644
--- a/core.lv2/lv2.ttl
+++ b/core.lv2/lv2.ttl
@@ -1,5 +1,5 @@
# RDF Schema for LV2 plugins
-# PROVISIONAL Revision 4
+# PROVISIONAL Revision 4.0pre1
#
# This document describes the classes and properties that are defined by the
# core LV2 specification. See <http://lv2plug.in> for more information.
@@ -70,8 +70,8 @@ more details.
doap:shortdesc "An audio plugin interface specification" ;
doap:programming-language "C" ;
doap:release [
- doap:revision "4" ;
- doap:created "2009-08-16"
+ doap:revision "4.0pre2" ;
+ doap:created "2010-11-05"
] ;
doap:maintainer [
a foaf:Person ;
@@ -83,27 +83,29 @@ more details.
foaf:name "David Robillard" ;
foaf:homepage <http://drobilla.net/> ;
rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
- ] ; rdfs:comment """
+ ] ;
+ lv2:documentation """
<h4>Overview</h4>
+<p>
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.
-
+</p><p>
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.
-
+</p><p>
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.
-
+</p><p>
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
@@ -112,20 +114,22 @@ 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.
-
+</p><p>
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
+dlopen() and family). This object provides one or more <a
+href="urn:struct:LV2_Descriptor">plugin descriptors</a> via the
lv2_descriptor() function. These plugins can be instantiated to create
"plugin instances", which can be connected together to perform tasks.
-
+</p><p>
This API contains very limited error-handling.
-
-<h4>Threading Rules</h4> Certain hosts may need to call the functions
+</p>
+<h4>Threading Rules</h4>
+<p>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:
-
+</p>
<dl>
<dt>Discovery Class</dt>
<dd>lv2_descriptor(), extension_data()</dd>
@@ -134,11 +138,11 @@ are divided into classes:
<dt>Audio Class</dt>
<dd>run(), connect_port()</dd>
</dl>
-
+<p>
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:
-
+</p>
<ul>
<li>When a function is running for a plugin instance, no other
function in the same class may run for that instance.</li>
@@ -147,9 +151,10 @@ The rules that hosts MUST follow are:
<li>When a function from the Instantiation class is running for a plugin
instance, no other functions for that instance may run.</li>
</ul>
+<p>
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.
+instances simultaneously.</p>
""" .
@@ -242,36 +247,38 @@ language tag.
rdfs:comment """
A port MUST have at least one lv2:name which is of type xsd:string.
""" ] ;
- rdfs:comment """
-The class which represents an LV2 port.
+ lv2:documentation """
+<p>The class which represents an LV2 port.</p>
-In order for it to be used by a host it MUST have at least
-the following properties:
- rdf:type (with object one of lv2:Port, lv2:InputPort, lv2:OutputPort)
- rdf:type (more specific port class, see below)
- lv2:index
- lv2:symbol
- lv2:name
+<p>In order for it to be used by a host it MUST have at least
+the following properties:</p>
+<ul>
+<li>rdf:type (with object one of lv2:Port, lv2:InputPort, lv2:OutputPort)</li>
+<li>rdf:type (more specific port class, see below)</li>
+<li>lv2:index</li>
+<li>lv2:symbol</li>
+<li>lv2:name</li>
+</ul>
-All LV2 port descriptions MUST have a property rdf:type where the object is
+<p>All LV2 port descriptions MUST have a property rdf:type where the object is
one of lv2:Port lv2:InputPort or lv2:OutputPort. Additionally there MUST
be at least one other rdf:type property which more specifically describes
-type of the port (e.g. lv2:AudioPort).
+type of the port (e.g. lv2:AudioPort).</p>
-Hosts that do not support a specific port class MUST NOT instantiate the
+<p>Hosts that do not support a specific port class MUST NOT instantiate the
plugin, unless that port has the connectionOptional property set (in which case
the host can simply "connect" that port to NULL). If a host is interested
in plugins to insert in a certain signal path (e.g. stereo audio), it SHOULD
consider all the classes of a port to determine which ports are most suitable
for connection (e.g. by ignoring ports with additional classes the host does
-not recognize).
+not recognize).</p>
-A port has two identifiers - a (numeric) index, and a (textual) symbol.
+<p>A port has two identifiers - a (numeric) index, and a (textual) symbol.
The index can be used as an identifier at run-time, but persistent references
to ports (e.g. in a saved preset) MUST use the symbol. A symbol is guaranteed
to refer to the same port on all plugins with a given URI. An index does NOT
necessarily refer to the same port on all plugins with a given URI (i.e. the
-index for a port may differ between plugin binaries).
+index for a port may differ between plugin binaries).</p>
""" .
lv2:InputPort a rdfs:Class ;
@@ -340,39 +347,28 @@ version to distinguish incompatible objects (use the URI for that).
####################################
-## Optional Plugin RDF Properties ##
+## Documentation ##
####################################
-lv2:basicXHTML a rdfs:Class ;
- rdfs:seeAlso <http://www.w3.org/TR/xhtml1/> ;
- rdfs:seeAlso <http://www.w3.org/TR/xhtml-modularization/> ;
- rdfs:comment """
-A very basic subset of XHTML for use with lv2:documentation, intended to be
-reasonable for hosts to support for styled inline documentation.
-
-A literal with this data type is an XHTML 1.0 fragment containing only
-tags from the following XHTML modules: text, hypertext, list, basic tables,
-image, presentation. See the XHTML and XHTML Modularization specifications
-for details. A literal with this data type must be legal to insert as the
-body of a &lt;div&gt; tag (free text is allowed).
-
-If only basicXHTML documentation is given but a host has no facilities for
-handling tags, simply stripping tags and inserting newlines after appropriate
-tags will yield a somewhat readable plain text version of the documentation.
-""" .
-
lv2:documentation a rdf:Property ;
rdfs:domain lv2:Resource ;
+ rdfs:range rdfs:Literal ;
rdfs:label "documentation" ;
- rdfs:comment """
-Relates a Plugin to some text/audio/video documentation either online or
-included with the plugin package. The value of this property may be either a
-URL, or a literal of any type. Literal documentation SHOULD be either plain
-text, or lv2:basicXHTML. More advanced documentation should be linked to instead.
+ rdfs:seeAlso <http://www.w3.org/TR/xhtml-basic/> ;
+ lv2:documentation """
+<p>Relates a Resource to documentation markup. The value of this property
+MUST be a string literal which is a valid XHTML Basic 1.1 fragment suitable
+for use as the content of a &lt;div&gt; element. This can be used by
+hosts to provide rich online documentation or by tools to generate external
+documentation pages. The standard language tagging facility of RDF can be
+used to provide multi-lingual documentation.</p>
+<p>XHTML Basic is a W3C Recommendation which defines a basic subset of XHTML
+intended to be reasonable to implement with limited resources (e.g. on embedded
+devices). See <a href="http://www.w3.org/TR/xhtml-basic/#s_xhtmlmodules"
+>XHTML Basic, Section 3</a> for a list of legal tags.</p>
""" .
-
###################################
## Mandatory Port RDF Properties ##
###################################