aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/ext/atom
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-02-19 04:18:53 +0000
committerDavid Robillard <d@drobilla.net>2012-02-19 04:18:53 +0000
commitab74953ba3f8ff649ff1c53536a7b649763c677d (patch)
tree9f815f7c680f887dc11e8acfb25d8acdf6037690 /lv2/lv2plug.in/ns/ext/atom
parent35a3120672f78c13a58ea5c947becd5bbd362caf (diff)
downloadlv2-ab74953ba3f8ff649ff1c53536a7b649763c677d.tar.xz
Clean up documentation.
Improve object query function names.
Diffstat (limited to 'lv2/lv2plug.in/ns/ext/atom')
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/atom-test.c34
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/atom.h35
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/atom.ttl6
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/forge.h21
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/manifest.ttl3
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/util.h26
6 files changed, 62 insertions, 63 deletions
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom-test.c b/lv2/lv2plug.in/ns/ext/atom/atom-test.c
index c81f581..7375a17 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom-test.c
+++ b/lv2/lv2plug.in/ns/ext/atom/atom-test.c
@@ -309,7 +309,7 @@ main()
LV2_OBJECT_QUERY_END
};
- unsigned n_matches = lv2_object_get((LV2_Atom_Object*)obj, q);
+ unsigned n_matches = lv2_object_query((LV2_Atom_Object*)obj, q);
for (int i = 0; i < 2; ++i) {
if (n_matches != n_props) {
return test_fail("Query failed, %u matches != %u\n",
@@ -342,22 +342,22 @@ main()
return test_fail("Bad match sequence\n");
}
memset(&matches, 0, sizeof(matches));
- n_matches = lv2_object_getv((LV2_Atom_Object*)obj,
- eg_one, &matches.one,
- eg_two, &matches.two,
- eg_three, &matches.three,
- eg_four, &matches.four,
- eg_true, &matches.affirmative,
- eg_false, &matches.negative,
- eg_path, &matches.path,
- eg_uri, &matches.uri,
- eg_urid, &matches.urid,
- eg_string, &matches.string,
- eg_literal, &matches.literal,
- eg_tuple, &matches.tuple,
- eg_vector, &matches.vector,
- eg_seq, &matches.seq,
- 0);
+ n_matches = lv2_object_get((LV2_Atom_Object*)obj,
+ eg_one, &matches.one,
+ eg_two, &matches.two,
+ eg_three, &matches.three,
+ eg_four, &matches.four,
+ eg_true, &matches.affirmative,
+ eg_false, &matches.negative,
+ eg_path, &matches.path,
+ eg_uri, &matches.uri,
+ eg_urid, &matches.urid,
+ eg_string, &matches.string,
+ eg_literal, &matches.literal,
+ eg_tuple, &matches.tuple,
+ eg_vector, &matches.vector,
+ eg_seq, &matches.seq,
+ 0);
}
printf("All tests passed.\n");
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.h b/lv2/lv2plug.in/ns/ext/atom/atom.h
index a8ec72d..791e18c 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.h
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.h
@@ -17,14 +17,14 @@
/**
@file atom.h C header for the LV2 Atom extension
<http://lv2plug.in/ns/ext/atom>.
-
- This header describes the binary layout of various types defined in the
- atom extension.
*/
#ifndef LV2_ATOM_H
#define LV2_ATOM_H
+#include <stdint.h>
+#include <stddef.h>
+
#define LV2_ATOM_URI "http://lv2plug.in/ns/ext/atom"
#define LV2_ATOM__Atom LV2_ATOM_URI "#Atom"
@@ -60,9 +60,6 @@
#define LV2_ATOM_REFERENCE_TYPE 0
-#include <stdint.h>
-#include <stddef.h>
-
#ifdef __cplusplus
extern "C" {
#endif
@@ -72,7 +69,7 @@ typedef char lv2_atom_assert_double_fits_in_64_bits[
((sizeof(double) <= sizeof(uint64_t)) * 2) - 1];
/**
- Return a pointer to the contents of a variable-sized atom.
+ Return a pointer to the contents of an Atom.
@param type The type of the atom, e.g. LV2_Atom_String.
@param atom A variable-sized atom.
*/
@@ -90,26 +87,26 @@ typedef struct {
/** An atom:Int32 or atom:Bool. May be cast to LV2_Atom. */
typedef struct {
- LV2_Atom atom;
- int32_t value;
+ LV2_Atom atom; /**< Atom header. */
+ int32_t value; /**< Integer value. */
} LV2_Atom_Int32;
/** An atom:Int64. May be cast to LV2_Atom. */
typedef struct {
- LV2_Atom atom;
- int64_t value;
+ LV2_Atom atom; /**< Atom header. */
+ int64_t value; /**< Integer value. */
} LV2_Atom_Int64;
/** An atom:Float. May be cast to LV2_Atom. */
typedef struct {
- LV2_Atom atom;
- float value;
+ LV2_Atom atom; /**< Atom header. */
+ float value; /**< Floating point value. */
} LV2_Atom_Float;
/** An atom:Double. May be cast to LV2_Atom. */
typedef struct {
- LV2_Atom atom;
- double value;
+ LV2_Atom atom; /**< Atom header. */
+ double value; /**< Floating point value. */
} LV2_Atom_Double;
/** An atom:Bool. May be cast to LV2_Atom. */
@@ -130,8 +127,8 @@ typedef struct {
/** The complete header of an atom:Literal. */
typedef struct {
LV2_Atom atom; /**< Atom header. */
- uint32_t datatype; /**< The ID of the datatype of this literal. */
- uint32_t lang; /**< The ID of the language of this literal. */
+ uint32_t datatype; /**< Datatype URID. */
+ uint32_t lang; /**< Language URID. */
/* Contents (a null-terminated UTF-8 string) follow here. */
} LV2_Atom_Literal;
@@ -167,8 +164,8 @@ typedef struct {
/** The complete header of an atom:Object. */
typedef struct {
- LV2_Atom atom; /**< Atom header. */
- uint32_t id; /**< URID for atom:Resource, or blank ID for atom:Blank. */
+ LV2_Atom atom; /**< Atom header. */
+ uint32_t id; /**< URID (atom:Resource) or blank ID (atom:Blank). */
uint32_t otype; /**< Type URID (same as rdf:type, for fast dispatch). */
/* Contents (a series of property bodies) follow here. */
} LV2_Atom_Object;
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
index c3249ec..ce1aed2 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
@@ -30,8 +30,8 @@
rdfs:seeAlso <util.h> ,
<forge.h> ;
doap:release [
- doap:revision "0.4" ;
- doap:created "2012-02-07"
+ doap:revision "0.5" ;
+ doap:created "2012-02-18"
] ;
doap:maintainer [
a foaf:Person ;
@@ -523,4 +523,4 @@ atom:eventTransfer
atom:Sequence. The host must transfer each individual event to the recipient.
The format of the received data is an LV2_Atom, there is no timestamp
header.</p>
-""" . \ No newline at end of file
+""" .
diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h
index 52ba635..acfc6a8 100644
--- a/lv2/lv2plug.in/ns/ext/atom/forge.h
+++ b/lv2/lv2plug.in/ns/ext/atom/forge.h
@@ -17,20 +17,21 @@
/**
@file forge.h An API for constructing LV2 atoms.
- This file provides a simple API which can be used to create complex nested
- atoms by calling the provided functions to append atoms (or atom headers) in
- the correct order.
+ This file provides an API for constructing Atoms which makes it relatively
+ simple to build nested atoms of arbitrary complexity without requiring
+ dynamic memory allocation.
- The size of containers is automatically handled to any depth. All functions
- that start a container take a pointer to an uninitialised stack frame which
- will be initialised and must be popped when the container is finished.
+ The API is based on successively appending the appropriate pieces to build a
+ complete Atom. The size of containers is automatically updated. Functions
+ that begin a container return (via their frame argument) a stack frame which
+ must be popped when the container is finished.
- All output is written to a user-provided buffer, or sink function. Thus,
- this API can be used to create atoms on the stack, on the heap, in LV2 port
- buffers, or in a ringbuffer.
+ All output is written to a user-provided buffer or sink function. This
+ makes it popssible to create create atoms on the stack, on the heap, in LV2
+ port buffers, in a ringbuffer, or elsewhere, all using the same API.
This entire API is realtime safe if used with a buffer or a realtime safe
- sink, except lv2_atom_forge_init(), which is only realtime safe if the URI
+ sink, except lv2_atom_forge_init() which is only realtime safe if the URI
map function is.
Note these functions are all static inline, do not take their address.
diff --git a/lv2/lv2plug.in/ns/ext/atom/manifest.ttl b/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
index 37f0f58..9730981 100644
--- a/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
@@ -4,6 +4,5 @@
<http://lv2plug.in/ns/ext/atom>
a lv2:Specification ;
lv2:minorVersion 0 ;
- lv2:microVersion 4 ;
+ lv2:microVersion 5 ;
rdfs:seeAlso <atom.ttl> .
-
diff --git a/lv2/lv2plug.in/ns/ext/atom/util.h b/lv2/lv2plug.in/ns/ext/atom/util.h
index 6ba792c..9015a01 100644
--- a/lv2/lv2plug.in/ns/ext/atom/util.h
+++ b/lv2/lv2plug.in/ns/ext/atom/util.h
@@ -22,12 +22,11 @@
This header is non-normative, it is provided for convenience.
*/
-#ifndef LV2_ATOM_HELPERS_H
-#define LV2_ATOM_HELPERS_H
+#ifndef LV2_ATOM_UTIL_H
+#define LV2_ATOM_UTIL_H
#include <stdarg.h>
#include <stdint.h>
-#include <stdio.h>
#include <string.h>
#include "lv2/lv2plug.in/ns/ext/atom/atom.h"
@@ -272,6 +271,9 @@ static const LV2_Atom_Object_Query LV2_OBJECT_QUERY_END = { 0, NULL };
sweep. By allocating @p query on the stack, objects can be "queried"
quickly without allocating any memory. This function is realtime safe.
+ This function can only do "flat" queries, it is not smart enough to match
+ variables in nested objects.
+
For example:
@code
const LV2_Atom* name = NULL;
@@ -281,12 +283,12 @@ static const LV2_Atom_Object_Query LV2_OBJECT_QUERY_END = { 0, NULL };
{ urids.eg_age, &age },
LV2_OBJECT_QUERY_END
};
- lv2_object_get(obj, q);
+ lv2_object_query(obj, q);
// name and age are now set to the appropriate values in obj, or NULL.
@endcode
*/
static inline int
-lv2_object_get(const LV2_Atom_Object* object, LV2_Atom_Object_Query* query)
+lv2_object_query(const LV2_Atom_Object* object, LV2_Atom_Object_Query* query)
{
int matches = 0;
int n_queries = 0;
@@ -324,19 +326,19 @@ lv2_object_get(const LV2_Atom_Object* object, LV2_Atom_Object_Query* query)
@code
const LV2_Atom* name = NULL;
const LV2_Atom* age = NULL;
- lv2_object_getv(obj,
- uris.name_key, &name,
- uris.age_key, &age,
- 0);
+ lv2_object_get(obj,
+ uris.name_key, &name,
+ uris.age_key, &age,
+ 0);
@endcode
*/
static inline int
-lv2_object_getv(const LV2_Atom_Object* object, ...)
+lv2_object_get(const LV2_Atom_Object* object, ...)
{
int matches = 0;
int n_queries = 0;
- /* Count number of query keys so we can short-circuit when done */
+ /* Count number of keys so we can short-circuit when done */
va_list args;
va_start(args, object);
for (n_queries = 0; va_arg(args, uint32_t); ++n_queries) {
@@ -369,4 +371,4 @@ lv2_object_getv(const LV2_Atom_Object* object, ...)
@}
*/
-#endif /* LV2_ATOM_HELPERS_H */
+#endif /* LV2_ATOM_UTIL_H */