From 68a4dc89f5e00aa6e2780f4f96011b92961b7a80 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Tue, 25 Nov 2014 00:23:48 -0500 Subject: Single-page API documentation with unified style. --- lv2/lv2plug.in/ns/ext/atom/atom.h | 12 ++++++++-- lv2/lv2plug.in/ns/ext/atom/atom.ttl | 45 +++++++++++++++++-------------------- lv2/lv2plug.in/ns/ext/atom/forge.h | 7 ++++++ lv2/lv2plug.in/ns/ext/atom/util.h | 7 ++++++ 4 files changed, 44 insertions(+), 27 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext/atom') diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.h b/lv2/lv2plug.in/ns/ext/atom/atom.h index 3f0195b..55fffe2 100644 --- a/lv2/lv2plug.in/ns/ext/atom/atom.h +++ b/lv2/lv2plug.in/ns/ext/atom/atom.h @@ -15,8 +15,12 @@ */ /** - @file atom.h C header for the LV2 Atom extension - . + @defgroup atom Atom + + A generic value container and several data types, see + for details. + + @{ */ #ifndef LV2_ATOM_H @@ -239,6 +243,10 @@ typedef struct { LV2_Atom_Sequence_Body body; /**< Body. */ } LV2_Atom_Sequence; +/** + @} +*/ + #ifdef __cplusplus } /* extern "C" */ #endif 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 @@ , ; lv2:documentation """ -

This specification defines a simple generic data container, called an -Atom. An atom:Atom can contain simple primitive types like integers, + +

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. 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. An atom:AtomPort that contains an atom:Sequence can be used for sample -accurate event communication, such as MIDI, and replaces the earlier LV2 event extension.

+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

@@ -54,7 +49,7 @@ 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 +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 diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h index 3492712..0ce05dc 100644 --- a/lv2/lv2plug.in/ns/ext/atom/forge.h +++ b/lv2/lv2plug.in/ns/ext/atom/forge.h @@ -39,6 +39,12 @@ This header is non-normative, it is provided for convenience. */ +/** + @defgroup forge Forge + @ingroup atom + @{ +*/ + #ifndef LV2_ATOM_FORGE_H #define LV2_ATOM_FORGE_H @@ -687,6 +693,7 @@ lv2_atom_forge_beat_time(LV2_Atom_Forge* forge, double beats) /** @} + @} */ #if defined(__clang__) diff --git a/lv2/lv2plug.in/ns/ext/atom/util.h b/lv2/lv2plug.in/ns/ext/atom/util.h index 1340024..52cdf93 100644 --- a/lv2/lv2plug.in/ns/ext/atom/util.h +++ b/lv2/lv2plug.in/ns/ext/atom/util.h @@ -22,6 +22,12 @@ This header is non-normative, it is provided for convenience. */ +/** + @defgroup util Utilities + @ingroup atom + @{ +*/ + #ifndef LV2_ATOM_UTIL_H #define LV2_ATOM_UTIL_H @@ -437,6 +443,7 @@ lv2_atom_object_get(const LV2_Atom_Object* object, ...) /** @} + @} */ #ifdef __cplusplus -- cgit v1.2.1