From ab74953ba3f8ff649ff1c53536a7b649763c677d Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 19 Feb 2012 04:18:53 +0000 Subject: Clean up documentation. Improve object query function names. --- lv2/lv2plug.in/ns/ext/atom/atom-test.c | 34 ++++++++++++++++---------------- lv2/lv2plug.in/ns/ext/atom/atom.h | 35 +++++++++++++++------------------ lv2/lv2plug.in/ns/ext/atom/atom.ttl | 6 +++--- lv2/lv2plug.in/ns/ext/atom/forge.h | 21 ++++++++++---------- lv2/lv2plug.in/ns/ext/atom/manifest.ttl | 3 +-- lv2/lv2plug.in/ns/ext/atom/util.h | 26 +++++++++++++----------- 6 files changed, 62 insertions(+), 63 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext/atom') 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 . - - This header describes the binary layout of various types defined in the - atom extension. */ #ifndef LV2_ATOM_H #define LV2_ATOM_H +#include +#include + #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 -#include - #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 , ; 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.

-""" . \ 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 @@ a lv2:Specification ; lv2:minorVersion 0 ; - lv2:microVersion 4 ; + lv2:microVersion 5 ; rdfs:seeAlso . - 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 #include -#include #include #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 */ -- cgit v1.2.1