From 21d16ed2e53601f8a26f378b3274a207a9426b12 Mon Sep 17 00:00:00 2001
From: David Robillard This specification defines a generic container for data, called an
- The purpose of Atoms is to allow implementations that process and/or
-transmit data to be independent of that data's type. For example, plugins that
-mutually understand a type can be used together in a host that does not
-understand that type, because the host's required facilities are generic.
-Similarly, plugins (such as routers, delays, or data structures) can
-meaningfully process atoms of a type unknown to them. This specification defines a simple generic data container, called an
+ Atoms are not limited to the types defined here, but allow implementations
+to work with any type of POD data at all. This is possible because Atom types
+are URIs, but mapped to integers using the LV2
+URID extension for performance reasons. Since atoms are simple to copy,
+communication of any atom is simple to implement 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 can and should be used anywhere values of various types must be stored
or transmitted. The port type atom:AtomPort can be used to transmit atoms via
-ports. The atom:Sequence type in an atom:AtomPort replaces the LV2 event extension. The types defined in this extension should be powerful enough to express
-almost any structure. Implementations SHOULD build structures out of the types
-provided here, rather than define new binary formats (e.g. use atom:Object
-rather than a new C Implementing this extension requires a facility for mapping URIs to
-integers, such as the LV2 URID extension. An Atom type primarily defines a binary format (i.e. a C data type) for use
-at runtime. However, each Atom type also has a standard serialisation format
-which SHOULD be used wherever an atom needs to be expressed as a string or in
-Turtle. Thus, this specification not only defines binary data types for
-plugins to use, but a complete data model with a portable RDF-compatible
-serialisation. This is useful for inter-process communication as well as
-saving state. 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. 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 atom:Tuple or atom:Object rather than
+a new C A local file path. A Path is a URI reference with only a path component: no scheme, authority,
-query, or fragment. Thus, 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.Atom
, and several basic Atom types which can be used to express
-structured data. An atom:Atom is (with one exception) Plain Old Data (POD),
-which means it can be copied generically (e.g. using a simple
-memcpy
), and is suitable for use in real-time code.Atom
. An atom:Atom can contain simple primitive types like integers,
+floating point numbers, and strings; as well as structured data like lists and
+dictionary-like Objects
. An Atom is, with one exception, Plain Old Data
+(POD), meaning it can be easily copied (e.g. using memcpy
) and is
+suitable for use in real-time code.struct
type). New binary formats are an
-implementation burden which harms interoperabilty, and should only be defined
-where absolutely necessary.Serialisation
-Custom Atom Types
+
+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.
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 diff --git a/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl b/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl index ca33803..db52e54 100644 --- a/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl +++ b/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl @@ -19,6 +19,8 @@ rdfs:label "Fix lv2_atom_sequence_end()." ] , [ rdfs:label "Remove atom:stringType in favour of owl:onDatatype so generic tools can understand and validate atom literals." + ] , [ + rdfs:label "Improve atom documentation." ] ] ] , [ -- cgit v1.2.1