LV2 1.0.13

Data Structures | Functions
Utilities
Atom

## Detailed Description

## Data Structures
struct | LV2_Atom_Object_Query

## Functions
static uint32_t | lv2_atom_pad_size (uint32_t size)
static uint32_t | lv2_atom_total_size (const LV2_Atom *atom)
static bool | lv2_atom_is_null (const LV2_Atom *atom)
static bool | lv2_atom_equals (const LV2_Atom *a, const LV2_Atom *b)

## Sequence Iterator
static LV2_Atom_Event * | lv2_atom_sequence_begin (const LV2_Atom_Sequence_Body *body)
static LV2_Atom_Event * | lv2_atom_sequence_end (const LV2_Atom_Sequence_Body *body, uint32_t size)
static bool | lv2_atom_sequence_is_end (const LV2_Atom_Sequence_Body *body, uint32_t size, const LV2_Atom_Event *i)
static LV2_Atom_Event * | lv2_atom_sequence_next (const LV2_Atom_Event *i)
#define | LV2_ATOM_SEQUENCE_FOREACH(seq, iter)
#define | LV2_ATOM_SEQUENCE_BODY_FOREACH(body, size, iter)

## Sequence Utilities
static void | lv2_atom_sequence_clear (LV2_Atom_Sequence *seq)
static LV2_Atom_Event * | lv2_atom_sequence_append_event (LV2_Atom_Sequence *seq, uint32_t capacity, const LV2_Atom_Event *event)

## Tuple Iterator
static LV2_Atom * | lv2_atom_tuple_begin (const LV2_Atom_Tuple *tup)
static bool | lv2_atom_tuple_is_end (const void *body, uint32_t size, const LV2_Atom *i)
static LV2_Atom * | lv2_atom_tuple_next (const LV2_Atom *i)
#define | LV2_ATOM_TUPLE_FOREACH(tuple, iter)
#define | LV2_ATOM_TUPLE_BODY_FOREACH(body, size, iter)

## Object Iterator
static LV2_Atom_Property_Body * | lv2_atom_object_begin (const LV2_Atom_Object_Body *body)
static bool | lv2_atom_object_is_end (const LV2_Atom_Object_Body *body, uint32_t size, const LV2_Atom_Property_Body *i)
static LV2_Atom_Property_Body * | lv2_atom_object_next (const LV2_Atom_Property_Body *i)
#define | LV2_ATOM_OBJECT_FOREACH(obj, iter)
#define | LV2_ATOM_OBJECT_BODY_FOREACH(body, size, iter)

## Object Query
static const LV2_Atom_Object_Query | LV2_ATOM_OBJECT_QUERY_END = { 0, NULL }
static int | lv2_atom_object_query (const LV2_Atom_Object *object, LV2_Atom_Object_Query *query)
static int | lv2_atom_object_body_get (uint32_t size, const LV2_Atom_Object_Body *body,...)
static int | lv2_atom_object_get (const LV2_Atom_Object *object,...)
static int | lv2_atom_object_get_typed (const LV2_Atom_Object *object,...)

## Data Structure Documentation

## ◆ LV2_Atom_Object_Query

struct LV2_Atom_Object_Query

A single entry in an Object query.

Data Fields
uint32_t | key | Key to query (input set by user)
const LV2_Atom ** | value | Found value (output set by query function)

## Macro Definition Documentation

## ◆ LV2_ATOM_SEQUENCE_FOREACH

#define LV2_ATOM_SEQUENCE_FOREACH | ( |  | seq,
|  |  | iter
| ) |  |

Value:
for (LV2_Atom_Event* (iter) = lv2_atom_sequence_begin(&(seq)->body); \
!lv2_atom_sequence_is_end(&(seq)->body, (seq)->atom.size, (iter)); \
(iter) = lv2_atom_sequence_next(iter))
lv2_atom_sequence_is_end
static bool lv2_atom_sequence_is_end(const LV2_Atom_Sequence_Body *body, uint32_t size, const LV2_Atom_Event *i)
Return true iff i has reached the end of body.
Definition: util.h:96
LV2_Atom_Event
The header of an atom:Event.
Definition: atom.h:210
lv2_atom_sequence_next
static LV2_Atom_Event * lv2_atom_sequence_next(const LV2_Atom_Event *i)
Return an iterator to the element following i.
Definition: util.h:105
lv2_atom_sequence_begin
static LV2_Atom_Event * lv2_atom_sequence_begin(const LV2_Atom_Sequence_Body *body)
Get an iterator pointing to the first event in a Sequence body.
Definition: util.h:82

