From 4db67120efca2d4c200d2e1ba5cf3d7b97cab97e Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 22 Sep 2018 20:38:01 +0200 Subject: Install standard headers to simpler include paths --- lv2/atom/atom.ttl | 602 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 602 insertions(+) create mode 100644 lv2/atom/atom.ttl (limited to 'lv2/atom/atom.ttl') diff --git a/lv2/atom/atom.ttl b/lv2/atom/atom.ttl new file mode 100644 index 0000000..891cd1f --- /dev/null +++ b/lv2/atom/atom.ttl @@ -0,0 +1,602 @@ +@prefix atom: . +@prefix lv2: . +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix ui: . +@prefix units: . +@prefix xsd: . + + + a owl:Ontology ; + rdfs:seeAlso , + , + , + ; + lv2:documentation """ + +

An #Atom is a simple generic data container for holding any type of Plain +Old Data (POD). An #Atom can contain simple primitive types like integers, +floating point numbers, and strings; as well as structured data like lists and +dictionary-like Objects. Since Atoms are POD, they can be easily copied +(e.g. using memcpy) anywhere and are suitable for use in real-time +code.

+ +

Every atom starts with an LV2_Atom header, followed by the contents. This +allows code to process atoms without requiring special code for every type of +data. For example, plugins that mutually understand a type can be used +together in a host that does not understand that type, because the host is only +required to copy atoms, not interpret their contents. Similarly, plugins (such +as routers, delays, or data structures) can meaningfully process atoms of a +type unknown to them.

+ +

Atoms should be used anywhere values of various types must be stored or +transmitted. The port type #AtomPort can be used to transmit atoms via ports. +An #AtomPort that contains an #Sequence can be used for sample accurate event +communication, such as MIDI, and replaces the earlier event extension.

+ +

Serialisation

+ +

Each Atom type defines a binary format for use at runtime, but also a +serialisation that is natural to express in Turtle format. Thus, this +specification defines a powerful real-time appropriate data model, as well as a +portable way to serialise any data in that model. This is particularly useful +for inter-process communication, saving/restoring state, and describing values +in plugin data files.

+ +

Custom Atom Types

+ +

While it is possible to define new Atom types for any binary format, the +standard types defined here are powerful enough to describe almost anything. +Implementations SHOULD build structures out of the types provided here, rather +than define new binary formats (e.g. use #Tuple or #Object rather than +a new C struct type). Current implementations have support for +serialising all standard types, so new binary formats are an implementation +burden which harms interoperabilty. In particular, plugins SHOULD NOT expect +UI communication or state saving with custom Atom types to work. In general, +new Atom types should only be defined where absolutely necessary due to +performance reasons and serialisation is not a concern.

+""" . + +atom:cType + a rdf:Property , + owl:DatatypeProperty , + owl:FunctionalProperty ; + rdfs:label "C type" ; + rdfs:domain rdfs:Class ; + rdfs:range lv2:Symbol ; + rdfs:comment """The identifier for a C type describing the binary representation of an Atom of this type.""" . + +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 +size and type 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 pass through, or ignore, 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:Chunk + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Chunk of memory" ; + owl:onDatatype xsd:base64Binary ; + lv2:documentation """ +

A chunk of memory with undefined contents. This type is used to indicate a +certain amount of space is available. For example, output ports with a +variably sized type are connected to a Chunk so the plugin knows the size of +the buffer available for writing.

+ +

The use of a Chunk should be constrained to a local scope, since +interpreting it is impossible without context. However, if serialised to RDF, +a Chunk may be represented directly as an xsd:base64Binary string, e.g.:

