From ed78bbe5ba12be1f9bcc736f14c51da6b4f639f3 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 8 Feb 2012 04:56:24 +0000 Subject: Rearrange tree so top level can be used as an include path for standard style LV2 includes. --- lv2/lv2plug.in/ns/ext/atom/atom.ttl | 462 ++++++++++++++++++++++++++++++++++++ 1 file changed, 462 insertions(+) create mode 100644 lv2/lv2plug.in/ns/ext/atom/atom.ttl (limited to 'lv2/lv2plug.in/ns/ext/atom/atom.ttl') 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 +# +# 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: . +@prefix doap: . +@prefix foaf: . +@prefix lv2: . +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . + + + a lv2:Specification ; + doap:name "LV2 Atom" ; + doap:shortdesc "A generic value container and several data types." ; + doap:license ; + rdfs:seeAlso , + ; + doap:release [ + doap:revision "0.4" ; + doap:created "2012-02-07" + ] ; + doap:maintainer [ + a foaf:Person ; + foaf:name "David Robillard" ; + foaf:homepage ; + rdfs:seeAlso + ] ; + lv2:documentation """ +

This extension defines a generic container for data, called an Atom, +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 memcpy).

+ +

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.

+ +

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 LV2 event extension.

+ +

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 struct type). New binary formats are an +implementation burden which harms interoperabilty, and should only be defined +where absolutely necessary.

+ +

Implementing this extension requires a facility for mapping URIs to +integers, such as the LV2 URID +extension.

+""" . + +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 """ +

Abstract base class for all atoms. An LV2_Atom has a 32-bit +type and size followed by a body of size +bytes. Atoms MUST be 64-bit aligned.

+ +

All concrete Atom types (subclasses of this class) MUST define a precise +binary layout for their body.

+ +

The type field is the URI of an Atom type mapped to an integer. +Implementations SHOULD gracefully ignore, or pass through, atoms with unknown +types.

+ +

All atoms are POD by definition except references, which as a special case +have type = 0. An Atom MUST NOT contain a Reference. It is safe +to copy any non-reference Atom with a simple memcpy, even if the +implementation does not understand type. 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 type and size 0 is +null, which is not considered a Reference.

+""" . + +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 """ +

A UTF-8 encoded string.

+ +

The body of an LV2_Atom_String is a C string in UTF-8 encoding, i.e. an +array of bytes (uint8_t) terminated with a NULL byte +('\\0').

+ +

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.

+""" . + +atom:Literal + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "String Literal" ; + atom:cType "LV2_Atom_Literal" ; + lv2:documentation """ +

A UTF-8 encoded string literal, with an optional datatype or language.

+ +

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 +datatype and lang followed by string data in UTF-8 +encoding. The length of the string data in bytes is size - +sizeof(LV2_Atom_Literal), including the terminating NULL character. The +lang field SHOULD be a URI of the form +<http://lexvo.org/id/term/LANG> where LANG is an ISO 693-2 or ISO 693-3 language code.

+ +

A Literal may have a datatype OR a lang, but never +both.

+ +

For example, a Literal can be "Hello" in English:

+
+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
+}
+
+ +

or a Turtle string:

+
+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
+}
+
+""" . + +atom:URID + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Integer ID mapped from a URI" ; + atom:cType "LV2_Atom_ID" ; + lv2:documentation """ +

An unsigned 32-bit integer mapped from a URI (e.g. with LV2_URID_Map).

+""" . + +atom:Vector + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Vector" ; + atom:cType "LV2_Atom_Vector" ; + lv2:documentation """ +

A homogeneous series of atom bodies with equivalent type and size.

+ +

An LV2_Atom_Vector is a 32-bit elem_count and +elem_type followed by elem_count atom bodies of type +elem_type. The element type must be a fixed size atom:Atom type, +i.e. the size of each element is the vector's size / +elem_count.

+ +

For example, an atom:Vector containing 42 elements of type atom:Float:

+
+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];
+};
+
+ +

Note that it is possible to construct a valid Atom for each element +of the vector, even by an implementation which does not understand +elem_type.

+""" . + +atom:Tuple + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Tuple" ; + lv2:documentation """ +

