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.