+ +
+[] eg:someChunk "vu/erQ=="^^xsd:base64Binary .
+
+""" . + +atom:Number + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Number" . + +atom:Int + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:Number ; + rdfs:label "Signed 32-bit integer" ; + atom:cType "LV2_Atom_Int" ; + owl:onDatatype xsd:int . + +atom:Long + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:Number ; + rdfs:label "Signed 64-bit integer" ; + atom:cType "LV2_Atom_Long" ; + owl:onDatatype xsd:long . + +atom:Float + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:Number ; + rdfs:label "32-bit floating point number" ; + atom:cType "LV2_Atom_Float" ; + owl:onDatatype xsd:float . + +atom:Double + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:Number ; + rdfs:label "64-bit floating point number" ; + atom:cType "LV2_Atom_Double" ; + owl:onDatatype xsd:double . + +atom:Bool + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Boolean" ; + atom:cType "LV2_Atom_Bool" ; + owl:onDatatype xsd:boolean ; + rdfs:comment "An Int where 0 is false and any other value is true." . + +atom:String + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:Atom ; + rdfs:label "String" ; + atom:cType "LV2_Atom_String" ; + owl:onDatatype xsd: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 is for free-form strings, but SHOULD NOT be used for typed data or +text in any language. Use atom:Literal 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 rdfs: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/iso639-3/LANG> or +<http://lexvo.org/id/iso639-1/LANG> where LANG is a 3-character ISO 693-3 +language code, or a 2-character ISO 693-1 language code, respectively.

+ +

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->body.datatype = 0;
+     lit->body.lang     = map("http://lexvo.org/id/iso639-1/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->body.datatype = map("http://www.w3.org/2008/turtle#turtle");
+     lit->body.lang     = 0;
+     memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit),
+            ttl,
+            strlen(ttl) + 1);  // Assumes enough space
+}
+
+""" . + +atom:Path + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:URI ; + owl:onDatatype atom:URI ; + rdfs:label "File path string" ; + lv2:documentation """ +

A local file path.

+ +

A Path is a URI reference with only a path component: no scheme, authority, +query, or fragment. In particular, paths to files in the same bundle may be +cleanly written in Turtle files as a relative URI. However, implementations +may assume any binary Path (e.g. in an event payload) is a valid file path +which can passed to system functions like fopen() directly, without any +character encoding or escape expansion required.

+ +

Any implemenation that creates a Path atom to transmit to another is +responsible for ensuring it is valid. A Path SHOULD always be absolute, unless +there is some mechanism in place that defines a base path. Since this is not +the case for plugin instances, effectively any Path sent to or received from a +plugin instance MUST be absolute.

+""" . + +atom:URI + a rdfs:Class , + rdfs:Datatype ; + rdfs:subClassOf atom:String ; + owl:onDatatype xsd:anyURI ; + rdfs:label "URI string" ; + lv2:documentation """ +

A URI string. This is useful when a URI is needed but mapping is +inappropriate, for example with temporary or relative URIs. Since the ability +to distinguish URIs from plain strings is often necessary, URIs MUST NOT be +transmitted as atom:String.

+ +

This is not strictly a URI, since UTF-8 is allowed. Escaping and related +issues are the host's responsibility.

+""" . + +atom:URID + a rdfs:Class ; + rdfs:subClassOf atom:Atom ; + rdfs:label "Integer URID" ; + atom:cType "LV2_Atom_URID" ; + 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 child_size and +child_type followed by size / child_size atom +bodies.

+ +

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

+
+struct VectorOf42Floats {
+    uint32_t size;        // sizeof(LV2_Atom_Vector_Body) + (42 * sizeof(float);
+    uint32_t type;        // map(expand("atom:Vector"))
+    uint32_t child_size;  // sizeof(float)
+    uint32_t child_type;  // map(expand("atom:Float"))
+    float    elems[42];
+};
+
+ +

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

+ +

If serialised to RDF, a Vector SHOULD have the form:

+ +
+eg:someVector
+     a atom:Vector ;
+     atom:childType atom:Int ;
+     rdf:value (
+         "1"^^xsd:int
+         "2"^^xsd:int
+         "3"^^xsd:int
+         "4"^^xsd:int
+     ) .
+
+""" . + +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.

+ +

If serialised to RDF, a Tuple SHOULD have the form:

+ +
+eg:someVector
+     a atom:Tuple ;
+     rdf:value (
+         "1"^^xsd:int
+         "3.5"^^xsd:float
+         "etc"
+     ) .
+
+ +""" . + +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.

+ +

Properties generally only exist as part of an atom:Object. Accordingly, +they will typically be represented directly as properties in RDF (see +atom:Object). If this is not possible, they may be expressed as partial +reified statements, e.g.:

+ +
+eg:someProperty
+    rdf:predicate eg:theKey ;
+    rdf:object eg:theValue .
+
+""" . + +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 body has a uint32_t id and +type, followed by a series of atom:Property bodies +(LV2_Atom_Property_Body). The LV2_Atom_Object_Body::otype field is equivalent +to a property with key rdf:type, but is included in the structure to allow for +fast dispatching.

+ +

Code SHOULD check for objects using lv2_atom_forge_is_object() or +lv2_atom_forge_is_blank() if a forge is available, rather than checking the +atom type directly. This will correctly handle the deprecated atom:Resource +and atom:Blank types.

+ +

When serialised to RDF, an Object is represented as a resource, e.g.:

+ +
+eg:someObject
+    eg:firstPropertyKey "first property value" ;
+    eg:secondPropertyKey "first loser" ;
+    eg:andSoOn "and so on" .
+
+""" . + +atom:Resource + a rdfs:Class ; + rdfs:subClassOf atom:Object ; + rdfs:label "Resource" ; + owl:deprecated "true"^^xsd:boolean ; + atom:cType "LV2_Atom_Object" ; + lv2:documentation """ +

This class is deprecated. Use atom:Object instead.

+ +

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" ; + owl:deprecated "true"^^xsd:boolean ; + atom:cType "LV2_Atom_Object" ; + lv2:documentation """ +

