diff options
Diffstat (limited to 'lv2/lv2plug.in/ns/ext/atom/atom.ttl')
| -rw-r--r-- | lv2/lv2plug.in/ns/ext/atom/atom.ttl | 462 |
1 files changed, 462 insertions, 0 deletions
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl new file mode 100644 index 0000000..7d534d0 --- /dev/null +++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl @@ -0,0 +1,462 @@ +# LV2 Atom Extension +# Copyright 2007-2012 David Robillard <d@drobilla.net> +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +@prefix atom: <http://lv2plug.in/ns/ext/atom#> . +@prefix doap: <http://usefulinc.com/ns/doap#> . +@prefix foaf: <http://xmlns.com/foaf/0.1/> . +@prefix lv2: <http://lv2plug.in/ns/lv2core#> . +@prefix owl: <http://www.w3.org/2002/07/owl#> . +@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . +@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . +@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . + +<http://lv2plug.in/ns/ext/atom> + a lv2:Specification ; + doap:name "LV2 Atom" ; + doap:shortdesc "A generic value container and several data types." ; + doap:license <http://opensource.org/licenses/isc> ; + rdfs:seeAlso <atom-helpers.h> , + <forge.h> ; + doap:release [ + doap:revision "0.4" ; + doap:created "2012-02-07" + ] ; + doap:maintainer [ + a foaf:Person ; + foaf:name "David Robillard" ; + foaf:homepage <http://drobilla.net/> ; + rdfs:seeAlso <http://drobilla.net/drobilla.rdf> + ] ; + lv2:documentation """ +<p>This extension defines a generic container for data, called an <q>Atom</q>, +and several basic Atom types which can be used to express structured data. +Atoms allow LV2 plugins and hosts to communicate, process, serialise, and store +values of any type via a generic mechanism (e.g. ports, files, networks, +ringbuffers, etc.). Atoms are, with one exception, Plain Old Data (POD) which +may safely be copied (e.g. with a simple call to <code>memcpy</code>).</p> + +<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.</p> + +<p>Atoms can and should be used anywhere values of various types must be stored +or transmitted. This extension defines port types, atom:ValuePort and +atom:MessagePort, which are connected to an Atom. The atom:Sequence type in +conjunction with atom:MessagePort is intended to replace the <a +href="http://lv2plug.in/ns/ext/event">LV2 event</a> extension.</p> + +<p>The types defined in this extension should be powerful enough to express +almost any structure. Implementers SHOULD build structures out of the types +provided here, rather than define new binary formats (e.g. use atom:Object +rather than a new C <code>struct</code> type). New binary formats are an +implementation burden which harms interoperabilty, and should only be defined +where absolutely necessary.</p> + +<p>Implementing this extension requires a facility for mapping URIs to +integers, such as the <a href="http://lv2plug.in/ns/ext/urid">LV2 URID</a> +extension.</p> +""" . + +atom:cType + a rdf:Property , + owl:DatatypeProperty ; + rdfs:label "C type" ; + rdfs:domain rdfs:Class ; + rdfs:range xsd:string ; + rdfs:comment """ +The identifier for a C type describing the in-memory representation of +an instance of this class. +""" . + +atom:Atom + a rdfs:Class ; + rdfs:label "Atom" ; + atom:cType "LV2_Atom" ; + lv2:documentation """ +<p>Abstract base class for all atoms. An LV2_Atom has a 32-bit +<code>type</code> and <code>size</code> followed by a body of <code>size</code> +bytes. Atoms MUST be 64-bit aligned.</p> + +<p>All concrete Atom types (subclasses of this class) MUST define a precise +binary layout for their body.</p> + +<p>The <code>type</code> field is the URI of an Atom type mapped to an integer. +Implementations SHOULD gracefully ignore, or pass through, atoms with unknown +types.</p> + +<p>All atoms are POD by definition except references, which as a special case +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>. Though this extension +reserves the type 0 for references, the details of reference handling are +currently unspecified. A future revision of this extension, or a different +extension, may define how to use non-POD data and references. Implementations +MUST NOT send references to another implementation unless the receiver is +explicitly known to support references (e.g. by supporting a feature). The +atom with both <code>type</code> <em>and</em> <code>size</code> 0 is +<q>null</q>, which is not considered a Reference.</p> +""" . + +atom:Bang + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Bang" ; + rdfs:comment "Generic activity or trigger, with no body." . + +atom:Number + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Number" . + +atom:Int32 + a rdfs:Class ; + rdfs:subClassOf atom:Number ; + rdfs:label "Signed 32-bit integer" ; + atom:cType "LV2_Atom_Int32" . + +atom:Int64 + a rdfs:Class ; + rdfs:subClassOf atom:Number ; + rdfs:label "Signed 64-bit integer" ; + atom:cType "LV2_Atom_Int64" . + +atom:Float + a rdfs:Class ; + rdfs:subClassOf atom:Number ; + rdfs:label "32-bit IEEE-754 floating point number" ; + atom:cType "LV2_Atom_Float" . + +atom:Double + a rdfs:Class ; + rdfs:subClassOf atom:Number ; + rdfs:label "64-bit IEEE-754 floating point number" ; + atom:cType "LV2_Atom_Double" . + +atom:Bool + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Boolean" ; + atom:cType "LV2_Atom_Bool" ; + rdfs:comment "An Int32 where 0 is false and any other value is true." . + +atom:String + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "String" ; + atom:cType "LV2_Atom_String" ; + lv2:documentation """ +<p>A UTF-8 encoded string.</p> + +<p>The body of an LV2_Atom_String is a C string in UTF-8 encoding, i.e. an +array of bytes (<code>uint8_t</code>) terminated with a NULL byte +(<code>'\\0'</code>).</p> + +<p>This type can be used for free-form strings, but in most cases it is better to +use atom:Literal since this supports a language tag or datatype. Implementations +SHOULD NOT use atom:String unless translating the string does not make sense and +the string has no meaningful datatype.</p> +""" . + +atom:Literal + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "String Literal" ; + atom:cType "LV2_Atom_Literal" ; + lv2:documentation """ +<p>A UTF-8 encoded string literal, with an optional datatype or language.</p> + +<p>This type is compatible with rdf:Literal and is capable of expressing a +string in any language or a value of any type. A Literal has a +<code>datatype</code> and <code>lang</code> followed by string data in UTF-8 +encoding. The length of the string data in bytes is <code>size - +sizeof(LV2_Atom_Literal)</code>, including the terminating NULL character. The +<code>lang</code> field SHOULD be a URI of the form +<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.</p> + +<p>A Literal may have a <code>datatype</code> OR a <code>lang</code>, but never +both.</p> + +<p>For example, a Literal can be "Hello" in English:</p> +<pre class="c-code"> +void set_to_hello_in_english(LV2_Atom_Literal* lit) { + lit->atom.type = map(expand("atom:Literal")); + lit->atom.size = 14; + lit->datatype = 0; + lit->lang = map("http://lexvo.org/id/term/en"); + memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit), + "Hello", + sizeof("Hello")); // Assumes enough space +} +</pre> + +<p>or a Turtle string:</p> +<pre class="c-code"> +void set_to_turtle_string(LV2_Atom_Literal* lit, const char* ttl) { + lit->atom.type = map(expand("atom:Literal")); + lit->atom.size = 64; + lit->datatype = map("http://www.w3.org/2008/turtle#turtle"); + lit->lang = 0; + memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit), + ttl, + strlen(ttl) + 1); // Assumes enough space +} +</pre> +""" . + +atom:URID + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Integer ID mapped from a URI" ; + atom:cType "LV2_Atom_ID" ; + lv2:documentation """ +<p>An unsigned 32-bit integer mapped from a URI (e.g. with LV2_URID_Map).</p> +""" . + +atom:Vector + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Vector" ; + atom:cType "LV2_Atom_Vector" ; + lv2:documentation """ +<p>A homogeneous series of atom bodies with equivalent type and size.</p> + +<p>An LV2_Atom_Vector is a 32-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 atom:Atom type, +i.e. the size of each element is the vector's <code>size / +elem_count</code>.</p> + +<p>For example, an atom:Vector containing 42 elements of type atom:Float:</p> +<pre class="c-code"> +struct VectorOf42Floats { + uint32_t type; // map(expand("atom:Vector")) + uint32_t size; // sizeof(LV2_Atom_Vector) + (42 * sizeof(float); + uint32_t elem_count; // 42 + uint32_t elem_type; // map(expand("atom:Float")) + float elems[32]; +}; +</pre> + +<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>.</p> +""" . + +atom:Tuple + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Tuple" ; + lv2:documentation """ +<p>A series of Atoms with varying <code>type</code> and <code>size</code>.</p> + +<p>The body of a Tuple is simply a series of complete atoms, each aligned to +64 bits.</p> +""" . + +atom:Property + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Property" ; + atom:cType "LV2_Atom_Property" ; + lv2:documentation """ +<p>A property of an atom:Object. An LV2_Atom_Property has a URID +<code>key</code> and <code>context</code>, and an Atom <code>value</code>. +This corresponds to an RDF Property, where the <q>key</q> is the <q>predicate</q> +and the <q>value</q> is the object.</p> + +<p>The <code>context</code> field can be used to specify a different context +for each property, where this is useful. Otherwise, it may be 0.</p> +""" . + +atom:Object + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Object" ; + atom:cType "LV2_Atom_Object" ; + lv2:documentation """ +<p>An <q>Object</q> is an atom with a set of properties. This corresponds to +an RDF Resource, and can be thought of as a dictionary with URID keys.</p> + +<p>An LV2_Atom_Object has a uint32_t <code>id</code> and uint32_t +<code>type</code>, followed by a series of atom:Property bodies (without +headers, i.e. LV2_Atom_Property_Body). The LV2_Atom_Object::type field is +semantically equivalent to a property with key rdf:type, but is included in the +structure to allow for fast dispatch.</p> + +<p>This is an abstract Atom type, an Object is always either a atom:Resource +or a atom:Blank.</p> +""" . + +atom:Resource + a rdfs:Class ; + rdfs:subClassOf atom:Object ; + rdfs:label "Resource" ; + atom:cType "LV2_Atom_Object" ; + lv2:documentation """ +<p>An atom:Object where the <code>id</code> field is a URID, i.e. an Object +with a URI.</p> +""" . + +atom:Blank + a rdfs:Class ; + rdfs:subClassOf atom:Object ; + rdfs:label "Blank" ; + atom:cType "LV2_Atom_Object" ; + lv2:documentation """ +<p>An atom:Object where the LV2_Atom_Object::id is a blank node ID (NOT a URI). +The ID of a Blank is valid only within the context the Blank appears in. For +ports this is the context of the associated run() call, i.e. all ports share +the same context so outputs can contain IDs that correspond to IDs of blanks in +the input.</p> """ . + +atom:Event + a rdfs:Class ; + rdfs:label "Event" ; + atom:cType "LV2_Atom_Event" ; + lv2:documentation """ +<p>An atom with a time stamp header prepended, typically an element of an +atom:Sequence. Note this is not an Atom type.</p> +""" . + +atom:Sequence + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Sequence" ; + atom:cType "LV2_Atom_Sequence" ; + lv2:documentation """ +<p>A sequence of atom:Event, i.e. a series of time-stamped Atoms.</p> +""" . + +atom:AtomPort + a rdfs:Class ; + rdfs:subClassOf lv2:Port ; + rdfs:label "Atom Port" ; + lv2:documentation """ +<p>A port which contains an lv2:Atom. Ports of this type will be connected to +a 64-bit aligned LV2_Atom immediately followed by <code>size</code> bytes of +data.</p> + +<p>This is an abstract port type with incomplete semantics which can not be +used directly as a port type. Atom ports should be either a atom:ValuePort or +a atom:MessagePort.</p> + +<p>Before calling a method on a 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</code> and <code>size</code> 0).</p> +""" . + +atom:ValuePort + a rdfs:Class ; + rdfs:subClassOf atom:AtomPort ; + rdfs:label "Value Port" ; + lv2:documentation """ + +<p>An AtomPort that contains a persistent <em>value</em>. A <q>value</q> is +time-independent and may be used numerous times. A ValuePort is <q>pure</q> in +the sense that it may affect output but MUST NOT affect persistent plugin state +in any externally visible way.</p> + +<ul> +<li>If a plugin has fixed values for all inputs, all ValuePort outputs are also +fixed regardless of the number of times the plugin is run.</li> + +<li>If a plugin has fixed input values for all ports except a ValuePort, each +value of that port corresponds to a single set of values for all +ValuePort outputs.</li> + +<li>If the plugin saves state other than port values (e.g. using the <a +href="http://lv2plug.in/ns/ext/state">LV2 State</a> extension), changing only +the value of a ValuePort input MUST NOT change that state. In other words, +value port changes MUST NOT trigger a state change that requires a save.</li> +</ul> + +<p>Value ports are essentially purely functional ports: if a plugin has only +value ports, that plugin is purely functional. Hosts may elect to cache output +and avoid calling run() if the output is already known according to these +rules.</p> +""" . + +atom:MessagePort + a rdfs:Class ; + rdfs:subClassOf atom:AtomPort ; + rdfs:label "Message Port" ; + lv2:documentation """ +<p>An AtomPort that contains transient data which is <em>consumed</em> or +<em>sent</em>. The Atom contained in a MessagePort is time-dependent and only +valid for a single run invocation. Unlike a ValuePort, a MessagePort may be +used to manipulate internal plugin state.</p> + +<p>Intuitively, a MessagePort contains a <q>message</q> or <q>event</q> which +is reacted to <em>once</em> (not a <q>value</q> which is computed with any +number of times).</p> +""" . + +atom:bufferType + a rdf:Property ; + rdfs:domain atom:AtomPort ; + rdfs:label "buffer type" ; + lv2:documentation """ +<p>Indicates that an AtomPort may be connected to a certain Atom type. A port +MAY support several buffer types. The host MUST NOT connect a port to an Atom +with a type not explicitly listed with this property. The value of this +property MUST be a sub-class of atom:Atom. For example, an input port that is +connected directly to an LV2_Atom_Double value is described like so:</p> + +<pre class="turtle-code"> +<plugin> + lv2:port [ + a lv2:InputPort , atom:ValuePort ; + atom:bufferType atom:Double ; + ] . +</pre> + +<p>Note this property only indicates the atom types a port may be directly +connected to, it is not <q>recursive</q>. If a port can be connected to a +collection, use atom:supports to indicate which element types are understood. +If a port supports heterogeneous collections (collections that can contain +several types of elements at once), implementations MUST gracefully handle any +types that are present in the collection, even if those types are not +explicitly supported.</p> +""" . + +atom:supports + a rdf:Property ; + rdfs:label "supports" ; + lv2:documentation """ +<p>Indicates that a particular Atom type is supported.</p> + +<p>This property is defined loosely, it may be used to indicate that anything +<q>supports</q> an Atom type, wherever that may be useful. It applies +<q>recursively</q> where collections are involved.</p> + +<p>In particular, this property can be used to describe which event types are +supported by a port. For example, a port that receives MIDI events is +described like so:</p> + +<pre class="turtle-code"> +<plugin> + lv2:port [ + a lv2:InputPort , atom:MessagePort ; + atom:bufferType atom:Sequence ; + atom:supports midi:MidiEvent ; + ] . +</pre> +""" . |