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/ns/ext/atom/atom.ttl | 462 ----------------------------------------------- 1 file changed, 462 deletions(-) delete mode 100644 lv2/ns/ext/atom/atom.ttl (limited to 'lv2/ns/ext/atom/atom.ttl') 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 -# -# 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