This class is deprecated. Use atom:Object with ID 0 instead.

+ +

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:Sound + a rdfs:Class ; + rdfs:subClassOf atom:Vector ; + rdfs:label "Sound" ; + atom:cType "LV2_Atom_Sound" ; + lv2:documentation """ +

An atom:Vector of atom:Float which represents an audio waveform. The format +is the same as the buffer format for lv2:AudioPort (except the size may be +arbitrary). An atom:Sound inherently depends on the sample rate, which is +assumed to be known from context. Because of this, directly serialising an +atom:Sound is probably a bad idea, use a standard format like WAV instead.

+""" . + +atom:frameTime + a rdf:Property , + owl:DatatypeProperty , + owl:FunctionalProperty ; + rdfs:range xsd:decimal ; + rdfs:label "frame time" ; + lv2:documentation """ +

Time stamp in audio frames. Typically used for events.

+""" . + +atom:beatTime + a rdf:Property , + owl:DatatypeProperty , + owl:FunctionalProperty ; + rdfs:range xsd:decimal ; + rdfs:label "beat time" ; + lv2:documentation """ +

Time stamp in beats. Typically used for events.

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

An atom with a time stamp prefix, 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.

+ +

LV2_Atom_Sequence_Body.unit describes the time unit for the contained atoms. +If the unit is known from context (e.g. run() stamps are always audio frames), +this field may be zero. Otherwise, it SHOULD be either units:frame or +units:beat, in which case ev.time.frames or ev.time.beats is valid, +respectively.

+ +

If serialised to RDF, a Sequence has a similar form to atom:Vector, but for +brevity the elements may be assumed to be atom:Event, e.g.:

+ +
+eg:someSequence
+    a atom:Sequence ;
+    rdf:value (
+        [
+            atom:frameTime 1 ;
+            rdf:value "901A01"^^midi:MidiEvent
+        ] [
+            atom:frameTime 3 ;
+            rdf:value "902B02"^^midi:MidiEvent
+        ]
+    ) .
+
+""" . + +atom:AtomPort + a rdfs:Class ; + rdfs:subClassOf lv2:Port ; + rdfs:label "Atom Port" ; + lv2:documentation """ +

A port which contains an atom:Atom. Ports of this type are connected to an +LV2_Atom with a type specified by atom:bufferType.

+ +

Output ports with a variably sized type MUST be initialised by the host +before every run() to an atom:Chunk with size set to the available space. The +plugin reads this size to know how much space is available for writing. In all +cases, the plugin MUST write a complete atom (including header) to outputs. +However, to be robust, hosts SHOULD initialise output ports to a safe sentinel +(e.g. the null Atom) before calling run().

+""" . + +atom:bufferType + a rdf:Property , + owl:ObjectProperty ; + rdfs:domain atom:AtomPort ; + rdfs:range rdfs:Class ; + 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:AtomPort ;
+        atom:bufferType atom:Double ;
+    ] .
+
+ +

This property only describes the types a port may be directly +connected to. It says nothing about the expected contents of containers. For +that, use atom:supports.

+""" . + +atom:childType + a rdf:Property , + owl:ObjectProperty ; + rdfs:label "child type" ; + rdfs:comment "The type of a container's children." . + +atom:supports + a rdf:Property ; + rdfs:label "supports" ; + rdfs:range rdfs:Class ; + 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 +expected by a port. For example, a port that receives MIDI events is described +like so:

+ +
+<plugin>
+    lv2:port [
+        a lv2:InputPort , atom:AtomPort ;
+        atom:bufferType atom:Sequence ;
+        atom:supports midi:MidiEvent ;
+    ] .
+
+""" . + +atom:eventTransfer + a ui:PortProtocol ; + rdfs:label "event transfer" ; + lv2:documentation """ +

Transfer of individual events in a port buffer. Useful as the +format for a LV2UI_Write_Function.

+ +

This protocol applies to ports which contain events, usually in an +atom:Sequence. The host must transfer each individual event to the recipient. +The format of the received data is an LV2_Atom, there is no timestamp +header.

+""" . + +atom:atomTransfer + a ui:PortProtocol ; + rdfs:label "atom transfer" ; + lv2:documentation """ +

Transfer of the complete atom in a port buffer. Useful as the +format for a LV2UI_Write_Function.

+ +

This protocol applies to atom ports. The host must transfer the complete +atom contained in the port, including header.

+""" . -- cgit v1.2.1