aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/ext/atom/atom.ttl
diff options
context:
space:
mode:
Diffstat (limited to 'lv2/lv2plug.in/ns/ext/atom/atom.ttl')
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/atom.ttl45
1 files changed, 20 insertions, 25 deletions
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
index 301f416..113cfe8 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
@@ -14,31 +14,26 @@
<forge.h> ,
<lv2-atom.doap.ttl> ;
lv2:documentation """
-<p>This specification defines a simple generic data container, called an
-<q>Atom</q>. An atom:Atom can contain simple primitive types like integers,
+
+<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>. An Atom is, with one exception, Plain Old Data
-(POD), meaning it can be easily copied (e.g. using <code>memcpy</code>) and is
-suitable for use in real-time code.</p>
-
-<p>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 <a href="../urid/urid.html">LV2
-URID</a> extension for performance reasons.</p>
-
-<p>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.</p>
-
-<p>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. An atom:AtomPort that contains an atom:Sequence can be used for sample
-accurate event communication, such as MIDI, and replaces the earlier <a
-href="../event/event.html">LV2 event</a> extension.</p>
+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>
@@ -54,7 +49,7 @@ in plugin data files.</p>
<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 atom:Tuple or atom:Object rather than
+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