From 430284545345539c9ffb31df889debac1d3888b5 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 22 Mar 2020 16:36:44 +0100 Subject: Move documentation to metadata files and convert it to Markdown --- lv2/atom/atom.meta.ttl | 440 ++++++++++++++++++++++++++++++++++++++++++++- lv2/atom/atom.ttl | 473 ++++++------------------------------------------- 2 files changed, 497 insertions(+), 416 deletions(-) (limited to 'lv2/atom') diff --git a/lv2/atom/atom.meta.ttl b/lv2/atom/atom.meta.ttl index 4f6e69b..7b04180 100644 --- a/lv2/atom/atom.meta.ttl +++ b/lv2/atom/atom.meta.ttl @@ -1,6 +1,8 @@ +@prefix atom: . @prefix dcs: . @prefix doap: . @prefix foaf: . +@prefix lv2: . @prefix rdfs: . @@ -100,5 +102,441 @@ rdfs:label "Initial release." ] ] - ] . + ] ; + lv2:documentation """ + +An atom: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 +(for example, with `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. An atom:AtomPort can be used to transmit atoms via ports. An +atom:AtomPort that contains a atom:Sequence can be used for sample accurate +communication of events, such as MIDI. + +### 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 (for example, using atom:Object rather than a +new C `struct` type). Host and tool 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 binary 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. + +"""^^lv2:Markdown . + +atom:Atom + lv2:documentation """ + +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 special case of a null atom with both `type` and `size` 0 is not considered +a reference. + +"""^^lv2:Markdown . + +atom:Chunk + lv2:documentation """ + +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, for example: + + :::turtle + [] eg:someChunk "vu/erQ=="^^xsd:base64Binary . + +"""^^lv2:Markdown . + +atom:String + lv2:documentation """ + +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. + +"""^^lv2:Markdown . + +atom:Literal + lv2:documentation """ + +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: + + :::c + 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: + + :::c + 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 + } + +"""^^lv2:Markdown . + +atom:Path + lv2:documentation """ + +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. + +"""^^lv2:Markdown . + +atom:URI + lv2:documentation """ + +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. + +"""^^lv2:Markdown . + +atom:URID + lv2:documentation """ + +A URID is typically generated with the LV2_URID_Map provided by the host . + +"""^^lv2:Markdown . + +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: + + :::c + 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: + + :::turtle + eg:someVector + a atom:Vector ; + atom:childType atom:Int ; + rdf:value ( + "1"^^xsd:int + "2"^^xsd:int + "3"^^xsd:int + "4"^^xsd:int + ) . + +"""^^lv2:Markdown . + +atom:Tuple + lv2:documentation """ + +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: + + :::turtle + eg:someVector + a atom:Tuple ; + rdf:value ( + "1"^^xsd:int + "3.5"^^xsd:float + "etc" + ) . + +"""^^lv2:Markdown . + +atom:Property + lv2:documentation """ + +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, for example: + + :::turtle + eg:someProperty + rdf:predicate eg:theKey ; + rdf:object eg:theValue . + +"""^^lv2:Markdown . + +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, for example: + + :::turtle + eg:someObject + eg:firstPropertyKey "first property value" ; + eg:secondPropertyKey "first loser" ; + eg:andSoOn "and so on" . + +"""^^lv2:Markdown . + +atom:Resource + lv2:documentation """ + +This class is deprecated. Use atom:Object directly instead. + +An atom:Object where the id field is a URID, that is, an Object +with a URI. + +"""^^lv2:Markdown . + +atom:Blank + 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. + +"""^^lv2:Markdown . + +atom:Sound + lv2:documentation """ + +The format of a atom:Sound 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. + +"""^^lv2:Markdown . + +atom:Event + lv2:documentation """ + +An Event is typically an element of an atom:Sequence. Note that this is not an Atom type since it begins with a timestamp, not an atom header. + +"""^^lv2:Markdown . + +atom:Sequence + lv2:documentation """ + +A flat sequence of atom:Event, that is, 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, for example: + + :::turtle + eg:someSequence + a atom:Sequence ; + rdf:value ( + [ + atom:frameTime 1 ; + rdf:value "901A01"^^midi:MidiEvent + ] [ + atom:frameTime 3 ; + rdf:value "902B02"^^midi:MidiEvent + ] + ) . + +"""^^lv2:Markdown . + +atom:AtomPort + lv2:documentation """ + +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(). + +"""^^lv2:Markdown . + +atom:bufferType + 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: + + :::turtle + <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. + +"""^^lv2:Markdown . + +atom:supports + lv2:documentation """ + +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: + + :::turtle + <plugin> + lv2:port [ + a lv2:InputPort , atom:AtomPort ; + atom:bufferType atom:Sequence ; + atom:supports midi:MidiEvent ; + ] . + +"""^^lv2:Markdown . + +atom:eventTransfer + 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. + +"""^^lv2:Markdown . + +atom:atomTransfer + 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. + +"""^^lv2:Markdown . diff --git a/lv2/atom/atom.ttl b/lv2/atom/atom.ttl index dc9fa1e..96e9326 100644 --- a/lv2/atom/atom.ttl +++ b/lv2/atom/atom.ttl @@ -14,121 +14,44 @@ , , ; - 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.

