diff options
Diffstat (limited to 'lv2/ns/ext/atom/atom.ttl')
| -rw-r--r-- | lv2/ns/ext/atom/atom.ttl | 462 |
1 files changed, 0 insertions, 462 deletions
diff --git a/lv2/ns/ext/atom/atom.ttl b/lv2/ns/ext/atom/atom.ttl deleted file mode 100644 index 7d534d0..0000000 --- a/lv2/ns/ext/atom/atom.ttl +++ /dev/null @@ -1,462 +0,0 @@ -# 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> -""" . |