diff options
Diffstat (limited to 'core.lv2/lv2.ttl')
| -rw-r--r-- | core.lv2/lv2.ttl | 108 |
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 <div> 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 <div> 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 ## ################################### |