aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/ns/ext/atom/atom.ttl
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2011-11-21 01:36:00 +0000
committerDavid Robillard <d@drobilla.net>2011-11-21 01:36:00 +0000
commiteb43c8896480114b224755e824fae2e2f7485256 (patch)
tree26e91bd8dc6421d2296a33991e90f7dcb546b079 /lv2/ns/ext/atom/atom.ttl
parentdf79255ccef7fb5d091e9d4e52f3c46545b53282 (diff)
downloadlv2-eb43c8896480114b224755e824fae2e2f7485256.tar.xz
Move ns to lv2/ns so repository top level can be used as an include dir directly.
Diffstat (limited to 'lv2/ns/ext/atom/atom.ttl')
-rw-r--r--lv2/ns/ext/atom/atom.ttl435
1 files changed, 435 insertions, 0 deletions
diff --git a/lv2/ns/ext/atom/atom.ttl b/lv2/ns/ext/atom/atom.ttl
new file mode 100644
index 0000000..1b2e265
--- /dev/null
+++ b/lv2/ns/ext/atom/atom.ttl
@@ -0,0 +1,435 @@
+# LV2 Atom Extension
+# Copyright 2007-2011 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 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#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+
+<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-license> ;
+ rdfs:seeAlso <atom-buffer.h> ;
+ doap:release [
+ doap:revision "0.2" ;
+ doap:created "2011-11-05"
+ ] ;
+ 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 format for a typed piece of data, called an
+lv2:Atom (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>).</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>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.</p>
+
+<p>Atoms (the start of the LV2_Atom header) MUST be 32-bit aligned.</p>
+
+<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: atom:ValuePort and atom:MessagePort, which both have the same
+buffer format but different semantics (with respect to how the run() callback
+interprets the Atom).</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: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 <code>body</code> of
+<code>size</code> bytes.</p>
+
+<p>All concrete Atom types (subclasses of this class) MUST define a precise
+binary layout for <code>body</code>.</p>
+
+<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 LV2_URI_Map_Feature::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
+(or copied if it does not have type 0).</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, actual specification of how references are used is left
+to another extension.</p>
+""" .
+
+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>For compatibility, a Literal MUST have either 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->type = map(expand("atom:Literal"));
+ lit->size = 14;
+ lit->datatype = 0;
+ lit->lang = map("http://lexvo.org/id/term/en");
+ memcpy(lit->str, "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->type = map(expand("atom:Literal"));
+ lit->size = 64;
+ lit->datatype = map("http://www.w3.org/2008/turtle#turtle");
+ lit->lang = 0;
+ memcpy(lit->str, 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 using the <a
+href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's
+LV2_URI_Map_Feature::uri_to_id() with <code>map = NULL</code>.</p>
+""" .
+
+atom:BlankID
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Atom ;
+ rdfs:label "Integer ID for a blank node" ;
+ atom:cType "LV2_Atom_ID" ;
+ lv2:documentation """
+<p>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 a
+URID, and can not be mapped to/from a URI.</p>
+""" .
+
+atom:Vector
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Atom ;
+ rdfs:label "Vector" ;
+ atom:cType "LV2_Atom_Vector" ;
+ lv2:documentation """
+<p>A homogeneous sequence of atoms 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 sequence of lv2:Atom with varying <code>type</code>
+and <code>size</code>.</p>
+
+<p>The body of a Tuple is simply a sequence of complete atoms, each aligned to
+32 bits.</p>
+""" .
+
+atom:Thing
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Atom ;
+ rdfs:label "Thing" ;
+ atom:cType "LV2_Thing" ;
+ lv2:documentation """
+<p>Abstract base class for a "Thing", i.e. an atom:Atom with a number of
+properties. An LV2_Object is an unsigned 32-bit integer <code>context</code>
+and <code>id</code> followed by a sequence of LV2_Atom_Property .</p>
+
+<p>The <code>context</code> is mapped using the <a
+href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's
+LV2_URI_Map_Feature::uri_to_id() with <code>map = NULL</code>, and may be 0
+(the default context).</p>
+
+<p>Note this is an abstract class, i.e. no Atom can exist with <code>type =
+uri_to_id(atom:Thing)</code>. An Object is either an atom:Resource or an
+atom:Blank, but the <code>body</code> always has the same binary format,
+LV2_Object. Thus, both named and anonymous objects can be handled with common
+code using only a 64-bit header for both.</p>
+""" .
+
+atom:Resource
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Thing ;
+ atom:cType "LV2_Thing" ;
+ lv2:documentation """
+<p>An atom:Thing where <code>id</code> is the URI of the resource mapped to an
+atom:URID.</p>
+""" .
+
+atom:Blank
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Thing ;
+ atom:cType "LV2_Thing" ;
+ lv2:documentation """
+<p>An atom:Thing 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. In particular, <code>id</code>
+is NOT a URID.</p>
+""" .
+
+atom:Message
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Thing ;
+ atom:cType "LV2_Thing" ;
+ lv2:documentation """
+<p>A atom:Thing where <code>id</code> is a message type ID. Conceptually, a
+Message is identical to a Blank, but is a distinct type with a single type
+field to allow simple and fast dispatch by handling code.</p>
+
+<p>A Message may be serialised as a Blank by adding an rdf:type property with
+the value <code>id</code> unmapped to a URI.</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 for sample accurate
+transmission via LV2 ports. See struct LV2_Atom_Event.</p>
+""" .
+
+atom:Bang
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Atom ;
+ rdfs:label "Bang (activity) (size = 0)" .
+
+atom:Number
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Atom ;
+ rdfs:label "Number (abstract class)." .
+
+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:Bool
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Atom ;
+ rdfs:label "An atom:Int32 where 0 is false and all other values true" ;
+ atom:cType "LV2_Atom_Int32" .
+
+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:blobSupport
+ a lv2:Feature ;
+ rdfs:label "Blob support" ;
+ lv2:documentation """
+<p>Support for dynamically allocated blobs. If a host supports this feature,
+it MUST pass a LV2_Feature with <code>URI</code>
+http://lv2plug.in/ns/ext/atom#blobSupport and <code>data</code> pointing to a
+LV2_Blob_Support.</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 32-bit aligned LV2_Atom immediately followed by
+<code>size</code> bytes of data.</p>
+
+<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 atom:ValuePort or atom:MessagePort).
+</p>
+
+<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>).</p>
+""" .
+
+atom:ValuePort
+ a rdfs:Class ;
+ rdfs:subClassOf atom:AtomPort ;
+ rdfs:label "Value Port" ;
+ lv2:documentation """
+<p>An AtomPort that interprets its data as a persistent and time-independent
+"value".</p>
+<ul>
+<li>If a plugin has fixed input values for all ports, 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 V of that ValuePort corresponds to a single set of outputs
+for all ports.</li>
+<li>If a ValuePort contains a reference then the blob it refers to is
+constant; plugin MUST NOT modify the blob in any way.</li>
+</ul>
+<p>Value ports can be thought of as purely functional ports: if a plugin
+callback has only value ports, then the plugin callback is a pure function.</p>
+""" .
+
+atom:MessagePort
+ a rdfs:Class ;
+ rdfs:subClassOf atom:AtomPort ;
+ rdfs:label "Message Port" ;
+ rdfs:comment """
+An AtomPort that "receives", "consumes", "executes", or "sends" its value.
+The Atom contained in a MessagePort is considered transient and/or
+time-dependent, and is only valid for a single run invocation. Unlike a
+ValuePort, a MessagePort may be used to manipulate internal plugin state.
+
+Intuitively, a MessagePort contains a "message" or "command" or "event"
+which is reacted to, NOT a "value" or "signal" (which is computed with).
+""" .
+
+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:EventPort
+ a rdfs:Class ;
+ rdfs:label "Event port" ;
+ rdfs:subClassOf lv2:Port ;
+ lv2:documentation """
+<p>A port used for communicating time-stamped atoms in the audio context.
+Ports of this type are connected to an LV2_Atom_Buffer, which contains a flat
+time-stamped sequence of atom:Event.</p>
+
+<p>This port type is intended as a simpler and atom compatible successor to <a
+href="http://lv2plug.in/ns/ext/event#EventPort">ev:EventPort</a>.</p>
+""" .
+
+atom:supports
+ a rdf:Property ;
+ rdfs:domain lv2:Port ;
+ rdfs:range atom:Atom ;
+ rdfs:label "supports" ;
+ lv2:documentation """
+<p>Indicates that a Port supports a certain atom:Atom 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 Atom types a Port expects to
+receive or send.</p>
+""" .