aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/atom/atom.ttl
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2018-09-22 20:38:01 +0200
committerDavid Robillard <d@drobilla.net>2018-09-22 20:38:58 +0200
commit4db67120efca2d4c200d2e1ba5cf3d7b97cab97e (patch)
tree793630dd2a17b78d805dc4bc5cd50fbdd0ace3bd /lv2/atom/atom.ttl
parent160ecb9601c9687a1093e124e936dcbd78aef43c (diff)
downloadlv2-4db67120efca2d4c200d2e1ba5cf3d7b97cab97e.tar.xz
Install standard headers to simpler include paths
Diffstat (limited to 'lv2/atom/atom.ttl')
-rw-r--r--lv2/atom/atom.ttl602
1 files changed, 602 insertions, 0 deletions
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: <http://lv2plug.in/ns/ext/atom#> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix ui: <http://lv2plug.in/ns/extensions/ui#> .
+@prefix units: <http://lv2plug.in/ns/extensions/units#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<http://lv2plug.in/ns/ext/atom>
+ a owl:Ontology ;
+ rdfs:seeAlso <atom.h> ,
+ <util.h> ,
+ <forge.h> ,
+ <lv2-atom.doap.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>
+""" .
+
+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 """
+<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>
+""" .
+
+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>
+""" .
+
+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 """
+<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>
+""" .
+
+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>
+""" .
+
+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>
+""" .
+
+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>
+""" .
+
+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>
+""" .
+
+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>
+""" .
+
+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>
+
+""" .
+
+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>
+""" .
+
+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>
+""" .
+
+atom:Resource
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Object ;
+ rdfs:label "Resource" ;
+ 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:Blank
+ a rdfs:Class ;
+ rdfs:subClassOf atom:Object ;
+ rdfs:label "Blank" ;
+ 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: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>
+""" .
+
+atom:frameTime
+ a rdf:Property ,
+ owl:DatatypeProperty ,
+ owl:FunctionalProperty ;
+ rdfs:range xsd:decimal ;
+ rdfs:label "frame time" ;
+ lv2:documentation """
+<p>Time stamp in audio frames. Typically used for events.</p>
+""" .
+
+atom:beatTime
+ a rdf:Property ,
+ owl:DatatypeProperty ,
+ owl:FunctionalProperty ;
+ rdfs:range xsd:decimal ;
+ rdfs:label "beat time" ;
+ lv2:documentation """
+<p>Time stamp in beats. Typically used for events.</p>
+""" .
+
+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>
+""" .
+
+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>
+""" .
+
+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>
+""" .
+
+atom:bufferType
+ a rdf:Property ,
+ owl:ObjectProperty ;
+ 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>
+""" .
+
+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 """
+<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>
+""" .
+
+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>
+""" .
+
+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>
+""" .