# LV2 Atom Extension # Copyright 2007-2011 David Robillard <d@drobilla.net> # # Permission to use, copy, modify, and/or distribute this software for any # purpose with or without fee is hereby granted, provided that the above # copyright notice and this permission notice appear in all copies. # # THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. @prefix atom: <http://lv2plug.in/ns/ext/atom#> . @prefix doap: <http://usefulinc.com/ns/doap#> . @prefix foaf: <http://xmlns.com/foaf/0.1/> . @prefix lv2: <http://lv2plug.in/ns/lv2core#> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . @prefix xsd: <http://www.w3.org/2001/XMLSchema#> . <http://lv2plug.in/ns/ext/atom> a lv2:Specification ; doap:name "LV2 Atom" ; doap:release [ doap:revision "0.1" ; doap:created "2011-04-05" ] ; doap:maintainer [ a foaf:Person ; foaf:name "David Robillard" ; foaf:homepage <http://drobilla.net/> ; rdfs:seeAlso <http://drobilla.net/drobilla.rdf> ] ; lv2:documentation """ <p>This extension defines a generic format for a typed piece of data, called an "<a href="#Atom">Atom</a>" (e.g. integers, strings, buffers, data structures, etc). Atoms allow LV2 plugins and hosts to communicate, process, serialise, and store values of any type via a generic mechanism (e.g. LV2 ports, events, disk, shared memory, network). Atoms are, with one exception, Plain Old Data (POD) and may be safely copied (e.g. with a simple call to <code>memcpy</code>).</p> <p>Since Atom communication can be implemented generically, plugins that understand some type can be used together in a host that does not understand that type, and plugins (e.g. routers, delays) can process atoms of unknown type.</p> <p>An Atom can be trivially constructed in-place from an <a href="http://lv2plug.in/ns/ext/event#Event">Event</a> as defined by the <a href="http://lv2plug.in/ns/ext/event">LV2 Event</a> extension. In other words, an Event is simply an Atom with a time stamp header. Atoms SHOULD be used anywhere a "value" needs to be stored or communicated, to allow implementations to be polymorphic and extensible.</p> <p>Atoms (the start of the LV2_Atom header) MUST be 32-bit aligned.</p> <p>Atoms can be communicated in many ways. Since an Atom is the payload of an Event, an <a href="http://lv2plug.in/ns/ext/event#EventPort">EventPort</a> can be used for communicating Atoms in realtime with sub-sample time stamp accuracy. This extension also defines two port types for connecting directly to a single Atom: <a href="#ValuePort">ValuePort</a> and <a href="#MessagePort" >MessagePort</a>, which both have the same buffer format but different semantics (with respect to how the run() callback interprets the Atom).</p> <p>This extension requires the host to support the <a href="http://lv2plug.in/ns/ext/uri-map">LV2 URI Map</a> extension.</p> """ . atom:Atom a rdfs:Class ; rdfs:label "Atom" ; lv2:documentation """ <p>Abstract base class for all atoms. An LV2_Atom has a 16-bit <code>type</code> and <code>size</code> followed by a <code>body</code> of <code>size</code> bytes.</p> <p>All concrete Atom types (subclasses of this class) MUST define a precise binary layout for <code>body</code>.</p> <p>The <code>type</code> field is the URI of a subclass of Atom mapped to an integer using the <a href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's LV2_URI_Map_Feature::uri_to_id() with <code>map = "http://lv2plug.in/ns/ext/event"</code>. If a plugin or host does not understand <code>type</code>, that atom SHOULD be gracefully ignored (or copied if it does not have type 0).</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, actual specification of how references are used is left to another extension.</p> """ . atom:String a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "String" ; lv2:documentation """ <p>A UTF-8 encoded string.</p> <p>The body of an 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 can be used for free-form strings, but in most cases it is better to use atom:Literal since this supports a language tag or datatype. Implementations SHOULD NOT use atom:String unless translating the string does not make sense and the string has no meaningful datatype.</p> """ . atom:Literal a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "String Literal" ; lv2:documentation """ <p>A UTF-8 encoded string literal, with an optional language tag or datatype.</p> <p>This type is compatible with an RDF literal and is capable of expressing a string in any language, or a value of any type. An LV2_Atom_Literal has an <a href="#ID">ID</a> <code>lang</code> and <code>datatype</code> followed by the string data in UTF-8 encoding. The length of the string data in bytes is <code>size - (2 * sizeof(uint32_t))</code>, including the terminating NULL character. The <code>lang</code> field SHOULD be a URI of the form <http://lexvo.org/id/term/LANG> where LANG is an <a href="http://www.loc.gov/standards/iso639-2/">ISO 693-2</a> or <a href="http://www.loc.gov/standards/iso639-2/">ISO 693-3</a> language code.</p> <p>For example, "Hello" in English:</p> <pre class="c-code"> struct LV2_Atom { uint16_t type = uri_to_id(atom:Literal); uint16_t size = 14; } uint32_t datatype = 0; uint32_t lang = uri_to_id("http://lexvo.org/id/term/en"); char str[] = "Hello"; </pre> and French: <pre class="c-code"> struct LV2_Atom { uint16_t type = uri_to_id(atom:Literal); uint16_t size = 16; } uint32_t datatype = 0; uint32_t lang = uri_to_id("http://lexvo.org/id/term/fr"); char str[] = "Bonjour"; </pre> <p>or a Turtle string:</p> <pre class="c-code"> struct LV2_Atom { uint16_t type = uri_to_id(atom:Literal); uint16_t size = 64; } uint32_t datatype = uri_to_id("http://www.w3.org/2008/turtle#turtle"); uint32_t lang = 0; char str[] = "<http://example.org/foo> a <http://example.org/Thing> ." </pre> """ . atom:ID a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Integer ID mapped from a URI" ; lv2:documentation """ An unsigned 32-bit integer mapped from a URI using the <a href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's LV2_URI_Map_Feature::uri_to_id() with <code>map = NULL</code>. """ . atom:BlankID a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Integer ID for a blank node" ; lv2:documentation """ An unsigned 32-bit integer identifier for a blank node. A BlankID is only meaningful within a limited scope (e.g. the Atom in which it appears), and MUST NOT be used as a global identifier. In particular, a BlankID is NOT an ID, and can not be mapped to/from a URI. """ . atom:Vector a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Vector" ; lv2:documentation """ <p>A homogeneous sequence of atoms with equivalent type and size.</p> <p>An LV2_Atom_Vector is a 16-bit <code>elem_count</code> and <code>elem_type</code> followed by <code>elem_count</code> atom bodies of type <code>elem_type</code>. The element type must be a fixed size <a href="#Atom">Atom</a> type, i.e. the size of each element is the vector's <code>size / elem_count</code>.</p> <p>For example, an atom:Vector containing 42 elements of type atom:Float looks like this in memory:</p> <pre class="c-code"> struct LV2_Atom { uint16_t type = uri_to_id(atom:Vector); uint16_t size = sizeof(LV2_Atom) + sizeof(LV2_Atom_Vector) + (42 * sizeof(float); } struct LV2_Vector { uint16_t elem_count = 42; uint16_t elem_type = uri_to_id(atom:Float); } float elem_00; float elem_01; ... float elem_41; </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>elem_type</code>.</p> <p>A Vector header is 64-bits, thus the first element of a Vector is 64-bit aligned if the Vector itself is 64-bit aligned.</p> """ . atom:Tuple a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Tuple" ; lv2:documentation """ <p>A sequence of <a href="#Atom">atoms</a> with varying <code>type</code> and <code>size</code>.</p> <p>The body of a Tuple is simply a sequence of complete atoms, each aligned to 32 bits.</p> """ . atom:Property a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Property of an Object" ; lv2:documentation """ A single property of some <a href="#Object">Object</a>. An LV2_Atom_Property has an <a href="#ID">ID</a> <code>key</code> and <a href="#Atom">Atom</a> <code>value</code>. """ . atom:Object a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Object" ; lv2:documentation """ <p>Abstract base class for an "Object", i.e. an <a href="#Atom">Atom</a> with a number of <a href="#Property">properties</a>. An LV2_Object is an unsigned 32-bit integer <code>context</code> and <code>id</code> followed by a sequence of LV2_Atom_Property .</p> <p>The <code>context</code> is mapped using the <a href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's LV2_URI_Map_Feature::uri_to_id() with <code>map = NULL</code>, and may be 0 (the default context).</p> <p>Note this is an abstract class, i.e. no Atom can exist with <code>type = uri_to_id(atom:Object)</code>. An Object is either a <a href="#Resource">Resource</a> or a <a href="#Blank">Blank</a>, but the <code>body</code> always has the same binary format, LV2_Object. Thus, both named and anonymous objects can be handled with common code using only a 64-bit header for both.</p> """ . atom:Resource a rdfs:Class ; rdfs:subClassOf atom:Object ; lv2:documentation """ An <a href="#Object">Object</a> where <code>id</code> is the URI of the resource mapped to an <a href="#ID">ID</a>. """ . atom:Blank a rdfs:Class ; rdfs:subClassOf atom:Object ; lv2:documentation """ An <a href="#Object">Object</a> where <code>id</code> is the blank node ID of the object, which is only meaningful within a certain limited scope (e.g. the container of the Blank) and MUST NOT be used as a global ID. In particular, <code>id</code> is NOT an <a href="ID">ID</a>. """ . atom:Model a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Model" ; lv2:documentation """ A description of a set of <a href="#Object">objects</a>. In memory, a Model is simply a sequence of objects. """ . atom:Event a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Event" ; lv2:documentation """ An atom with a time stamp header prepended, typically for sample accurate transmission via LV2 ports. See struct LV2_Atom_Event. """ . atom:MidiMessage a rdfs:Class ; rdfs:label "MIDI Message" ; rdfs:subClassOf atom:Atom ; lv2:documentation """ <p>A single raw MIDI message.</p> <p>This is a standard MIDI message, with the following restrictions to ease the burden on plugin authors:</p> <ul> <li>Running status is not allowed, every message must have its own status byte.</li> <li>Note On messages with velocity 0 are not allowed. These messages are equivalent to Note Off in standard MIDI streams, but here only proper Note Off messages are allowed.</li> <li>"Realtime messages" (status bytes 0xF8 to 0xFF) are allowed, but may not occur inside other messages like they can in standard MIDI streams.</li> </ul> """ . atom:Bang a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Bang (activity) (size = 0)" . atom:Byte a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Byte (<code>size = 1</code>)" . atom:Int32 a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Signed 32-bit integer" . atom:Int64 a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Signed 64-bit integer" . atom:Bool a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "Signed 32-bit integer where 0 is false" . atom:Float a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "32-bit IEEE-754 floating point number" . atom:Double a rdfs:Class ; rdfs:subClassOf atom:Atom ; rdfs:label "64-bit IEEE-754 floating point number" . atom:blobSupport a lv2:Feature ; rdfs:label "Blob support" ; lv2:documentation """ Support for dynamically allocated blobs. If a host supports this feature, it MUST pass a LV2_Feature with <code>URI</code> http://lv2plug.in/ns/ext/atom#blobSupport and <code>data</code> pointing to a LV2_Blob_Support. """ . atom:AtomPort a rdfs:Class ; rdfs:subClassOf lv2:Port ; rdfs:label "Atom Port" ; lv2:documentation """ <p>A port which contains an <a href="#Atom">Atom</a>. Ports of this type will be connected to a 32-bit aligned LV2_Atom immediately followed by <code>size</code> bytes of data.</p> <p>This is an abstract port type, i.e. a port MUST NOT only be an AtomPort, but must be a more descriptive type that is a subclass of AtomPort which defines the port's semantics (typically <a href="#ValuePort">ValuePort</a> or <a href="#MessagePort">MessagePort</a>).</p> <p>Before calling a method on the plugin that writes to an AtomPort output, the host MUST set the size of the Atom in that output to the amount of available memory immediately following the Atom header. The plugin MUST write a valid Atom to that port (leaving it untouched is illegal). If there is no reasonable value to write to the port, the plugin MUST write NULL (the Atom with both <code>type = 0</code> and <code>size = 0</code>).</p> """ . atom:ValuePort a rdfs:Class ; rdfs:subClassOf atom:AtomPort ; rdfs:label "Value Port" ; lv2:documentation """ An AtomPort that interprets its data as a persistent and time-independent "value". <ul> <li>If a plugin has fixed input values for all ports, all ValuePort outputs are also fixed regardless of the number of times the plugin is run.</li> <li>If a plugin has fixed input values for all ports except a ValuePort, each value V of that ValuePort corresponds to a single set of outputs for all ports.</li> <li>If a ValuePort contains a reference then the blob it refers to is constant; plugin MUST NOT modify the blob in any way.</li> </ul> Value ports can be thought of as purely functional ports: if a plugin callback has only value ports, then the plugin callback is a pure function. """ . atom:MessagePort a rdfs:Class ; rdfs:subClassOf atom:AtomPort ; rdfs:label "Message Port" ; rdfs:comment """ An AtomPort that "receives", "consumes", "executes", or "sends" its value. The Atom contained in a MessagePort is considered transient and/or time-dependent, and is only valid for a single run invocation. Unlike a ValuePort, a MessagePort may be used to manipulate internal plugin state. Intuitively, a MessagePort contains a "message" or "command" or "event" which is reacted to, NOT a "value" or "signal" (which is computed with). """ . atom:EventPort a rdfs:Class ; rdfs:label "Event port" ; rdfs:subClassOf lv2:Port ; lv2:documentation """ Ports of this type will be connected to an LV2_Atom_Event_Buffer. These ports contain a sequence of atom:Event (i.e. time stamped atoms). These ports are used to send and receive atoms in the audio context (i.e. LV2_Descriptor::run()), and are intended as a simpler, more generic, and atom compatible successor to <a href="http://lv2plug.in/ns/ext/event#EventPort">ev:EventPort</a>. """ . atom:supports a rdf:Property ; rdfs:domain lv2:Port ; rdfs:range atom:Atom ; rdfs:label "supports" ; lv2:documentation """ Indicates that a Port supports a certain <a href="#Atom">Atom</a> type. This is distinct from the port type - e.g. the port type ValuePort can hold atoms with many different types. This property is used to describe which Atom types a Port expects to receive or send. """ .