diff options
author | David Robillard <d@drobilla.net> | 2010-11-26 20:25:02 +0000 |
---|---|---|
committer | David Robillard <d@drobilla.net> | 2010-11-26 20:25:02 +0000 |
commit | e0c4fb1bc1c66e5655a41ddcbfaafb07e32b93a2 (patch) | |
tree | a73d27c9839bd99ef8e14ac3efec8d59d21c756d /ext | |
parent | a31c23155b8b1902f70a63a12d7c09822dacda04 (diff) | |
download | lv2-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 'ext')
-rw-r--r-- | ext/atom.lv2/atom.ttl | 157 | ||||
-rw-r--r-- | ext/contexts.lv2/contexts.ttl | 52 | ||||
-rw-r--r-- | ext/data-access.lv2/data-access.ttl | 4 | ||||
-rw-r--r-- | ext/dyn-manifest.lv2/dyn-manifest.ttl | 4 | ||||
-rw-r--r-- | ext/event.lv2/event.ttl | 8 | ||||
-rw-r--r-- | ext/files.lv2/files.ttl | 31 | ||||
-rw-r--r-- | ext/host-info.lv2/host-info.ttl | 10 | ||||
-rw-r--r-- | ext/instance-access.lv2/instance-access.ttl | 4 | ||||
-rw-r--r-- | ext/message.lv2/message.ttl | 42 | ||||
-rw-r--r-- | ext/midi.lv2/midi.ttl | 14 | ||||
-rw-r--r-- | ext/parameter.lv2/parameter.ttl | 20 | ||||
-rw-r--r-- | ext/persist.lv2/persist.ttl | 68 | ||||
-rw-r--r-- | ext/presets.lv2/presets.ttl | 4 | ||||
-rw-r--r-- | ext/resize-port.lv2/resize-port.ttl | 12 | ||||
-rw-r--r-- | ext/string-port.lv2/string-port.ttl | 4 | ||||
-rw-r--r-- | ext/uri-map.lv2/uri-map.ttl | 4 | ||||
-rw-r--r-- | ext/uri-unmap.lv2/uri-unmap.ttl | 6 |
17 files changed, 220 insertions, 224 deletions
diff --git a/ext/atom.lv2/atom.ttl b/ext/atom.lv2/atom.ttl index 7702d21..ff0cf7e 100644 --- a/ext/atom.lv2/atom.ttl +++ b/ext/atom.lv2/atom.ttl @@ -37,103 +37,104 @@ foaf:homepage <http://drobilla.net/> ; rdfs:seeAlso <http://drobilla.net/drobilla.rdf> ] ; - rdfs:comment """ -This extension defines a generic format for a typed piece of data, called an + lv2:documentation """ +<p>This extension defines a generic format for a typed piece of data, called an "<a href="#Atom">Atom</a>" (e.g. integers, strings, buffers, data structures, etc). Atoms allow LV2 plugins and hosts to communicate, process, serialise, and store values of any type via a generic mechanism (e.g. LV2 ports, events, disk, shared memory, network). Atoms are, with one exception, Plain Old Data (POD) and may be safely copied (e.g. with a simple call to -<code>memcpy</code>). +<code>memcpy</code>).</p> -Since Atom communication can be implemented generically, plugins that +<p>Since Atom communication can be implemented generically, plugins that understand some type can be used together in a host that does not understand that type, and plugins (e.g. routers, delays) can process atoms of unknown -type. +type.</p> -An Atom can be trivially constructed in-place from an +<p>An Atom can be trivially constructed in-place from an <a href="http://lv2plug.in/ns/ext/event#Event">Event</a> as defined by the <a href="http://lv2plug.in/ns/ext/event">LV2 Event</a> extension. In other words, an Event is simply an Atom with a time stamp header. Atoms SHOULD be used anywhere a "value" needs to be stored or communicated, to allow -implementations to be polymorphic and extensible. +implementations to be polymorphic and extensible.</p> -Atoms (the start of the LV2_Atom header) MUST be 32-bit aligned. +<p>Atoms (the start of the LV2_Atom header) MUST be 32-bit aligned.</p> -Optionally, the host MAY implement <a href="#blobSupport">blob support</a>. +<p>Optionally, the host MAY implement <a href="#blobSupport">blob support</a>. A <a href="#Blob">Blob</a> is a dynamically allocated chunk of memory that (unlike an Atom) is not necessarily POD. Blobs are accessed via a <a href="#Reference">Reference</a>, which is a special case of Atom that always has <code>type = 0</code>, is not POD, and can only be copied using host provided functions. This allows plugins and hosts to work with data -of any type at all. +of any type at all.</p> -Atoms can be communicated in many ways. Since an Atom is the payload of an +<p>Atoms can be communicated in many ways. Since an Atom is the payload of an Event, an <a href="http://lv2plug.in/ns/ext/event#EventPort">EventPort</a> can be used for communicating Atoms in realtime with sub-sample time stamp accuracy. This extension also defines two port types for connecting directly -to a single Atom: <a href="ValuePort">ValuePort</a> and <a href="#MessagePort" +to a single Atom: <a href="#ValuePort">ValuePort</a> and <a href="#MessagePort" >MessagePort</a>, which both have the same buffer format but different -semantics (with respect to how the run() callback interprets the Atom). +semantics (with respect to how the run() callback interprets the Atom).</p> -This extension requires the host to support the <a -href="http://lv2plug.in/ns/ext/uri-map">LV2 URI Map</a> extension. +<p>This extension requires the host to support the <a +href="http://lv2plug.in/ns/ext/uri-map">LV2 URI Map</a> extension.</p> """ . atom:Atom a rdfs:Class ; rdfs:label "Atom" ; - rdfs:comment """ -Abstract base class for all atoms. An <a href="urn:struct:LV2_Atom" + lv2:documentation """ +<p>Abstract base class for all atoms. An <a href="urn:struct:LV2_Atom" >LV2_Atom</a> has a 16-bit <code>type</code> and <code>size</code> followed by -a <code>body</code>. +a <code>body</code>.</p> -All concrete Atom types (subclasses of this class) MUST define a precise -binary layout for <code>body</code>. +<p>All concrete Atom types (subclasses of this class) MUST define a precise +binary layout for <code>body</code>.</p> -The <code>type</code> field is the URI of a subclass of Atom mapped to an +<p>The <code>type</code> field is the URI of a subclass of Atom mapped to an integer using the <a href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's <a href="urn:struct:LV2_URI_Map_Feature" >LV2_URI_Map_Feature</a>::uri_to_id with <code>map = "http://lv2plug.in/ns/ext/event"</code>. If a plugin or host does not understand <code>type</code>, that atom SHOULD be gracefully ignored -(though it MAY be copied if it is not a <a href="#Reference">Reference</a>). +(or copied if it is not a <a href="#Reference">Reference</a>).</p> -All atoms are POD by definition except references, which have +<p>All atoms are POD by definition except references, which have <code>type = 0</code>. An Atom MUST NOT contain a Reference. It is safe to copy any non-reference Atom with a simple <code>memcpy</code>, even if -the implementation does not understand <code>type</code>. +the implementation does not understand <code>type</code>.</p> """ . atom:Reference a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Reference" ; - rdfs:comment """ -Reference to a <a href="#Blob">Blob</a>. The actual contents of a Reference + lv2:documentation """ +<p>Reference to a <a href="#Blob">Blob</a>. The actual contents of a Reference are opaque and host specific, and must not be copied, serialized, or otherwise interpreted by a plugin, except via functions provided by the host in -<a href="urn:struct:LV2_Blob_Support">LV2_Blob_Support</a>. +<a href="urn:struct:LV2_Blob_Support">LV2_Blob_Support</a>.</p> -A Reference is a special case of Atom with <code>type = 0</code>. -"Null" is the unique Atom with <code>type = 0</code> and <code>size = 0</code>. +<p>A Reference is a special case of Atom with <code>type = 0</code>. +"Null" is the unique Atom with <code>type = 0</code> and +<code>size = 0</code>.</p> """ . atom:String a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "String" ; - rdfs:comment """ -A UTF-8 encoded string, with an optional language tag. An + lv2:documentation """ +<p>A UTF-8 encoded string, with an optional language tag. An <a href="urn:struct:LV2_Atom_String">LV2_Atom_String</a> has an <a href="#ID">ID</a> <code>lang</code> followed by the string data in UTF-8 encoding. The length of the string data in bytes is <code>size - sizeof(uint32_t)</code>, including the terminating NULL character. The <code>lang</code> may be any URI; to describe a human language, use http://lexvo.org/id/term/LANG where LANG is an <a href="http://www.loc.gov/standards/iso639-2/">ISO 693-2</a> or -<a href="http://www.loc.gov/standards/iso639-2/">ISO 693-3</a> language code. +<a href="http://www.loc.gov/standards/iso639-2/">ISO 693-3</a> language code.</p> -For example, "Hello" in English: +<p>For example, "Hello" in English:</p> <pre> struct LV2_Atom { uint16_t type = uri_to_id(atom:String); @@ -151,7 +152,7 @@ struct LV2_Atom { uint32_t lang = uri_to_id("http://lexvo.org/id/term/fr"); char str[] = "Bonjour"; </pre> -or a Turtle string: +<p>or a Turtle string:</p> <pre> struct LV2_Atom { uint16_t type = uri_to_id(atom:String); @@ -166,7 +167,7 @@ char str[] = "<http://example.org/foo> a <http://example.org/Thing& atom:ID a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Integer ID mapped from a URI" ; - rdfs:comment """ + lv2:documentation """ An unsigned 32-bit integer mapped from a URI using the <a href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's <a href="urn:struct:LV2_URI_Map_Feature">LV2_URI_Map_Feature</a>::uri_to_id @@ -177,7 +178,7 @@ with <code>map = NULL</code>. atom:BlankID a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Integer ID for a blank node" ; - rdfs:comment """ + lv2:documentation """ An unsigned 32-bit integer identifier for a blank node. A BlankID is only meaningful within a limited scope (e.g. the Atom in which it appears), and MUST NOT be used as a global identifier. In particular, a BlankID is NOT an @@ -188,17 +189,17 @@ ID, and can not be mapped to/from a URI. atom:Vector a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Vector" ; - rdfs:comment """ -A homogeneous sequence of atoms with equivalent type and size. + lv2:documentation """ +<p>A homogeneous sequence of atoms with equivalent type and size.</p> -An <a href="urn:struct:LV2_Atom_Vector">LV2_Atom_Vector</a> is a +<p>An <a href="urn:struct:LV2_Atom_Vector">LV2_Atom_Vector</a> is a 16-bit <code>elem_count</code> and <code>elem_type</code> followed by <code>elem_count</code> atom bodies of type <code>elem_type</code>. The element type must be a fixed size <a href="#Atom">Atom</a> type, i.e. the -size of each element is the vector's <code>size / elem_count</code>. +size of each element is the vector's <code>size / elem_count</code>.</p> -For example, an atom:Vector containing 42 elements of type atom:Float looks -like this in memory: +<p>For example, an atom:Vector containing 42 elements of type atom:Float looks +like this in memory:</p> <pre> struct LV2_Atom { uint16_t type = uri_to_id(atom:Vector); @@ -214,31 +215,31 @@ float elem_01; float elem_41; </pre> -Note that it is possible to construct a valid Atom for each element +<p>Note that it is possible to construct a valid Atom for each element of the vector, even by an implementation which does not understand -<code>elem_type</code>. +<code>elem_type</code>.</p> -A Vector header is 64-bits, thus the first element of a Vector is 64-bit -aligned if the Vector itself is 64-bit aligned. +<p>A Vector header is 64-bits, thus the first element of a Vector is 64-bit +aligned if the Vector itself is 64-bit aligned.</p> """ . atom:Tuple a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Tuple" ; - rdfs:comment """ -A sequence of <a href="#Atom">atoms</a> with varying <code>type</code> -and <code>size</code>. + lv2:documentation """ +<p>A sequence of <a href="#Atom">atoms</a> with varying <code>type</code> +and <code>size</code>.</p> -The body of a Tuple is simply a sequence of complete atoms, each aligned to -32 bits. +<p>The body of a Tuple is simply a sequence of complete atoms, each aligned to +32 bits.</p> """ . atom:Property a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Property of an Object" ; - rdfs:comment """ + lv2:documentation """ A single property of some <a href="#Object">Object</a>. An <a href="urn:struct:LV2_Atom_Property">LV2_Atom_Property</a> has an <a href="#ID">ID</a> <code>key</code> and @@ -249,30 +250,30 @@ has an <a href="#ID">ID</a> <code>key</code> and atom:Object a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Object" ; - rdfs:comment """ -Abstract base class for an "Object", i.e. an <a href="#Atom">Atom</a> + lv2:documentation """ +<p>Abstract base class for an "Object", i.e. an <a href="#Atom">Atom</a> with a number of <a href="#Property">properties</a>. An <a href="urn:struct:LV2_Object">LV2_Object</a> is an unsigned 32-bit integer <code>context</code> and <code>id</code> followed by a sequence of -<a href="urn:struct:LV2_Atom_Property" >properties</a>. +<a href="urn:struct:LV2_Atom_Property" >properties</a>.</p> -The <code>context</code> is mapped using the <a +<p>The <code>context</code> is mapped using the <a href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's <a href="urn:struct:LV2_URI_Map_Feature">LV2_URI_Map_Feature</a>::uri_to_id -with <code>map = NULL</code>, and may be 0 (the default context). +with <code>map = NULL</code>, and may be 0 (the default context).</p> -Note this is an abstract class, i.e. no Atom can exist with +<p>Note this is an abstract class, i.e. no Atom can exist with <code>type = uri_to_id(atom:Object)</code>. An Object is either a <a href="urn:struct:LV2_Resource">Resource</a> or a <a href="urn:struct:Blank">Blank</a>, but the <code>body</code> always has the same binary format. Thus, both named and anonymous objects can be handled -with common code using only a 64-bit header for both. +with common code using only a 64-bit header for both.</p> """ . atom:Resource a rdfs:Class ; rdfs:subClassOf atom:Object ; - rdfs:comment """ + lv2:documentation """ An <a href="#Object">Object</a> where <code>id</code> is the URI of the resource mapped to an <a href="#ID">ID</a>. """ . @@ -280,7 +281,7 @@ URI of the resource mapped to an <a href="#ID">ID</a>. atom:Blank a rdfs:Class ; rdfs:subClassOf atom:Object ; - rdfs:comment """ + lv2:documentation """ An <a href="#Object">Object</a> where <code>id</code> is the blank node ID of the object, which is only meaningful within a certain limited scope (e.g. the container of the Blank) and MUST NOT be used as a global ID. @@ -291,14 +292,14 @@ In particular, <code>id</code> is NOT an <a href="ID">ID</a>. atom:Model a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Model" ; - rdfs:comment """ + lv2:documentation """ A description of a set of <a href="#Object">objects</a>. In memory, a Model is simply a sequence of objects. """ . atom:Bang a rdfs:Class ; rdfs:subClassOf atom:Atom ; - rdfs:label "Bang (activity) (<code>size = 0</code>)" . + rdfs:label "Bang (activity) (size = 0)" . atom:Byte a rdfs:Class ; @@ -327,7 +328,7 @@ atom:Double a rdfs:Class ; atom:blobSupport a lv2:Feature ; rdfs:label "Blob support" ; - rdfs:comment """ + lv2:documentation """ Support for dynamically allocated blobs. If a host supports this feature, it MUST pass a <a href="urn:struct:LV2_Feature">LV2_Feature</a> with <code>URI</code> http://lv2plug.in/ns/ext/atom#blobSupport @@ -338,46 +339,46 @@ and <code>data</code> pointing to a <a href="urn:struct:LV2_Blob_Support" atom:Blob a rdfs:Class ; rdfs:label "Blob" ; - rdfs:comment """ -Base class for all dynamically allocated blobs. An <a + lv2:documentation """ +<p>Base class for all dynamically allocated blobs. An <a href="urn:struct:LV2_Blob" >LV2_Blob</a> ia an opaque pointer to host data. The type and data of a blob can be accessed via host-provided functions in <a href="urn:struct:LV2_Blob_Support">LV2_Blob_Support</a>. The type of a blob can be any URI that describes a data format. Blobs are -always allocated by the host, and unlike atoms are not necessarily POD. +always allocated by the host, and unlike atoms are not necessarily POD.</p> -Blob data MUST NOT be used in any way by an implementation that does not +<p>Blob data MUST NOT be used in any way by an implementation that does not understand that blob type (unlike Atoms, meaningful type-oblivious use -of a Blob is impossible). +of a Blob is impossible).</p> """ . atom:AtomPort a rdfs:Class ; rdfs:subClassOf lv2:Port ; rdfs:label "Atom Port" ; - rdfs:comment """ -A port which contains an <a href="#Atom">Atom</a>. Ports of this type will + lv2:documentation """ +<p>A port which contains an <a href="#Atom">Atom</a>. Ports of this type will be connected to a 32-bit aligned <a href="urn:struct:LV2_Atom">LV2_Atom</a> -immediately followed by <code>size</code> bytes of data. +immediately followed by <code>size</code> bytes of data.</p> -This is an abstract port type, i.e. a port MUST NOT only be an AtomPort, +<p>This is an abstract port type, i.e. a port MUST NOT only be an AtomPort, but must be a more descriptive type that is a subclass of AtomPort which defines the port's semantics (typically <a href="#ValuePort">ValuePort</a> -or <a href="#MessagePort">MessagePort</a>). +or <a href="#MessagePort">MessagePort</a>).</p> -Before calling a method on the plugin that writes to an AtomPort output, +<p>Before calling a method on the plugin that writes to an AtomPort output, the host MUST set the size of the Atom in that output to the amount of available memory immediately following the Atom header. The plugin MUST write a valid Atom to that port (leaving it untouched is illegal). If there is no reasonable value to write to the port, the plugin MUST write NULL -(the Atom with both <code>type = 0</code> and <code>size = 0</code>). +(the Atom with both <code>type = 0</code> and <code>size = 0</code>).</p> """ . atom:ValuePort a rdfs:Class ; rdfs:subClassOf atom:AtomPort ; rdfs:label "Value Port" ; - rdfs:comment """ + lv2:documentation """ An AtomPort that interprets its data as a persistent and time-independent "value". <ul> @@ -411,7 +412,7 @@ atom:supports a rdf:Property ; rdfs:domain lv2:Port ; rdfs:range atom:Atom ; rdfs:label "supports" ; - rdfs:comment """ + lv2:documentation """ Indicates that a Port supports a certain <a href="#Atom">Atom</a> type. This is distinct from the port type - e.g. the port type ValuePort can hold atoms with many different types. This property is used to describe which diff --git a/ext/contexts.lv2/contexts.ttl b/ext/contexts.lv2/contexts.ttl index ad37d95..187acd0 100644 --- a/ext/contexts.lv2/contexts.ttl +++ b/ext/contexts.lv2/contexts.ttl @@ -35,32 +35,32 @@ a lv2:Specification ; a lv2:Feature ; doap:name "LV2 Contexts" ; - rdfs:comment """ -An extension for LV2 plugins which have several execution contexts. + lv2:documentation """ +<p>An extension for LV2 plugins which have several execution contexts.</p> -Contexts allow plugins to run several tasks in parallel and process port +<p>Contexts allow plugins to run several tasks in parallel and process port input/output in multiple threads. Contexts can be used to add non-realtime functionality to a plugin while still keeping the audio run() method -realtime safe. +realtime safe.</p> -Any host which supports this extension must pass an LV2_Feature to +<p>Any host which supports this extension must pass an LV2_Feature to the plugin's instantiate method with URI http://lv2plug.in/ns/ext/contexts -and a pointer to a +and a pointer to a</p> <pre> struct { void* host_handle; void (*request_run)(void* host_handle, const char* context_uri); } </pre> -where the plugin may call request_run with the given host_handle (from any -context) to demand immediate execution of the context specified. +<p>where the plugin may call request_run with the given host_handle (from any +context) to demand immediate execution of the context specified.</p> -If the host does not support blocking contexts, request_run may be set to NULL, -but plugins which have a :BlockingContext which is :mandatory MUST NOT be -instantiated. If the plugin has ANY context which is :hardRTCapable, -request_run must be realtime safe (as defined by lv2:hardRTCapable). +<p>If the host does not support blocking contexts, request_run may be set to +NULL, but plugins which have a :BlockingContext which is :mandatory MUST NOT +be instantiated. If the plugin has ANY context which is :hardRTCapable, +request_run must be realtime safe (as defined by lv2:hardRTCapable).</p> -Unless otherwise stated, each context (defined by some URI) adds a new +<p>Unless otherwise stated, each context (defined by some URI) adds a new threading class similar to the Audio class defined by LV2. Each context has a run callback and a connect_port callback both in the same class (i.e. can't be called concurrently), but may be called concurrently with functions for other @@ -68,8 +68,8 @@ contexts (excluding the Instantiation class). Context properties such as ctx:hardRTCapable apply to both functions. The host MUST only call the correct connect_port function associated with the context for that port, i.e. it is an error to use the main LV2 connect_port -function on a port with a context other than the main LV2 run function. -"""^^lv2:basicXHTML . +function on a port with a context other than the main LV2 run function.</p> +""" . ########################## @@ -78,21 +78,21 @@ function on a port with a context other than the main LV2 run function. ctx:Context a rdfs:Class ; rdfs:label "LV2 Context" ; - rdfs:comment """ -A potentially concurrent context (callback) on a plugin. + lv2:documentation """ +<p>A potentially concurrent context (callback) on a plugin.</p> -Ports are always associated with a context. If a port has no explicit context -property, then its context is ctx:AudioContext (the default LV2 run() context). +<p>Ports are always associated with a context. If a port has no explicit context +property, then its context is ctx:AudioContext (the default LV2 run() context).</p> -A plugin indicates support for a context by supporting an LV2 Feature with +<p>A plugin indicates support for a context by supporting an LV2 Feature with that context's URI. If a plugin optionally supports a context (e.g. <code><plugin> lv2:optionalFeature ctx:IdleContext .</code>), then all ports associated with that context MUST be lv2:connectionOptional. Thus, hosts that do not support contexts will connect such ports to NULL and the -plugin can run with only a standard LV2 run() context. +plugin can run with only a standard LV2 run() context.</p> -Any plugin that supports any context (optionally or mandatorily) MUST adhere -to the following additional threading rules for LV2_Descriptor.connect_port: +<p>Any plugin that supports any context (optionally or mandatorily) MUST adhere +to the following additional threading rules for LV2_Descriptor.connect_port:</p> <ul> <li>connect_port MUST only be called for a given port from the context associated with that port</li> @@ -100,16 +100,16 @@ associated with that port</li> contexts (but MUST NOT be called concurrently for multiple ports in the same context)</li> </ul> -Note this implies that any shared data access in connect_port may be +<p>Note this implies that any shared data access in connect_port may be accessed concurrently. The plugin is responsible for any synchronisation -or locking necessary to make this possible. +or locking necessary to make this possible.</p> """ . ctx:AudioContext a ctx:Context , lv2:Feature ; rdfs:comment """The context of LV2_Descriptor.run().""" . ctx:MessageContext a ctx:Context , lv2:Feature ; - rdfs:comment """ + lv2:documentation """ A non-realtime context for plugin control via message passing. This context has a run method which takes a bitset of flags for parameters specifying which input and output ports are valid before and after the run method has executed, diff --git a/ext/data-access.lv2/data-access.ttl b/ext/data-access.lv2/data-access.ttl index ce5c849..029854e 100644 --- a/ext/data-access.lv2/data-access.ttl +++ b/ext/data-access.lv2/data-access.ttl @@ -31,8 +31,8 @@ doap:license <http://usefulinc.com/doap/licenses/mit> ; doap:name "LV2 Data Access" ; doap:release [ - doap:revision "1" ; - doap:created "2008-08-11" ; + doap:revision "1.1pre1" ; + doap:created "2010-10-29" ] ; doap:maintainer [ a foaf:Person ; diff --git a/ext/dyn-manifest.lv2/dyn-manifest.ttl b/ext/dyn-manifest.lv2/dyn-manifest.ttl index 84e8f5a..6afb305 100644 --- a/ext/dyn-manifest.lv2/dyn-manifest.ttl +++ b/ext/dyn-manifest.lv2/dyn-manifest.ttl @@ -45,8 +45,8 @@ doap:shortdesc "An LV2-based specification for dynamic data generation." ; doap:programming-language "C" ; doap:release [ - doap:revision "1" ; - doap:created "2009-06-13" + doap:revision "1.1pre1" ; + doap:created "2010-10-29" ] ; doap:maintainer [ a foaf:Person ; diff --git a/ext/event.lv2/event.ttl b/ext/event.lv2/event.ttl index 4f939a4..7c0efba 100644 --- a/ext/event.lv2/event.ttl +++ b/ext/event.lv2/event.ttl @@ -30,10 +30,10 @@ <http://lv2plug.in/ns/ext/event> a lv2:Specification ; doap:license <http://usefulinc.com/doap/licenses/mit> ; doap:name "LV2 Events" ; - rdfs:seeAlso "event-helpers.h" ; + rdfs:seeAlso <event-helpers.h> ; doap:release [ - doap:revision "1" ; - doap:created "2008-04-04" ; + doap:revision "1.1pre1" ; + doap:created "2010-10-29" ] ; doap:maintainer [ a foaf:Person ; @@ -44,7 +44,7 @@ a foaf:Person ; foaf:name "Lars Luthman" ; ] ; - rdfs:comment """ + lv2:documentation """ This extension defines a generic time-stamped event port type, which can be used to create plugins that read and write real-time events, such as MIDI, OSC, or any other type of event payload. The type(s) of event supported by diff --git a/ext/files.lv2/files.ttl b/ext/files.lv2/files.ttl index a83889d..4f1b68b 100644 --- a/ext/files.lv2/files.ttl +++ b/ext/files.lv2/files.ttl @@ -38,51 +38,50 @@ foaf:homepage <http://drobilla.net/> ; rdfs:seeAlso <http://drobilla.net/drobilla.rdf> ] ; - rdfs:comment """ -This extension provides a mechanism for plugins to create new files for + lv2:documentation """ +<p>This extension provides a mechanism for plugins to create new files for storing arbitrary data (e.g. waveforms), which can be persisted using the <a href="http://lv2plug.in/ns/ext/persist">LV2 Persist</a> extension. This allows plugins to work with potentially very large data via files, -and save/restore these files. +and save/restore these files.</p> -The motivating idea behind this extension is that all details of file +<p>The motivating idea behind this extension is that all details of file management must be handled by the host in whatever way is most appropriate for that host. Plugins MUST NOT make any assumption about filesystem locations -beyond what is explicitly guaranteed by this extension. +beyond what is explicitly guaranteed by this extension.</p> -To create a new file, plugins request a filename from the host. This way, +<p>To create a new file, plugins request a filename from the host. This way, the host is aware of files used by the plugin and can use an appropriate location for them that the plugin alone could not know (e.g. using an -appropriate disk volume for recording). +appropriate disk volume for recording).</p> -Plugins may also use pre-existing files from elsewhere on the filesystem. +<p>Plugins may also use pre-existing files from elsewhere on the filesystem. Using the LV2 Persist extension, the host can save both these types of files in an appropriate way (by e.g. storing a link, or copying the file to export -or archive a project). - +or archive a project).</p> """ . files:fileSupport a lv2:Feature ; rdfs:label "Support for plugin-created files" ; - rdfs:comment """ -This feature allows plugins to use pre-existing or newly created files, + lv2:documentation """ +<p>This feature allows plugins to use pre-existing or newly created files, and files them (e.g. across project saves and restores). If a host supports this feature it passes a LV2_Files_FileSupport structure to the plugins instantiate method as a feature (with URI http://lv2plug.in/ns/ext/files#FileSupport). This structure provides a function the plugin can use to create new file names. If and only if the host supports this feature, the plugin MAY files and restore values of -type LV2_FILES_FILENAME. +type LV2_FILES_FILENAME.</p> -A plugin SHOULD use this facility to create any new files it may need +<p>A plugin SHOULD use this facility to create any new files it may need (e.g. samples, waveforms for recording). Plugins MUST NOT expect their state to be correctly restored if they do not use this mechanism to -create new files. +create new files.</p> """ . files:FilePath a atom:AtomType ; rdfs:label "File Path" ; - rdfs:comment """ + lv2:documentation """ The full path to a file on the local filesystem. The format of a files:filePath is a C string (escaped or otherwise restricted in whatever way necessary for the system). This URI (http://lv2plug.in/ns/ext/files#FilePath), diff --git a/ext/host-info.lv2/host-info.ttl b/ext/host-info.lv2/host-info.ttl index 2aac2fc..8289f02 100644 --- a/ext/host-info.lv2/host-info.ttl +++ b/ext/host-info.lv2/host-info.ttl @@ -39,12 +39,12 @@ foaf:homepage <http://drobilla.net/> ; rdfs:seeAlso <http://drobilla.net/drobilla.rdf> ] ; - rdfs:comment """ -This specification defines various properties to represent useful information + lv2:documentation """ +<p>This specification defines various properties to represent useful information about LV2 hosts. Currently, the primary use of this specification is to describe which -extensions are supported by a given host. +extensions are supported by a given host.</p> -The extensions supported by a host can be described like this: +<p>The extensions supported by a host can be described like this:</p> <pre> @prefix hi: <http://lv2plug.in/ns/ext/host-info#> . @@ -55,7 +55,7 @@ The extensions supported by a host can be described like this: hi:sinceVersion "1.2.0" ] . </pre> -"""^^lv2:basicXHTML . +""" . ## Core Classes / Properties diff --git a/ext/instance-access.lv2/instance-access.ttl b/ext/instance-access.lv2/instance-access.ttl index 0646478..465a676 100644 --- a/ext/instance-access.lv2/instance-access.ttl +++ b/ext/instance-access.lv2/instance-access.ttl @@ -31,8 +31,8 @@ doap:license <http://usefulinc.com/doap/licenses/mit> ; doap:name "LV2 Instance Access" ; doap:release [ - doap:revision "1" ; - doap:created "2008-08-11" ; + doap:revision "1.1pre1" ; + doap:created "2010-10-29" ] ; doap:maintainer [ a foaf:Person ; diff --git a/ext/message.lv2/message.ttl b/ext/message.lv2/message.ttl index ae7d438..b47ae56 100644 --- a/ext/message.lv2/message.ttl +++ b/ext/message.lv2/message.ttl @@ -37,65 +37,65 @@ foaf:homepage <http://drobilla.net/> ; rdfs:seeAlso <http://drobilla.net/drobilla.rdf> ] ; - rdfs:comment """ -This extension defines a standard for LV2 "messages" which allow dynamic + lv2:documentation """ +<p>This extension defines a standard for LV2 "messages" which allow dynamic control and investigation of plugin instances, by both hosts and other -plugins. +plugins.</p> -This extension requires the host to support the <a +<p>This extension requires the host to support the <a href="http://lv2plug.in/ns/ext/uri-map">LV2 URI Map</a> extension, and the -<a href="http://lv2plug.in/ns/ext/atom">LV2 Atom</a> extension. +<a href="http://lv2plug.in/ns/ext/atom">LV2 Atom</a> extension.</p> """ . msg:MessageType a rdfs:Class ; rdfs:label "LV2 Message Type" ; - rdfs:comment """ -Base class for all types of LV2 Message. + lv2:documentation """ +<p>Base class for all types of LV2 Message.</p> -A type of message, which must be a resource (i.e. have a URI). This URI +<p>A type of message, which must be a resource (i.e. have a URI). This URI is used as the selector component of a Message and is used by receivers to -interpret the meaning of messages (e.g. which components are present). +interpret the meaning of messages (e.g. which components are present).</p> -A message in memory is simply an <a href="http://lv2plug.in/ns/ext/atom#Dict" +<p>A message in memory is simply an <a href="http://lv2plug.in/ns/ext/atom#Dict" >atom:Dict</a> with at least one rdf:type that is a rdfs:subClassOf msg:MessageType. The definitions of various message types define what -other key/value pairs can be expected in the message. +other key/value pairs can be expected in the message.</p> """ . msg:ControlPort a rdfs:Class ; rdfs:label "Control Port" ; rdfs:subClassOf lv2:Port ; - rdfs:comment """ -An input port used to control a plugin instance. A plugin has + lv2:documentation """ +<p>An input port used to control a plugin instance. A plugin has at most 1 msg:ControlPort. A ControlPort is always an lv2:InputPort. Hosts can send messages to the control port in order to investigate or manipulate -a plugin instance (possibly on behalf of a UI or another plugin instance). +a plugin instance (possibly on behalf of a UI or another plugin instance).</p> -This is an abstract port class, the actual format and semantics +<p>This is an abstract port class, the actual format and semantics of the port buffer (and messages) are defined by some other port type, i.e. a cmdControlPort MUST have another type which defines the format and semantics of the port buffer contents (likely candidates are <a href="http://lv2plug.in/ns/ext/atom#MessagePort">atom:MessagePort</a> -or <a href="http://lv2plug.in/ns/ext/event#EventPort">ev:EventPort</a>). +or <a href="http://lv2plug.in/ns/ext/event#EventPort">ev:EventPort</a>).</p> """ . msg:ResponsePort a rdfs:Class ; rdfs:label "Response Port" ; rdfs:subClassOf lv2:Port ; - rdfs:comment """ -An output port used to notify the host about changes to a plugin instance + lv2:documentation """ +<p>An output port used to notify the host about changes to a plugin instance or respond to messages send to its msg:ControlPort. A plugin has at most 1 StatusPort. A StatusPort is always an lv2:OutputPort. Any response to a command sent to the CommandPort of the plugin will appear in the StatusPort output. The plugin may also emit other messages (i.e. the contents of a -StatusPort are not necessarily responses to commands). +StatusPort are not necessarily responses to commands).</p> -This is an abstract port class, the actual format and semantics +<p>This is an abstract port class, the actual format and semantics of the port buffer (and messages) are defined by some other port type, i.e. a cmdControlPort MUST have another type which defines the format and semantics of the port buffer contents (likely candidates are <a href="http://lv2plug.in/ns/ext/atom#MessagePort">atom:MessagePort</a> -or <a href="http://lv2plug.in/ns/ext/event#EventPort">ev:EventPort</a>). +or <a href="http://lv2plug.in/ns/ext/event#EventPort">ev:EventPort</a>).</p> """ . diff --git a/ext/midi.lv2/midi.ttl b/ext/midi.lv2/midi.ttl index 12725ad..a8c7c6a 100644 --- a/ext/midi.lv2/midi.ttl +++ b/ext/midi.lv2/midi.ttl @@ -34,8 +34,8 @@ doap:name "LV2 MIDI Events" ; rdfs:comment "Defines an LV2 event type for standard raw MIDI" ; doap:release [ - doap:revision "1" ; - doap:created "2008-08-11" ; + doap:revision "1.1pre1" ; + doap:created "2010-10-29" ] ; doap:maintainer [ a foaf:Person ; @@ -51,11 +51,11 @@ midi:MidiEvent a rdfs:Class ; rdfs:label "LV2 MIDI event" ; rdfs:subClassOf lv2ev:Event ; - rdfs:comment """ -A single raw (sequence of bytes) MIDI event. + lv2:documentation """ +<p>A single raw (sequence of bytes) MIDI event.</p> -These events are equivalent to standard MIDI events, with the following -restrictions to ease the burden on plugin authors: +<p>These events are equivalent to standard MIDI events, with the following +restrictions to ease the burden on plugin authors:</p> <ul> <li>Running status is not allowed. Every event must have its own status byte.</li> @@ -83,5 +83,5 @@ restrictions to ease the burden on plugin authors: events to the buffer, and the MIDI reader (plugin or host) can assume that all events are valid.</li> </ul> -"""^^lv2:basicXHTML . +""" . diff --git a/ext/parameter.lv2/parameter.ttl b/ext/parameter.lv2/parameter.ttl index 5970844..d1517c9 100644 --- a/ext/parameter.lv2/parameter.ttl +++ b/ext/parameter.lv2/parameter.ttl @@ -43,22 +43,22 @@ param:Parameter a rdfs:Class ; a lv2:Resource ; rdfs:label "Parameter" ; - rdfs:comment """ -A parameter on an LV2 plugin. Parameters can be manipulated to alter the -behaviour or output of a plugin. Unlike lv2:ControlPort: + lv2:documentation """ +<p>A parameter on an LV2 plugin. Parameters can be manipulated to alter +the behaviour or output of a plugin. Unlike lv2:ControlPort:</p> <ul> <li>A parameter may have any data type</li> <li>Parameters can be dynamically added or removed</li> <li>Parameter values can be manipulated by the plugin</li> </ul> -Note that plugins are not required to support this potential functionality, +<p>Note that plugins are not required to support this potential functionality, parameters can be used to provide a basic LADSPA-like set of floating point -parameters in a more extensible manner. +parameters in a more extensible manner.</p> -Parameters are essentially controls that are not 1:1 associated with ports +<p>Parameters are essentially controls that are not 1:1 associated with ports (manipulation of parameters can be accomplished by e.g. sending messages -to a command port). +to a command port).</p> """ . @@ -66,11 +66,11 @@ param:supportsType a rdf:Property ; rdfs:domain param:Parameter ; rdfs:range atom:AtomType ; rdfs:label "supports type" ; - rdfs:comment """ + lv2:documentation """ Indicates that a Parameter has values of a particular type. A Parameter may support many types. Parameter values are always LV2 Atoms as defined -by the LV2 Atom Extension <http://lv2plug.in/ns/ext/atom#>. Any type -of LV2 Atom may be used as a parameter value. +by the <a href="http://lv2plug.in/ns/ext/atom">LV2 Atom</a> Extension +Any type of LV2 Atom may be used as a parameter value. """ . diff --git a/ext/persist.lv2/persist.ttl b/ext/persist.lv2/persist.ttl index 490e2c1..7ec0e0e 100644 --- a/ext/persist.lv2/persist.ttl +++ b/ext/persist.lv2/persist.ttl @@ -42,49 +42,49 @@ foaf:homepage <http://drobilla.net/> ; rdfs:seeAlso <http://drobilla.net/drobilla.rdf> ] ; - rdfs:comment """ -This extension provides a mechanism for plugins to save and restore state + lv2:documentation """ +<p>This extension provides a mechanism for plugins to save and restore state across instances, allowing hosts to save configuration/state/data with a -project or fully clone a plugin instance (including internal state). +project or fully clone a plugin instance (including internal state).</p> -Unlike ports, this extension allows plugins to save private state data. +<p>Unlike ports, this extension allows plugins to save private state data. The motivating ideal behind this extension is for the state of a plugin instance to be entirely described by port values (as with all LV2 plugins) and a key/value dictionary as defined by this extension. This mechanism is simple, -yet sufficiently powerful to describe the state of very advanced plugins. +yet sufficiently powerful to describe the state of very advanced plugins.</p> -The "state" described by this extension is conceptually a single key/value +<p>The "state" described by this extension is conceptually a single key/value dictionary. Keys are URIs, and values are typed-tagged blobs of any type. The plugin provides a save and restore method for saving and restoring state. To initiate a save or restore, the host calls these methods, passing a callback -to be used for saving or restoring a single key/value pair. In this way, the -actual mechanism of saving and restoring state is completely abstract from the -plugin's perspective. - -Because the state is a simple dictionary, hosts and plugins can work with state -easily (virtually all programming languages have an appropriate dictionary -type available). Additionally, this format is simple and terse to serialise -in many formats (e.g. any RDF syntax, JSON, XML, key/value databases such as -BDB, etc.). In particular, state can be elegantly described in a plugin's -Turtle description, which is useful for presets (among other things). +to be used for saving or restoring a single key/value pair. In this way, +the actual mechanism of saving and restoring state is completely abstract +from the plugin's perspective.</p> + +<p>Because the state is a simple dictionary, hosts and plugins can work +with state easily (virtually all programming languages have an appropriate +dictionary type available). Additionally, this format is simple and terse to +serialise in many formats (e.g. any RDF syntax, JSON, XML, key/value databases +such as BDB, etc.). In particular, state can be elegantly described in a +plugin's Turtle description, which is useful for presets (among other things). Note that these are all simply possibilities enabled by this simple data model. This extension defines only a few function prototypes and does not impose any requirement to use a particular syntax, data structure, library, or other implementation detail. Hosts are free to work with plugin state -in whatever way is most appropriate for that host. - -This extension makes it possible for plugins to save private data, but state is -not necessarily private, e.g. a plugin could have a public interface via ports -for manipulating internal state, which would be saved using this extension. -Plugins are strongly encouraged to represent all state change as modifications -of such key/value variables, to minimize implementation burden and enable -the many benefits of having a universal model for describing plugin state. -The use of URI keys prevents conflict and allows unrelated plugins to -meaningfully describe state changes. Future extensions will describe a -dynamic mechanism for manipulating plugin state, as well as define various -keys likely to be useful to a wide range of plugins. - -In pseudo code, a typical use case in a plugin is: +in whatever way is most appropriate for that host.</p> + +<p>This extension makes it possible for plugins to save private data, but +state is not necessarily private, e.g. a plugin could have a public interface +via ports for manipulating internal state, which would be saved using this +extension. Plugins are strongly encouraged to represent all state change as +modifications of such key/value variables, to minimize implementation burden +and enable the many benefits of having a universal model for describing +plugin state. The use of URI keys prevents conflict and allows unrelated +plugins to meaningfully describe state changes. Future extensions will +describe a dynamic mechanism for manipulating plugin state, as well as define +various keys likely to be useful to a wide range of plugins.</p> + +<p>In pseudo code, a typical use case in a plugin is:</p> <pre> static const char* const KEY_GREETING = "http://example.org/greeting"; @@ -108,7 +108,7 @@ void my_restore(LV2_Handle instance, size_t size; uint32_t type; - const char* greeting = retrieve(callback_data, KEY_GREETING, &size, &type); + const char* greeting = retrieve(callback_data, KEY_GREETING, &size, &type); if (greeting) plugin->state->greeting = greeting; @@ -118,7 +118,7 @@ void my_restore(LV2_Handle instance, } </pre> -Similarly, a typical use case in a host is: +<p>Similarly, a typical use case in a host is:</p> <pre> void store_callback(void* callback_data, const char* key, @@ -134,7 +134,7 @@ Map get_plugin_state(LV2_Handle instance) { LV2_Persist* persist = instance.extension_data("http://lv2plug.in/ns/ext/persist"); Map state_map; - persist.save(instance, store_callback, &state_map); + persist.save(instance, store_callback, &state_map); return state_map; } </pre> @@ -158,7 +158,7 @@ but its use is not required to support the LV2 Persist extension. persist:instanceState a rdf:Property ; rdfs:range persist:InstanceState ; - rdfs:comment """ + lv2:documentation """ Predicate to relate a plugin instance to an InstanceState. This may be used wherever the state of a particular plugin instance needs to be represented. Note that the domain of this property is unspecified, since LV2 does not diff --git a/ext/presets.lv2/presets.ttl b/ext/presets.lv2/presets.ttl index 804e187..21114e8 100644 --- a/ext/presets.lv2/presets.ttl +++ b/ext/presets.lv2/presets.ttl @@ -33,8 +33,8 @@ doap:license <http://usefulinc.com/doap/licenses/mit> ; doap:name "LV2 Presets" ; doap:release [ - doap:revision "2" ; - doap:created "2010-03-02" + doap:revision "2.1pre1" ; + doap:created "2010-10-29" ] ; doap:maintainer [ a foaf:Person ; diff --git a/ext/resize-port.lv2/resize-port.ttl b/ext/resize-port.lv2/resize-port.ttl index 7709c0a..9ddd3cb 100644 --- a/ext/resize-port.lv2/resize-port.ttl +++ b/ext/resize-port.lv2/resize-port.ttl @@ -35,18 +35,18 @@ a lv2:Specification ; a lv2:Feature ; doap:name "LV2 Resize Port Extension" ; - rdfs:comment """ -An extension that allows LV2 plugins to request a resize of an output port. + lv2:documentation """ +<p>An extension that allows LV2 plugins to request a resize of an output port.</p> -Any host which supports this extension must pass an LV2_Feature to +<p>Any host which supports this extension must pass an LV2_Feature to the plugin's instantiate method with URI http://lv2plug.in/ns/ext/resize-port and a pointer to a LV2_Resize_Port_Feature structure (see <a href="resize-port.h">resize-port.h</a> for details). This structure provides a resize_port function which plugins may use to resize output -port buffers as necessary. +port buffers as necessary.</p> -This extension also defines several predicates useful for describing the -amount of space required for a particular port buffer. +<p>This extension also defines several predicates useful for describing the +amount of space required for a particular port buffer.</p> """ . rsz:asLargeAs a rdf:Property ; diff --git a/ext/string-port.lv2/string-port.ttl b/ext/string-port.lv2/string-port.ttl index e6adfc2..8ee6373 100644 --- a/ext/string-port.lv2/string-port.ttl +++ b/ext/string-port.lv2/string-port.ttl @@ -35,7 +35,7 @@ a foaf:Person ; foaf:name "Krzysztof Foltman" ; ] ; - rdfs:comment """ + lv2:documentation """ Defines ports which contain string data. <h4>UI issues</h4> @@ -65,7 +65,7 @@ sp:StringTransfer a lv2:Feature ; sp:StringPort a lv2:Port ; rdfs:label "String port" ; - rdfs:comment """ + lv2:documentation """ Indicates that the port data points to a LV2_String_Data structure as defined in accompanying header file. diff --git a/ext/uri-map.lv2/uri-map.ttl b/ext/uri-map.lv2/uri-map.ttl index e6459c3..54db29d 100644 --- a/ext/uri-map.lv2/uri-map.ttl +++ b/ext/uri-map.lv2/uri-map.ttl @@ -31,8 +31,8 @@ doap:license <http://usefulinc.com/doap/licenses/mit> ; doap:name "LV2 URI Map" ; doap:release [ - doap:revision "1" ; - doap:created "2008-04-16" + doap:revision "1.1pre1" ; + doap:created "2010-10-29" ] ; doap:maintainer [ a foaf:Person ; diff --git a/ext/uri-unmap.lv2/uri-unmap.ttl b/ext/uri-unmap.lv2/uri-unmap.ttl index bf68446..6efab1f 100644 --- a/ext/uri-unmap.lv2/uri-unmap.ttl +++ b/ext/uri-unmap.lv2/uri-unmap.ttl @@ -30,17 +30,13 @@ <http://lv2plug.in/ns/ext/uri-unmap> a lv2:Specification , lv2:Feature ; doap:license <http://usefulinc.com/doap/licenses/mit> ; doap:name "LV2 URI Unmap" ; - doap:release [ - doap:revision "0" ; - doap:created "2010-10-19" - ] ; doap:maintainer [ a foaf:Person ; foaf:name "David Robillard" ; foaf:homepage <http://drobilla.net/> ; rdfs:seeAlso <http://drobilla.net/drobilla.xrdf> ] ; - rdfs:comment """ + lv2:documentation """ This extension is the opposite of the <a href="http://lv2plug.in/ns/ext/uri-map" >LV2 URI Map</a> extension. It allows the host to pass an id_to_uri function to the plugin which can be used for unmapping an integer (previously mapped using |