A series of Atoms with varying type and size.

+ +

The body of a Tuple is simply a series of complete atoms, each aligned to +64 bits.

+""" . + +atom:Property + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Property" ; + atom:cType "LV2_Atom_Property" ; + lv2:documentation """ +

A property of an atom:Object. An LV2_Atom_Property has a URID +key and context, and an Atom value. +This corresponds to an RDF Property, where the key is the predicate +and the value is the object.

+ +

The context field can be used to specify a different context +for each property, where this is useful. Otherwise, it may be 0.

+""" . + +atom:Object + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Object" ; + atom:cType "LV2_Atom_Object" ; + lv2:documentation """ +

An Object 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.

+ +

An LV2_Atom_Object has a uint32_t id and uint32_t +type, 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.

+ +

This is an abstract Atom type, an Object is always either a atom:Resource +or a atom:Blank.

+""" . + +atom:Resource + a rdfs:Class ; + rdfs:subClassOf atom:Object ; + rdfs:label "Resource" ; + atom:cType "LV2_Atom_Object" ; + lv2:documentation """ +

An atom:Object where the id field is a URID, i.e. an Object +with a URI.

+""" . + +atom:Blank + a rdfs:Class ; + rdfs:subClassOf atom:Object ; + rdfs:label "Blank" ; + atom:cType "LV2_Atom_Object" ; + lv2:documentation """ +

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.

""" . + +atom:Event + a rdfs:Class ; + rdfs:label "Event" ; + atom:cType "LV2_Atom_Event" ; + lv2:documentation """ +

An atom with a time stamp header prepended, typically an element of an +atom:Sequence. Note this is not an Atom type.

+""" . + +atom:Sequence + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Sequence" ; + atom:cType "LV2_Atom_Sequence" ; + lv2:documentation """ +

A sequence of atom:Event, i.e. a series of time-stamped Atoms.

+""" . + +atom:AtomPort + a rdfs:Class ; + rdfs:subClassOf lv2:Port ; + rdfs:label "Atom Port" ; + lv2:documentation """ +

A port which contains an lv2:Atom. Ports of this type will be connected to +a 64-bit aligned LV2_Atom immediately followed by size bytes of +data.

+ +

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.

+ +

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 +type and size 0).

+""" . + +atom:ValuePort + a rdfs:Class ; + rdfs:subClassOf atom:AtomPort ; + rdfs:label "Value Port" ; + lv2:documentation """ + +

An AtomPort that contains a persistent value. A value is +time-independent and may be used numerous times. A ValuePort is pure in +the sense that it may affect output but MUST NOT affect persistent plugin state +in any externally visible way.

+ +
    +
  • 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.
    • + +
  • 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.
    • + +
  • If the plugin saves state other than port values (e.g. using the LV2 State 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.
    • +
+ +

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.

+""" . + +atom:MessagePort + a rdfs:Class ; + rdfs:subClassOf atom:AtomPort ; + rdfs:label "Message Port" ; + lv2:documentation """ +

An AtomPort that contains transient data which is consumed or +sent. 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.

+ +

Intuitively, a MessagePort contains a message or event which +is reacted to once (not a value which is computed with any +number of times).

+""" . + +atom:bufferType + a rdf:Property ; + rdfs:domain atom:AtomPort ; + rdfs:label "buffer type" ; + lv2:documentation """ +

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:

+ +
+<plugin>
+    lv2:port [
+        a lv2:InputPort , atom:ValuePort ;
+        atom:bufferType atom:Double ;
+    ] .
+
+ +

Note this property only indicates the atom types a port may be directly +connected to, it is not recursive. 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.

+""" . + +atom:supports + a rdf:Property ; + rdfs:label "supports" ; + lv2:documentation """ +

Indicates that a particular Atom type is supported.

+ +

This property is defined loosely, it may be used to indicate that anything +supports an Atom type, wherever that may be useful. It applies +recursively where collections are involved.

+ +

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:

+ +
+<plugin>
+    lv2:port [
+        a lv2:InputPort , atom:MessagePort ;
+        atom:bufferType atom:Sequence ;
+        atom:supports midi:MidiEvent ;
+    ] .
+
+""" . -- cgit v1.2.1