A macro for iterating over all events in a Sequence.

Parameters

  seq | The sequence to iterate over
  iter | The name of the iterator

This macro is used similarly to a for loop (which it expands to), e.g.:

LV2_ATOM_SEQUENCE_FOREACH(sequence, ev) {
// Do something with ev (an LV2_Atom_Event*) here...
}

## ◆ LV2_ATOM_SEQUENCE_BODY_FOREACH

#define LV2_ATOM_SEQUENCE_BODY_FOREACH | ( |  | body,
|  |  | size,
|  |  | iter
| ) |  |

Value:
for (LV2_Atom_Event* (iter) = lv2_atom_sequence_begin(body); \
!lv2_atom_sequence_is_end(body, size, (iter)); \
(iter) = lv2_atom_sequence_next(iter))
lv2_atom_sequence_is_end
static bool lv2_atom_sequence_is_end(const LV2_Atom_Sequence_Body *body, uint32_t size, const LV2_Atom_Event *i)
Return true iff i has reached the end of body.
Definition: util.h:96
LV2_Atom_Event
The header of an atom:Event.
Definition: atom.h:210
lv2_atom_sequence_next
static LV2_Atom_Event * lv2_atom_sequence_next(const LV2_Atom_Event *i)
Return an iterator to the element following i.
Definition: util.h:105
lv2_atom_sequence_begin
static LV2_Atom_Event * lv2_atom_sequence_begin(const LV2_Atom_Sequence_Body *body)
Get an iterator pointing to the first event in a Sequence body.
Definition: util.h:82

Like LV2_ATOM_SEQUENCE_FOREACH but for a headerless sequence body.

## ◆ LV2_ATOM_TUPLE_FOREACH

#define LV2_ATOM_TUPLE_FOREACH | ( |  | tuple,
|  |  | iter
| ) |  |

Value:
for (LV2_Atom* (iter) = lv2_atom_tuple_begin(tuple); \
!lv2_atom_tuple_is_end(LV2_ATOM_BODY(tuple), (tuple)->atom.size, (iter)); \
(iter) = lv2_atom_tuple_next(iter))
LV2_Atom
The header of an atom:Atom.
Definition: atom.h:106
lv2_atom_tuple_next
static LV2_Atom * lv2_atom_tuple_next(const LV2_Atom *i)
Return an iterator to the element following i.
Definition: util.h:203
LV2_ATOM_BODY
#define LV2_ATOM_BODY(atom)
Return a pointer to the body of an Atom.
Definition: atom.h:98
lv2_atom_tuple_is_end
static bool lv2_atom_tuple_is_end(const void *body, uint32_t size, const LV2_Atom *i)
Return true iff i has reached the end of body.
Definition: util.h:196
lv2_atom_tuple_begin
static LV2_Atom * lv2_atom_tuple_begin(const LV2_Atom_Tuple *tup)
Get an iterator pointing to the first element in tup.
Definition: util.h:189

A macro for iterating over all properties of a Tuple.

Parameters

  tuple | The tuple to iterate over
  iter | The name of the iterator

This macro is used similarly to a for loop (which it expands to), e.g.:

LV2_ATOM_TUPLE_FOREACH(tuple, elem) {
// Do something with elem (an LV2_Atom*) here...
}

## ◆ LV2_ATOM_TUPLE_BODY_FOREACH

#define LV2_ATOM_TUPLE_BODY_FOREACH | ( |  | body,
|  |  | size,
|  |  | iter
| ) |  |

Value:
for (LV2_Atom* (iter) = (LV2_Atom*)(body); \
!lv2_atom_tuple_is_end(body, size, (iter)); \
(iter) = lv2_atom_tuple_next(iter))
LV2_Atom
The header of an atom:Atom.
Definition: atom.h:106
lv2_atom_tuple_next
static LV2_Atom * lv2_atom_tuple_next(const LV2_Atom *i)
Return an iterator to the element following i.
Definition: util.h:203
lv2_atom_tuple_is_end
static bool lv2_atom_tuple_is_end(const void *body, uint32_t size, const LV2_Atom *i)
Return true iff i has reached the end of body.
Definition: util.h:196

Like LV2_ATOM_TUPLE_FOREACH but for a headerless tuple body.

## ◆ LV2_ATOM_OBJECT_FOREACH

#define LV2_ATOM_OBJECT_FOREACH | ( |  | obj,
|  |  | iter
| ) |  |

