aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2011-03-02 06:18:03 +0000
committerDavid Robillard <d@drobilla.net>2011-03-02 06:18:03 +0000
commitb9cbae66b9d5daede2b8f1793278b876a3455f8b (patch)
treede34a044a093a16e106a2bb37ed18226fe5bca36
parent0a890c2ac8a162287f595d0d00a38f13d16d74a4 (diff)
downloadlv2-b9cbae66b9d5daede2b8f1793278b876a3455f8b.tar.xz
Tidy up lv2.ttl.
-rw-r--r--core.lv2/lv2.ttl163
1 files changed, 81 insertions, 82 deletions
diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl
index e3f16da..39efbdc 100644
--- a/core.lv2/lv2.ttl
+++ b/core.lv2/lv2.ttl
@@ -2,7 +2,7 @@
# 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.
+# core LV2 specification. See <http://lv2plug.in> for more information.
#
# Copyright (C) 2006-2009 Steve Harris, David Robillard
#
@@ -52,7 +52,7 @@ lv2:Specification a rdfs:Class ;
An LV2 specification (i.e. this specification, or an LV2 "extension").
Specification data, like plugin data, is distributed in standardized bundles
-so hosts may discover all present LV2 data. See http://lv2plug.in/docs for
+so hosts may discover all present LV2 data. See http://lv2plug.in/docs for
more details.
""" .
@@ -86,50 +86,50 @@ more details.
] ;
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").
+
+<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
-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.
-</p><p>
-Plugins reside in shared object files suitable for dynamic linking (e.g. by
+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
+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.</p>
+
+<p>Plugins reside in shared object files suitable for dynamic linking (e.g. by
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.
-</p>
+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.</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>
+
+<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>
@@ -138,24 +138,23 @@ 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
+
+<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>
+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>
-<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 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>
+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.</p>
-""" .
+
+<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.</p>""" .
@@ -167,9 +166,9 @@ lv2:Template a rdfs:Class ;
rdfs:subClassOf lv2:Resource ;
rdfs:comment """
An abstract plugin-like resource that may not actually be an LV2 plugin
-(e.g. may not actually have a plugin binary). A Template is a Resource
-that may have ports, and otherwise mimic the structure of a plugin.
-This should be subclassed by extensions that define such things.
+(e.g. may not actually have a plugin binary). A Template is a Resource that
+may have ports, and otherwise mimic the structure of a plugin. This should be
+subclassed by extensions that define such things.
""" .
lv2:Plugin a rdfs:Class ;
@@ -192,10 +191,10 @@ with no language tag.
rdfs:comment """
The class which represents an LV2 plugin.
-Plugins SHOULD have a doap:license property whenever possible.
-The doap:name property should be at most a few words in length using title
-capitalization, e.g. "Tape Delay Unit". Use doap:shortdesc or
-doap:description for more detailed descriptions.
+Plugins SHOULD have a doap:license property whenever possible. The doap:name
+property should be at most a few words in length using title capitalization,
+e.g. "Tape Delay Unit". Use doap:shortdesc or doap:description for more
+detailed descriptions.
""" .
@@ -261,13 +260,13 @@ the following properties:</p>
</ul>
<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
+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).</p>
<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
+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
@@ -275,8 +274,8 @@ not recognize).</p>
<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
+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).</p>
""" .
@@ -329,11 +328,11 @@ lv2:revision a rdf:Property ;
rdfs:range xsd:nonNegativeInteger ;
rdfs:label "revision" ;
rdfs:comment """
-The revision of an LV2 Resource. If a plugin's port indices change, the
-revision of the plugin MUST be increased. Note that if port symbols
+The revision of an LV2 Resource. If a plugin's port indices change, the
+revision of the plugin MUST be increased. Note that if port symbols
change or are removed, the plugin URI MUST be changed, the revision acts
as a 'minor version' to distinguish otherwise compatible revisions of
-a plugin. A plugin that has changed indices MUST have a lv2:revision
+a plugin. A plugin that has changed indices MUST have a lv2:revision
property, if a plugin has no revision property it is assumed to be 0.
Anything that refers to a specific revision of a plugin (e.g. a serialisation
@@ -369,15 +368,15 @@ lv2:documentation a rdf:Property ;
rdfs:label "documentation" ;
rdfs:seeAlso <http://www.w3.org/TR/xhtml-basic/> ;
lv2:documentation """
-<p>Relates a Resource to documentation markup. The value of this property
+<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
+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
+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"
+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>
""" .
@@ -404,7 +403,7 @@ A short name used as a machine and human readable identifier.
The first character must be one of _, a-z or A-Z and subsequenct characters can
be from _, a-z, A-Z and 0-9.
-A language tag MUST NOT be used on this property. The symbol uniquely
+A language tag MUST NOT be used on this property. The symbol uniquely
identifies the port on a plugin with a given URI (i.e. the plugin author MUST
change the plugin URI if a port symbol is changed or removed).
""" .
@@ -429,7 +428,7 @@ property without changing the Plugin URI.
lv2:Point a rdfs:Class ;
rdfs:label "Port value point" ;
rdfs:comment """
-Used to describe interesting values in a Port's range. To be valid it
+Used to describe interesting values in a Port's range. To be valid it
requires two properties: rdfs:label and rdf:value.
There are 3 specially defined Points in the LV2 specification (default,
@@ -604,12 +603,12 @@ lv2:reportsLatency a lv2:PortProperty ;
rdfs:label "Latency reporting port" ;
rdfs:comment """
Indicates that the port is used to express the processing latency incurred by
-the plugin, expressed in samples. The latency may be affected by the current
+the plugin, expressed in samples. The latency may be affected by the current
sample rate, plugin settings, or other factors, and may be changed by the
-plugin at any time. Where the latency is frequency dependent the plugin may
-choose any appropriate value. If a plugin introduces latency it MUST provide
+plugin at any time. Where the latency is frequency dependent the plugin may
+choose any appropriate value. If a plugin introduces latency it MUST provide
EXACTLY ONE port with this property set which informs the host of the "correct"
-latency. In "fuzzy" cases the value output should be the most reasonable based
+latency. In "fuzzy" cases the value output should be the most reasonable based
on user expectation of input/output alignment (eg. musical delay/echo plugins
should not report their delay as latency, as it is an intentional effect).
""" .
@@ -644,8 +643,8 @@ lv2:enumeration a lv2:PortProperty ;
rdfs:label "Enumeration" ;
rdfs:comment """
Indicates that a port's only reasonable values are the scale points defined for
-that port. Though a host SHOULD NOT allow a user to set the value of such a
-port to anything other than a scale point. A plugin MUST operate reasonably
+that port. Though a host SHOULD NOT allow a user to set the value of such a
+port to anything other than a scale point. A plugin MUST operate reasonably
even if such a port has an input that is not a scale point, preferably by
simply choosing the largest enumeration value less than or equal to the
actual input value (i.e. round the input value down).