-""" . + rdfs:label "LV2 Atom" ; + rdfs:comment "A generic value container and several data types." . atom:cType a rdf:Property , owl:DatatypeProperty , owl:FunctionalProperty ; rdfs:label "C type" ; + rdfs:comment "The C type that describes the binary representation of an Atom 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." . + rdfs:range lv2:Symbol . 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.

-""" . + rdfs:comment "Abstract base class for all atoms." ; + atom:cType "LV2_Atom" . 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 .
-
-""" . + rdfs:label "Chunk" ; + rdfs:comment "A chunk of memory with undefined contents." ; + owl:onDatatype xsd:base64Binary . atom:Number a rdfs:Class ; rdfs:subClassOf atom:Atom ; - rdfs:label "Number" . + rdfs:label "Number" ; + rdfs:comment "Base class for numeric types." . atom:Int a rdfs:Class , rdfs:Datatype ; rdfs:subClassOf atom:Number ; - rdfs:label "Signed 32-bit integer" ; + rdfs:label "Int" ; + rdfs:comment "A native `int32_t`." ; atom:cType "LV2_Atom_Int" ; owl:onDatatype xsd:int . @@ -136,7 +59,8 @@ atom:Long a rdfs:Class , rdfs:Datatype ; rdfs:subClassOf atom:Number ; - rdfs:label "Signed 64-bit integer" ; + rdfs:label "Long" ; + rdfs:comment "A native `int64_t`." ; atom:cType "LV2_Atom_Long" ; owl:onDatatype xsd:long . @@ -144,7 +68,8 @@ atom:Float a rdfs:Class , rdfs:Datatype ; rdfs:subClassOf atom:Number ; - rdfs:label "32-bit floating point number" ; + rdfs:label "Float" ; + rdfs:comment "A native `float`." ; atom:cType "LV2_Atom_Float" ; owl:onDatatype xsd:float . @@ -152,7 +77,8 @@ atom:Double a rdfs:Class , rdfs:Datatype ; rdfs:subClassOf atom:Number ; - rdfs:label "64-bit floating point number" ; + rdfs:label "Double" ; + rdfs:comment "A native `double`." ; atom:cType "LV2_Atom_Double" ; owl:onDatatype xsd:double . @@ -160,289 +86,99 @@ atom:Bool a rdfs:Class , rdfs:Datatype ; rdfs:subClassOf atom:Atom ; - rdfs:label "Boolean" ; + rdfs:label "Bool" ; + rdfs:comment "An atom:Int where 0 is false and any other value is true." ; atom:cType "LV2_Atom_Bool" ; - owl:onDatatype xsd:boolean ; - rdfs:comment "An Int where 0 is false and any other value is true." . + owl:onDatatype xsd:boolean . atom:String a rdfs:Class , rdfs:Datatype ; rdfs:subClassOf atom:Atom ; rdfs:label "String" ; + rdfs:comment "A UTF-8 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.

-""" . + owl:onDatatype xsd:string . 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
-}
-
-""" . + rdfs:label "Literal" ; + rdfs:comment "A UTF-8 string literal with optional datatype or language." ; + atom:cType "LV2_Atom_Literal" . 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.

-""" . + rdfs:label "Path" ; + rdfs:comment "A local file path." . 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.

-""" . + rdfs:label "URI" ; + rdfs:comment "A URI string." . 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).

-""" . + rdfs:label "URID" ; + rdfs:comment "An unsigned 32-bit integer ID for a URI." ; + atom:cType "LV2_Atom_URID" . 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
-     ) .
-
-""" . + rdfs:comment "A homogeneous sequence of atom bodies with equivalent type and size." ; + atom:cType "LV2_Atom_Vector" . 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"
-     ) .
-
- -""" . + rdfs:comment "A sequence of atoms with varying type and size." . 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 .
-
-""" . + rdfs:comment "A property of an atom:Object." ; + atom:cType "LV2_Atom_Property" . 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" .
-
-""" . + rdfs:comment "A collection of properties." ; + atom:cType "LV2_Atom_Object" . atom:Resource a rdfs:Class ; rdfs:subClassOf atom:Object ; rdfs:label "Resource" ; + rdfs:comment "A named collection of properties with a URI." ; 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:cType "LV2_Atom_Object" . atom:Blank a rdfs:Class ; rdfs:subClassOf atom:Object ; rdfs:label "Blank" ; + rdfs:comment "An anonymous collection of properties without a URI." ; 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:cType "LV2_Atom_Object" . 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.

-""" . + rdfs:comment "A atom:Vector of atom:Float which represents an audio waveform." ; + atom:cType "LV2_Atom_Sound" . atom:frameTime a rdf:Property , @@ -450,9 +186,7 @@ atom:frameTime owl:FunctionalProperty ; rdfs:range xsd:decimal ; rdfs:label "frame time" ; - lv2:documentation """ -

Time stamp in audio frames. Typically used for events.

-""" . + rdfs:comment "A time stamp in audio frames." . atom:beatTime a rdf:Property , @@ -460,66 +194,26 @@ atom:beatTime owl:FunctionalProperty ; rdfs:range xsd:decimal ; rdfs:label "beat time" ; - lv2:documentation """ -

Time stamp in beats. Typically used for events.

-""" . + rdfs:comment "A time stamp in beats." . 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.

-""" . + rdfs:comment "An atom with a time stamp prefix in a sequence." . 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
-        ]
-    ) .
-
-""" . + rdfs:comment "A sequence of events." . 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().

-""" . + rdfs:comment "A port which contains an atom:Atom." . atom:bufferType a rdf:Property , @@ -527,78 +221,27 @@ atom:bufferType 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.

-""" . + rdfs:comment "An atom type that a port may be connected to." . atom:childType a rdf:Property , owl:ObjectProperty ; rdfs:label "child type" ; - rdfs:comment """The type of a container's children.""" . + rdfs:comment "The type of children in a container." . 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 ;
-    ] .
-
-""" . + rdfs:comment "A supported atom type." ; + rdfs:range rdfs:Class . 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.

-""" . + rdfs:comment "A port protocol for transferring events." . 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.

-""" . + rdfs:comment "A port protocol for transferring atoms." . -- cgit v1.2.1