aboutsummaryrefslogtreecommitdiffstats
path: root/ext/atom.lv2/atom.ttl
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2010-10-04 18:21:08 +0000
committerDavid Robillard <d@drobilla.net>2010-10-04 18:21:08 +0000
commitcef9811dac46a9d54dab0f0d82ce5c3ae032fc7c (patch)
tree632b911da25fc24b6b3d331d7ceffc22606b8e5b /ext/atom.lv2/atom.ttl
parent61842745ab15454ee66be54a6f3bcc148a75406f (diff)
downloadlv2-cef9811dac46a9d54dab0f0d82ce5c3ae032fc7c.tar.xz
Initial import of lv2plug.in universe.
Diffstat (limited to 'ext/atom.lv2/atom.ttl')
-rw-r--r--ext/atom.lv2/atom.ttl272
1 files changed, 272 insertions, 0 deletions
diff --git a/ext/atom.lv2/atom.ttl b/ext/atom.lv2/atom.ttl
new file mode 100644
index 0000000..ad957f3
--- /dev/null
+++ b/ext/atom.lv2/atom.ttl
@@ -0,0 +1,272 @@
+# LV2 Atom Extension
+# Copyright (C) 2007-2010 David Robillard <d@drobilla.net>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE 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> .
+
+<http://lv2plug.in/ns/ext/atom>
+ a lv2:Specification ;
+ doap:name "LV2 Atom" ;
+ doap:maintainer [
+ a foaf:Person ;
+ foaf:name "David Robillard" ;
+ 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
+"atom" (e.g. integers, strings, buffers, data structures, etc). Atoms allow
+LV2 plugins and host to communicate and store values of any type and size via
+a generic mechanism (e.g. port buffers, event payloads, shared data, etc.).
+Atoms are simple a chunk of memory with a type and a size, and are (with
+one exception) Plain Old Data (POD) and may be safely copied (e.g. with a
+simple call to <code>memcpy</code>). Because they are POD, hosts and plugins
+can communicate atoms of any type, even if they do not understand that type.
+This allows two plugins that both understand some type to be used together in
+a host that does not itself understand that type, or allows a host to send
+atoms "through" a plugin that does not understand them (for e.g. routing,
+delaying, or buffering plugins).
+
+Atoms as defined by this extension can be trivially constructed in-place
+from events as defined by the <a href="http://lv2plug.in/ns/ext/event">LV2
+Event</a> extension. A valid LV2_Atom (see atom.h) is contained within
+any valid LV2_Event (see event.h). An LV2_Event is simply an LV2_Atom
+with a time stamp header prepended. Atoms should be used anywhere a "value"
+needs to be stored or communicated, which allows implementations to be
+polymorphic and extensible.
+
+Optionally, the host MAY support "Blobs", which are dynamically allocated
+chunks of memory that (unlike Atoms) are not necessarily POD. Blobs are
+accessed via references, which are a special case of Atom that always have
+type 0, are 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.
+Blob data MUST NOT be used in any way by an implementation that does not
+understand that blob type (meaningful type-oblivious use is impossible,
+e.g. the blob pointer may not point to actual memory).
+
+This extension requires the host to support the <a
+href="http://lv2plug.in/ns/ext/uri-map">LV2 URI Map</a> extension.
+""" .
+
+
+atom:AtomType a rdfs:Class ;
+ rdfs:label "LV2 Atom Type" ;
+ rdfs:comment """
+Base class for all types of LV2 Atom.
+
+All Atom types (instances of this class, which are themselves classes)
+must define a precise binary layout for that type of atom, which dictates
+the format of the data following the LV2_Atom header. Pedantically, this
+class refers to the type of memory starting where the LV2_Atom header starts,
+i.e. a chunk of memory with any type that is a subClassOf atom:AtomType by
+definition starts with an LV2_Atom. The area after the header is referred
+to as the atom's "body".
+
+The URIs of subclasses of atom:AtomType are mapped to integers and used as
+the type field of an LV2_Atom. If a plugin or host does not understand
+the type of an LV2_Atom, that atom SHOULD simply be ignored (though it
+MAY be simply copied if it is not a reference).
+
+All atoms are POD by definition, except references, which have type 0.
+An atom MUST NOT contain a reference. It is safe to copy any type of
+atom except type 0 with a simple memcpy using the size field, even if the
+implementation does not understand the actual type of that atom.
+""" .
+
+
+atom:Reference a atom:AtomType ;
+ rdfs:label "Reference" ;
+ rdfs:comment """
+Reference to a blob. The actual contents of a reference are opaque and host
+specific, and must not be copied, serialized, or otherwise interpreted by
+a plugin, except by using functions provided by the host.
+
+References are a special case: a reference atom always has type 0.
+The NULL reference is the unique atom with type 0 and size 0.
+""" .
+
+
+atom:String a atom:AtomType ;
+ rdfs:label "String" ;
+ rdfs:comment """
+A UTF-8 encoded string, where LV2_Atom.size refers to the length of the
+string in bytes (not characters).
+""" .
+
+
+atom:URIInt a atom:AtomType ;
+ rdfs:label "URI mapped to an integer" ;
+ rdfs:comment """
+A uint32_t interpreted as a URI mapped to an integer using the LV2
+URI map extension &lt;http://lv2plug.in/ns/ext/uri-map&gt;. Size is
+always 4.
+""" .
+
+
+atom:Message a atom:AtomType ;
+ rdfs:label "Message" ;
+ rdfs:comment """
+A message is a communication from one component to another. Messages
+consist of a selector URI, and a set of RDF triples. The selector URI
+dictates how the triples are to be interpreted (e.g. the selector can
+be used as a "verb" to build commands).
+
+The payload of a message is always an atom:Triples so hosts and plugins can
+always work with message data (e.g. to serialise for saved state or an undo
+stack), even if they do not specifically understand a particular message.
+
+In memory, a Message is simply a uint32_t selector (a URI mapped integer)
+followed by an atom:Triples.
+""" .
+
+
+atom:Vector a atom:AtomType ;
+ rdfs:label "Vector" ;
+ rdfs:comment """
+A POD homogeneous sequence of atoms with equivalent type and size.
+
+The body of a vector begins with
+<pre>
+uint16_t elem_count; // The number of elements in the vector
+uint16_t elem_type; // The type of each element
+</pre>
+followed by <code>elem_count</code> bodies of atoms of type
+<code>elem_type</code>, each with equivalent size. For variably sized
+content types, this size can be calculated using the total byte size of the
+vector, e.g.
+<pre>
+uint16_t elem_size = (vector.size - (2 * sizeof(uint16_t))) / vector.count);
+</pre>
+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>type</code>.
+
+For example, an atom:Vector containing 42 elements of type atom:Int32 looks
+like this in memory:
+<pre>
+uint16_t atom_type = uri_map(atom:Vector)
+uint16_t atom_size = (2 * sizeof(uint16_t)) + (42 * sizeof(int32_t))
+uint16_t elem_count = 42
+uint16_t elem_type = uri_map(atom:Int32)
+int32_t contents[42] = ...
+</pre>
+""" .
+
+
+atom:Triple a atom:AtomType ;
+ rdfs:label "RDF triple" ;
+ rdfs:comment """
+A single RDF triple.
+
+The subject and predicate of an RDF triple are implicitly URIs, this in an
+atom:Triple they are stored as URI mapped integers with type tags and sizes
+omitted.
+
+An atom:Triple in memory is two uint32_t's followed by an LV2_Atom:
+<pre>
+uint32_t subject;
+uint32_t predicate;
+LV2_Atom object;
+</pre>
+""" .
+
+
+atom:Triples a atom:AtomType ;
+ rdfs:label "RDF triple set" ;
+ rdfs:comment """
+A description in RDF (i.e. a set of triples).
+
+An atom:Triples contains any number of RDF triples, describing one or
+several resources. The subject and predicate of all triples are implicitly
+URI mapped integers, type tags are omitted. The object of triples may be
+any atom.
+
+An atom:Triples in memory is a sequence of atom:Triple where each atom:Triple
+is immediately followed by the next (without time stamps or sizes), with
+padding to ensure each subject is 32-bit aligned, e.g.:
+<pre>
+uint32_t subject1;
+uint32_t predicate1;
+LV2_Atom object1;
+uint8_t pad[1]; /* e.g. if object1.size == 3 */
+uint32_t subject2;
+uint32_t predicate2;
+LV2_Atom object2;
+...
+</pre>
+""" .
+
+
+atom:Blank a atom:AtomType ;
+ rdfs:label "Blank (anonymous resource)" ;
+ rdfs:comment """
+A description of an RDF resource with no URI (a resource with blank node
+ID), e.g. the resource of type ex:Foo in the following Turtle description:
+<code>&lt;&gt; ex:hasThing [ a ex:Thing ]</code>
+
+An atom:Blank is conceptually a dictionary where keys (RDF predicates) are
+URI mapped integers, and values (RDF objects) are any atom.
+
+An atom:Blank in memory is like an atom:Triples, but with subjects omitted:
+<pre>
+uint32_t predicate1;
+LV2_Atom object1;
+uint32_t predicate2;
+LV2_Atom object2;
+...
+</pre>
+""" .
+
+
+atom:Bang a atom:AtomType ; rdfs:label "Bang (generic activity), size=0" .
+atom:Byte a atom:AtomType ; rdfs:label "A byte" .
+atom:Int32 a atom:AtomType ; rdfs:label "Signed 32-bit Integer" .
+atom:Bool a atom:AtomType ; rdfs:label "atom:Int32 where 0=false, 1=true" .
+atom:Float32 a atom:AtomType ; rdfs:label "32-bit Floating Point Number" .
+atom:Float64 a atom:AtomType ; rdfs:label "64-bit Floating Point Number" .
+
+
+atom:blobSupport a lv2:Feature ;
+ rdfs:label "Blob support" ;
+ rdfs:comment """
+Support for dynamically allocated blobs. If a host supports this feature, it
+MUST pass an LV2_Feature with URI http://lv2plug.in/ns/ext/atom#blobSupport
+and a pointer to LV2_Blob_Support as data to the plugin's instantiate method.
+See atom.h for details.
+""" .
+
+
+atom:BlobType a rdfs:Class ;
+ rdfs:label "Blob Type" ;
+ rdfs:comment """
+Base class for all types of dynamically allocated LV2 blobs. Blobs can be of
+any type at all, there are no restrictions on the binary format or contents
+of a blob. Blobs are dynamically allocated by the host (or a plugin via
+the host), and unlike Atoms are not necessarily POD.
+
+The type of a blob MAY be a atom:AtomType, in which case the start of the
+blob data is the start of the Atom header (LV2_Atom).
+""" .
+