atom
type: Specification
name: LV2 Atom
shortdesc: A generic value container and several data types.
release:
  revision: 0.2
  created: 2011-11-05
maintainer: David Robillard
documentation: This extension defines a generic format for a typed piece of data, called an lv2:Atom (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 memcpy). 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. An Atom can be trivially constructed in-place from an Event as defined by the LV2 Event 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. Atoms (the start of the LV2_Atom header) MUST be 32-bit aligned. Atoms can be communicated in many ways. Since an Atom is the payload of an Event, an EventPort 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: atom:ValuePort and atom:MessagePort, which both have the same buffer format but different semantics (with respect to how the run() callback interprets the Atom). Implementing this extension requires a facility for mapping URIs to integers, such as the LV2 URID extension.

Atom
type: Class
C type: LV2_Atom
documentation: Abstract base class for all atoms. An LV2_Atom has a 32-bit type and size followed by a body of size bytes. All concrete Atom types (subclasses of this class) MUST define a precise binary layout for body. The type field is the URI of a subclass of Atom mapped to an integer using the URI Map extension's LV2_URI_Map_Feature::uri_to_id() with map = "http://lv2plug.in/ns/ext/event". If a plugin or host does not understand type, that atom SHOULD be gracefully ignored (or copied if it does not have type 0). 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, actual specification of how references are used is left to another extension.

String
type: Class
subclass of: Atom
C type: LV2_Atom_String
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 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.

String Literal
type: Class
subclass of: Atom
C type: LV2_Atom_Literal
documentation: A UTF-8 encoded string literal, with an optional datatype or language. This type is compatible with rdf: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/term/LANG> where LANG is an ISO 693-2 or ISO 693-3 language code. For compatibility, a Literal MUST have either 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->type = map(expand("atom:Literal")); lit->size = 14; lit->datatype = 0; lit->lang = map("http://lexvo.org/id/term/en"); memcpy(lit->str, "Hello", sizeof("Hello")); // Assumes enough space } or a Turtle string: void set_to_turtle_string(LV2_Atom_Literal* lit, const char* ttl) { lit->type = map(expand("atom:Literal")); lit->size = 64; lit->datatype = map("http://www.w3.org/2008/turtle#turtle"); lit->lang = 0; memcpy(lit->str, ttl, strlen(ttl) + 1); // Assumes enough space }

Integer ID mapped from a URI
type: Class
subclass of: Atom
C type: LV2_Atom_ID
documentation: An unsigned 32-bit integer mapped from a URI using the URI Map extension's LV2_URI_Map_Feature::uri_to_id() with map = NULL.

Integer ID for a blank node
type: Class
subclass of: Atom
C type: LV2_Atom_ID
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 a URID, and can not be mapped to/from a URI.

Vector
type: Class
subclass of: Atom
C type: LV2_Atom_Vector
documentation: A homogeneous sequence of atoms with equivalent type and size. An LV2_Atom_Vector is a 32-bit elem_count and elem_type followed by elem_count atom bodies of type elem_type. The element type must be a fixed size atom:Atom type, i.e. the size of each element is the vector's size / elem_count. For example, an atom:Vector containing 42 elements of type atom:Float: struct VectorOf42Floats { uint32_t type; // map(expand("atom:Vector")) uint32_t size; // sizeof(LV2_Atom_Vector) + (42 * sizeof(float); uint32_t elem_count; // 42 uint32_t elem_type; // map(expand("atom:Float")) float elems[32]; }; Note that it is possible to construct a valid Atom for each element of the vector, even by an implementation which does not understand elem_type.

Tuple
type: Class
subclass of: Atom
documentation: A sequence of lv2:Atom with varying type and size. The body of a Tuple is simply a sequence of complete atoms, each aligned to 32 bits.

Thing
type: Class
subclass of: Atom
C type: LV2_Thing
documentation: Abstract base class for a "Thing", i.e. an atom:Atom with a number of properties. An LV2_Object is an unsigned 32-bit integer context and id followed by a sequence of LV2_Atom_Property . The context is mapped using the URI Map extension's LV2_URI_Map_Feature::uri_to_id() with map = NULL, and may be 0 (the default context). Note this is an abstract class, i.e. no Atom can exist with type = uri_to_id(atom:Thing). An Object is either an atom:Resource or an atom:Blank, but the body 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.

Resource
type: Class
subclass of: Thing
C type: LV2_Thing
documentation: An atom:Thing where id is the URI of the resource mapped to an atom:URID.

Blank
type: Class
subclass of: Thing
C type: LV2_Thing
documentation: An atom:Thing where id 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, id is NOT an ID.

Message
type: Class
subclass of: Thing
C type: LV2_Thing
documentation: A atom:Thing where id is a message type ID. Conceptually, a Message is identical to a Blank, but is a distinct type with a single type field to allow simple and fast dispatch by handling code. A Message may be serialised as a Blank by adding an rdf:type property with the value id unmapped to a URI.

Event
type: Class
C type: LV2_Atom_Event
documentation: An atom with a time stamp header prepended, typically for sample accurate transmission via LV2 ports. See struct LV2_Atom_Event.

Bang (activity) (size = 0)
type: Class
subclass of: Atom

Number (abstract class).
type: Class
subclass of: Atom

Signed 32-bit integer
type: Class
subclass of: Number (abstract class).
C type: LV2_Atom_Int32

Signed 64-bit integer
type: Class
subclass of: Number (abstract class).
C type: LV2_Atom_Int64

An atom:Int32 where 0 is false and all other values true
type: Class
subclass of: Atom
C type: LV2_Atom_Int32

32-bit IEEE-754 floating point number
type: Class
subclass of: Number (abstract class).
C type: LV2_Atom_Float

64-bit IEEE-754 floating point number
type: Class
subclass of: Number (abstract class).
C type: LV2_Atom_Double

Blob support
type: Feature
documentation: Support for dynamically allocated blobs. If a host supports this feature, it MUST pass a LV2_Feature with URI http://lv2plug.in/ns/ext/atom#blobSupport and data pointing to a LV2_Blob_Support.

Atom Port
type: Class
subclass of: Port
documentation: A port which contains an lv2:Atom. Ports of this type will be connected to a 32-bit aligned LV2_Atom immediately followed by size bytes of data. 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 atom:ValuePort or atom:MessagePort). 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 type = 0 and size = 0).

Value Port
type: Class
subclass of: Atom Port
documentation: An AtomPort that interprets its data as a persistent and time-independent "value". 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. 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. If a ValuePort contains a reference then the blob it refers to is constant; plugin MUST NOT modify the blob in any way. 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.

Message Port
type: Class
subclass of: Atom Port
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).

C type
type: Property
type: DatatypeProperty
domain: Class
range: string
comment: The identifier for a C type describing the in-memory representation of an instance of this class.

Event port
type: Class
subclass of: Port
documentation: A port used for communicating time-stamped atoms in the audio context. Ports of this type are connected to an LV2_Atom_Buffer, which contains a flat time-stamped sequence of atom:Event. This port type is intended as a simpler and atom compatible successor to ev:EventPort.

supports
type: Property
domain: Port
range: Atom
documentation: Indicates that a Port supports a certain atom:Atom 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.