aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/ext/atom/atom.ttl
diff options
context:
space:
mode:
Diffstat (limited to 'lv2/lv2plug.in/ns/ext/atom/atom.ttl')
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/atom.ttl462
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
+&lt;http://lexvo.org/id/term/LANG&gt; 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">
+&lt;plugin&gt;
+ 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">
+&lt;plugin&gt;
+ lv2:port [
+ a lv2:InputPort , atom:MessagePort ;
+ atom:bufferType atom:Sequence ;
+ atom:supports midi:MidiEvent ;
+ ] .
+</pre>
+""" .