Value:
for (LV2_Atom_Property_Body* (iter) = lv2_atom_object_begin(&(obj)->body); \
!lv2_atom_object_is_end(&(obj)->body, (obj)->atom.size, (iter)); \
(iter) = lv2_atom_object_next(iter))
lv2_atom_object_begin
static LV2_Atom_Property_Body * lv2_atom_object_begin(const LV2_Atom_Object_Body *body)
Return a pointer to the first property in body.
Definition: util.h:240
lv2_atom_object_is_end
static bool lv2_atom_object_is_end(const LV2_Atom_Object_Body *body, uint32_t size, const LV2_Atom_Property_Body *i)
Return true iff i has reached the end of obj.
Definition: util.h:247
lv2_atom_object_next
static LV2_Atom_Property_Body * lv2_atom_object_next(const LV2_Atom_Property_Body *i)
Return an iterator to the property following i.
Definition: util.h:256
LV2_Atom_Property_Body
The body of an atom:Property (e.g.
Definition: atom.h:183

A macro for iterating over all properties of an Object.

Parameters

  obj | The object to iterate over
  iter | The name of the iterator

This macro is used similarly to a for loop (which it expands to), e.g.:

LV2_ATOM_OBJECT_FOREACH(object, i) {
// Do something with prop (an LV2_Atom_Property_Body*) here...
}

## ◆ LV2_ATOM_OBJECT_BODY_FOREACH

#define LV2_ATOM_OBJECT_BODY_FOREACH | ( |  | body,
|  |  | size,
|  |  | iter
| ) |  |

