From 21d16ed2e53601f8a26f378b3274a207a9426b12 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 27 Jan 2013 21:18:10 +0000 Subject: Improve atom documentation. --- lv2/lv2plug.in/ns/ext/atom/atom.ttl | 80 ++++++++++++++++------------ lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl | 2 + 2 files changed, 47 insertions(+), 35 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext/atom') diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl index 725d9ff..c222ebf 100644 --- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl +++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl @@ -14,43 +14,53 @@ , ; lv2:documentation """ -

This specification defines a generic container for data, called an -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.

- -

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 +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.

+ +

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 struct type). New binary formats are an -implementation burden which harms interoperabilty, and should only be defined -where absolutely necessary.

- -

Implementing this extension requires a facility for mapping URIs to -integers, such as the LV2 URID extension.

-

Serialisation

-

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.

+ +

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 atom:Tuple or atom: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.

""" . atom:cType @@ -239,11 +249,11 @@ atom:Path

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.

+query, or fragment. In particular, 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.

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