From b9cbae66b9d5daede2b8f1793278b876a3455f8b Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 2 Mar 2011 06:18:03 +0000 Subject: Tidy up lv2.ttl. --- core.lv2/lv2.ttl | 163 +++++++++++++++++++++++++++---------------------------- 1 file 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 for more information. +# core LV2 specification. See 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 """

Overview

-

-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"). + +

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 float 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 float 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 +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 float 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 float 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 object provides one or more plugin descriptors 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. -

+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.

+

Threading Rules

-

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: -

+ +

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:

+
Discovery Class
lv2_descriptor(), extension_data()
@@ -138,24 +138,23 @@ are divided into classes:
Audio Class
run(), connect_port()
-

-Extensions to this specification which add new functions MUST declare in + +

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: -

+The rules that hosts MUST follow are:

+
    -
  • When a function is running for a plugin instance, no other - function in the same class may run for that instance.
    • -
  • When a function from the Discovery class is running, no other - functions in the same shared object file may run.
    • +
  • When a function is running for a plugin instance, +no other function in the same class may run for that instance.
    • +
  • When a function from the Discovery class is running, +no other functions in the same shared object file may run.
  • When a function from the Instantiation class is running for a plugin - instance, no other functions for that instance may run.
    • +instance, no other functions for that instance may run.
-

-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.

-""" . + +

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.

""" . @@ -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:

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).

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).

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).

""" . @@ -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 ; lv2:documentation """ -

Relates a Resource to documentation markup. The value of this property +

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.

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 XHTML Basic, Section 3 for a list of legal tags.

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