Value:
for (LV2_Atom_Property_Body* (iter) = lv2_atom_object_begin(body); \
!lv2_atom_object_is_end(body, size, (iter)); \
(iter) = lv2_atom_object_next(iter))
lv2_atom_object_begin
static LV2_Atom_Property_Body * lv2_atom_object_begin(const LV2_Atom_Object_Body *body)
Return a pointer to the first property in body.
Definition: util.h:240
lv2_atom_object_is_end
static bool lv2_atom_object_is_end(const LV2_Atom_Object_Body *body, uint32_t size, const LV2_Atom_Property_Body *i)
Return true iff i has reached the end of obj.
Definition: util.h:247
lv2_atom_object_next
static LV2_Atom_Property_Body * lv2_atom_object_next(const LV2_Atom_Property_Body *i)
Return an iterator to the property following i.
Definition: util.h:256
LV2_Atom_Property_Body
The body of an atom:Property (e.g.
Definition: atom.h:183

Like LV2_ATOM_OBJECT_FOREACH but for a headerless object body.

## Function Documentation

## ◆ lv2_atom_pad_size()

static uint32_t lv2_atom_pad_size | ( | uint32_t | size | ) |
| inline static

Pad a size to 64 bits.

## ◆ lv2_atom_total_size()

static uint32_t lv2_atom_total_size | ( | const LV2_Atom * | atom | ) |
| inline static

Return the total size of `atom`, including the header.

## ◆ lv2_atom_is_null()

static bool lv2_atom_is_null | ( | const LV2_Atom * | atom | ) |
| inline static

Return true iff `atom` is null.

## ◆ lv2_atom_equals()

static bool lv2_atom_equals | ( | const LV2_Atom * | a,
|  | const LV2_Atom * | b
| ) |  |
| inline static

Return true iff `a` is equal to `b`.

## ◆ lv2_atom_sequence_begin()

static LV2_Atom_Event* lv2_atom_sequence_begin | ( | const LV2_Atom_Sequence_Body * | body | ) |
| inline static

Get an iterator pointing to the first event in a Sequence body.

## ◆ lv2_atom_sequence_end()

static LV2_Atom_Event* lv2_atom_sequence_end | ( | const LV2_Atom_Sequence_Body * | body,
|  | uint32_t | size
| ) |  |
| inline static

Get an iterator pointing to the end of a Sequence body.

## ◆ lv2_atom_sequence_is_end()

static bool lv2_atom_sequence_is_end | ( | const LV2_Atom_Sequence_Body * | body,
|  | uint32_t | size,
|  | const LV2_Atom_Event * | i
| ) |  |
| inline static

Return true iff `i` has reached the end of `body`.

## ◆ lv2_atom_sequence_next()

static LV2_Atom_Event* lv2_atom_sequence_next | ( | const LV2_Atom_Event * | i | ) |
| inline static

Return an iterator to the element following `i`.

## ◆ lv2_atom_sequence_clear()

static void lv2_atom_sequence_clear | ( | LV2_Atom_Sequence * | seq | ) |
| inline static

Clear all events from `sequence`.

This simply resets the size field, the other fields are left untouched.

## ◆ lv2_atom_sequence_append_event()

static LV2_Atom_Event* lv2_atom_sequence_append_event | ( | LV2_Atom_Sequence * | seq,
|  | uint32_t | capacity,
|  | const LV2_Atom_Event * | event
| ) |  |
| inline static

Append an event at the end of `sequence`.

Parameters

  seq | Sequence to append to.
  capacity | Total capacity of the sequence atom (e.g. as set by the host for sequence output ports).
  event | Event to write.

Returns
  A pointer to the newly written event in `seq`, or NULL on failure (insufficient space).

## ◆ lv2_atom_tuple_begin()

static LV2_Atom* lv2_atom_tuple_begin | ( | const LV2_Atom_Tuple * | tup | ) |
| inline static

Get an iterator pointing to the first element in `tup`.

## ◆ lv2_atom_tuple_is_end()

static bool lv2_atom_tuple_is_end | ( | const void * | body,
|  | uint32_t | size,
|  | const LV2_Atom * | i
| ) |  |
| inline static

Return true iff `i` has reached the end of `body`.

## ◆ lv2_atom_tuple_next()

static LV2_Atom* lv2_atom_tuple_next | ( | const LV2_Atom * | i | ) |
| inline static

Return an iterator to the element following `i`.

## ◆ lv2_atom_object_begin()

static LV2_Atom_Property_Body* lv2_atom_object_begin | ( | const LV2_Atom_Object_Body * | body | ) |
| inline static

Return a pointer to the first property in `body`.

## ◆ lv2_atom_object_is_end()

static bool lv2_atom_object_is_end | ( | const LV2_Atom_Object_Body * | body,
|  | uint32_t | size,
|  | const LV2_Atom_Property_Body * | i
| ) |  |
| inline static

Return true iff `i` has reached the end of `obj`.

## ◆ lv2_atom_object_next()

static LV2_Atom_Property_Body* lv2_atom_object_next | ( | const LV2_Atom_Property_Body * | i | ) |
| inline static

Return an iterator to the property following `i`.

## ◆ lv2_atom_object_query()

static int lv2_atom_object_query | ( | const LV2_Atom_Object * | object,
|  | LV2_Atom_Object_Query * | query
| ) |  |
| inline static

Get an object's values for various keys.

The value pointer of each item in `query` will be set to the location of the corresponding value in `object`. Every value pointer in `query` MUST be initialised to NULL. This function reads `object` in a single linear sweep. By allocating `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:

const LV2_Atom* name = NULL;
const LV2_Atom* age = NULL;
LV2_Atom_Object_Query q[] = {
{ urids.eg_name, &name },
{ urids.eg_age, &age },
LV2_ATOM_OBJECT_QUERY_END
};
lv2_atom_object_query(obj, q);
// name and age are now set to the appropriate values in obj, or NULL.

## ◆ lv2_atom_object_body_get()

static int lv2_atom_object_body_get | ( | uint32_t | size,
|  | const LV2_Atom_Object_Body * | body,
|  |  | ...
| ) |  |
| inline static

Body only version of lv2_atom_object_get().

## ◆ lv2_atom_object_get()

static int lv2_atom_object_get | ( | const LV2_Atom_Object * | object,
|  |  | ...
| ) |  |
| inline static

Variable argument version of lv2_atom_object_query().

This is nicer-looking in code, but a bit more error-prone since it is not type safe and the argument list must be terminated.

The arguments should be a series of uint32_t key and const LV2_Atom** value pairs, terminated by a zero key. The value pointers MUST be initialized to NULL. For example:

const LV2_Atom* name = NULL;
const LV2_Atom* age = NULL;
lv2_atom_object_get(obj,
uris.name_key, &name,
uris.age_key, &age,
0);

## ◆ lv2_atom_object_get_typed()

static int lv2_atom_object_get_typed | ( | const LV2_Atom_Object * | object,
|  |  | ...
| ) |  |
| inline static

Variable argument version of lv2_atom_object_query() with types.

This is like lv2_atom_object_get(), but each entry has an additional parameter to specify the required type. Only atoms with a matching type will be selected.

The arguments should be a series of uint32_t key, const LV2_Atom**, uint32_t type triples, terminated by a zero key. The value pointers MUST be initialized to NULL. For example:

const LV2_Atom_String* name = NULL;
const LV2_Atom_Int* age = NULL;
lv2_atom_object_get(obj,
uris.name_key, &name, uris.atom_String,
uris.age_key, &age, uris.atom_Int
0);