diff options
Diffstat (limited to 'core.lv2')
| -rw-r--r-- | core.lv2/lv2.ttl | 163 |
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 <div> element. This can be used by +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 +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). |