aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/atom
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2020-03-22 16:36:44 +0100
committerDavid Robillard <d@drobilla.net>2020-04-10 19:46:04 +0200
commit430284545345539c9ffb31df889debac1d3888b5 (patch)
treedc9bb1f32f0d6fe34a7339221389048e199f14a5 /lv2/atom
parentc4514483da1ab4f49148f9c4fe4ff5b559323217 (diff)
downloadlv2-430284545345539c9ffb31df889debac1d3888b5.tar.xz
Move documentation to metadata files and convert it to Markdown
Diffstat (limited to 'lv2/atom')
-rw-r--r--lv2/atom/atom.meta.ttl440
-rw-r--r--lv2/atom/atom.ttl473
2 files changed, 497 insertions, 416 deletions
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: <http://lv2plug.in/ns/ext/atom#> .
@prefix dcs: <http://ontologi.es/doap-changeset#> .
@prefix doap: <http://usefulinc.com/ns/doap#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
<http://lv2plug.in/ns/ext/atom>
@@ -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 <q>Objects</q>. 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
+&lt;http://lexvo.org/id/iso639-3/LANG&gt; or
+&lt;http://lexvo.org/id/iso639-1/LANG&gt; 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 <q>Hello</q> 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 <q>key</q> is the <q>predicate</q>
+and the <q>value</q> 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 <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.
+
+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 <code>id</code> 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
+ &lt;plugin&gt;
+ 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
+<q>supports</q> an Atom type, wherever that may be useful. It applies
+<q>recursively</q> 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
+ &lt;plugin&gt;
+ 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 @@
<util.h> ,
<forge.h> ,
<atom.meta.ttl> ;
- lv2:documentation """
-
-<p>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 <q>Objects</q>. Since Atoms are POD, they can be easily copied
-(e.g. using <code>memcpy</code>) anywhere and are suitable for use in real-time
-code.</p>
-
-<p>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.</p>
-
-<p>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.</p>
-
-<h3>Serialisation</h3>
-
-<p>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.</p>
-
-<h3>Custom Atom Types</h3>
-
-<p>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 <code>struct</code> 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.</p>
-""" .
+ 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 """
-<p>Abstract base class for all atoms. An LV2_Atom has a 32-bit
-<code>size</code> and <code>type</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 pass through, or ignore, 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).</p>
-
-<p>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>
-""" .
+ 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 """
-<p>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.</p>
-
-<p>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.:</p>
-
-<pre class="turtle-code">
-[] eg:someChunk "vu/erQ=="^^xsd:base64Binary .
-</pre>
-""" .
+ 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 """
-<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 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.</p>
-""" .
+ owl:onDatatype xsd:string .
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 rdfs: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
-&lt;http://lexvo.org/id/iso639-3/LANG&gt; or
-&lt;http://lexvo.org/id/iso639-1/LANG&gt; where LANG is a 3-character ISO 693-3
-language code, or a 2-character ISO 693-1 language code, respectively.</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->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
-}
-</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->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
-}
-</pre>
-""" .
+ 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 """
-<p>A local file path.</p>
-
-<p>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.</p>
-
-<p>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.</p>
-""" .
+ 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 """
-<p>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.</p>
-
-<p>This is not strictly a URI, since UTF-8 is allowed. Escaping and related
-issues are the host's responsibility.</p>
-""" .
+ 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 """
-<p>An unsigned 32-bit integer mapped from a URI (e.g. with LV2_URID_Map).</p>
-""" .
+ 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 """
-<p>A homogeneous series of atom bodies with equivalent type and size.</p>
-
-<p>An LV2_Atom_Vector is a 32-bit <code>child_size</code> and
-<code>child_type</code> followed by <code>size / child_size</code> atom
-bodies.</p>
-
-<p>For example, an atom:Vector containing 42 elements of type atom:Float:</p>
-<pre class="c-code">
-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];
-};
-</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>child_type</code>.</p>
-
-<p>If serialised to RDF, a Vector SHOULD have the form:</p>
-
-<pre class="turtle-code">
-eg:someVector
- a atom:Vector ;
- atom:childType atom:Int ;
- rdf:value (
- "1"^^xsd:int
- "2"^^xsd:int
- "3"^^xsd:int
- "4"^^xsd:int
- ) .
-</pre>
-""" .
+ 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 """
-<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>
-
-<p>If serialised to RDF, a Tuple SHOULD have the form:</p>
-
-<pre class="turtle-code">
-eg:someVector
- a atom:Tuple ;
- rdf:value (
- "1"^^xsd:int
- "3.5"^^xsd:float
- "etc"
- ) .
-</pre>
-
-""" .
+ 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 """
-<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>
-
-<p>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.:</p>
-
-<pre class="turtle-code">
-eg:someProperty
- rdf:predicate eg:theKey ;
- rdf:object eg:theValue .
-</pre>
-""" .
+ 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 """
-<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 body has a uint32_t <code>id</code> and
-<code>type</code>, 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.</p>
-
-<p>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.</p>
-
-<p>When serialised to RDF, an Object is represented as a resource, e.g.:</p>
-
-<pre class="turtle-code">
-eg:someObject
- eg:firstPropertyKey "first property value" ;
- eg:secondPropertyKey "first loser" ;
- eg:andSoOn "and so on" .
-</pre>
-""" .
+ 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 """
-<p>This class is deprecated. Use atom:Object instead.</p>
-
-<p>An atom:Object where the <code>id</code> field is a URID, i.e. an Object
-with a URI.</p>
-""" .
+ 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 """
-<p>This class is deprecated. Use atom:Object with ID 0 instead.</p>
-
-<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:cType "LV2_Atom_Object" .
atom:Sound
a rdfs:Class ;
rdfs:subClassOf atom:Vector ;
rdfs:label "Sound" ;
- atom:cType "LV2_Atom_Sound" ;
- lv2:documentation """
-<p>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.</p>
-""" .
+ 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 """
-<p>Time stamp in audio frames. Typically used for events.</p>
-""" .
+ 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 """
-<p>Time stamp in beats. Typically used for events.</p>
-""" .
+ rdfs:comment "A time stamp in beats." .
atom:Event
a rdfs:Class ;
rdfs:label "Event" ;
atom:cType "LV2_Atom_Event" ;
- lv2:documentation """
-<p>An atom with a time stamp prefix, typically an element of an atom:Sequence.
-Note this is not an Atom type.</p>
-""" .
+ 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 """
-<p>A sequence of atom:Event, i.e. a series of time-stamped Atoms.</p>
-
-<p>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.</p>
-
-<p>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.:</p>
-
-<pre class="turtle-code">
-eg:someSequence
- a atom:Sequence ;
- rdf:value (
- [
- atom:frameTime 1 ;
- rdf:value "901A01"^^midi:MidiEvent
- ] [
- atom:frameTime 3 ;
- rdf:value "902B02"^^midi:MidiEvent
- ]
- ) .
-</pre>
-""" .
+ rdfs:comment "A sequence of events." .
atom:AtomPort
a rdfs:Class ;
rdfs:subClassOf lv2:Port ;
rdfs:label "Atom Port" ;
- lv2:documentation """
-<p>A port which contains an atom:Atom. Ports of this type are connected to an
-LV2_Atom with a type specified by atom:bufferType.</p>
-
-<p>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().</p>
-""" .
+ 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 """
-<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">
-&lt;plugin&gt;
- lv2:port [
- a lv2:InputPort , atom:AtomPort ;
- atom:bufferType atom:Double ;
- ] .
-</pre>
-
-<p>This property only describes the types a port may be <em>directly</em>
-connected to. It says nothing about the expected contents of containers. For
-that, use atom:supports.</p>
-""" .
+ 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 """
-<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
-expected by a port. For example, a port that receives MIDI events is described
-like so:</p>
-
-<pre class="turtle-code">
-&lt;plugin&gt;
- lv2:port [
- a lv2:InputPort , atom:AtomPort ;
- atom:bufferType atom:Sequence ;
- atom:supports midi:MidiEvent ;
- ] .
-</pre>
-""" .
+ rdfs:comment "A supported atom type." ;
+ rdfs:range rdfs:Class .
atom:eventTransfer
a ui:PortProtocol ;
rdfs:label "event transfer" ;
- lv2:documentation """
-<p>Transfer of individual events in a port buffer. Useful as the
-<code>format</code> for a LV2UI_Write_Function.</p>
-
-<p>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.</p>
-""" .
+ rdfs:comment "A port protocol for transferring events." .
atom:atomTransfer
a ui:PortProtocol ;
rdfs:label "atom transfer" ;
- lv2:documentation """
-<p>Transfer of the complete atom in a port buffer. Useful as the
-<code>format</code> for a LV2UI_Write_Function.</p>
-
-<p>This protocol applies to atom ports. The host must transfer the complete
-atom contained in the port, including header.</p>
-""" .
+ rdfs:comment "A port protocol for transferring atoms." .