aboutsummaryrefslogtreecommitdiffstats
path: root/ext/atom.lv2/atom-helpers.h
blob: 9d48a2973f7ef7b817cb5886478e7814ca4f49ef (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
/*
  Copyright 2008-2011 David Robillard <http://drobilla.net>

  Permission to use, copy, modify, and/or distribute this software for any
  purpose with or without fee is hereby granted, provided that the above
  copyright notice and this permission notice appear in all copies.

  THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/

/**
   @file atom-helpers.h Helper functions for the LV2 Atom extension.

   These functions are provided for convenience only, use of them is not
   required for supporting atoms.

   Note that these functions are all static inline which basically means:
   do not take the address of these functions.
*/

#ifndef LV2_ATOM_HELPERS_H
#define LV2_ATOM_HELPERS_H

#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>

#include "lv2/lv2plug.in/ns/ext/atom/atom.h"

typedef LV2_Atom_Property* LV2_Object_Iter;

/** Get an iterator pointing to @c prop in some LV2_Object */
static inline LV2_Object_Iter
lv2_object_begin(const LV2_Object* obj)
{
	return (LV2_Object_Iter)(obj->properties);
}

/** Return true iff @c iter has reached the end of @c object */
static inline bool
lv2_object_iter_is_end(const LV2_Object* obj, LV2_Object_Iter iter)
{
	return (uint8_t*)iter >= ((uint8_t*)obj + sizeof(LV2_Atom) + obj->size);
}

/** Return true iff @c l points to the same property as @c r */
static inline bool
lv2_object_iter_equals(const LV2_Object_Iter l, const LV2_Object_Iter r)
{
	return l == r;
}

/** Return an iterator to the property following @c iter */
static inline LV2_Object_Iter
lv2_object_iter_next(const LV2_Object_Iter iter)
{
	return (LV2_Object_Iter)((uint8_t*)iter
	                         + sizeof(LV2_Atom_Property)
	                         + lv2_atom_pad_size(iter->value.size));
}

/** Return the property pointed to by @c iter */
static inline LV2_Atom_Property*
lv2_object_iter_get(LV2_Object_Iter iter)
{
	return (LV2_Atom_Property*)iter;
}

/**
   A macro for iterating over all properties of an Object.
   @param obj  The object to iterate over
   @param iter The name of the iterator

   This macro is used similarly to a for loop (which it expands to), e.g.:
   <pre>
   LV2_OBJECT_FOREACH(object, i) {
       LV2_Atom_Property* prop = lv2_object_iter_get(i);
       // Do things with prop here...
   }
   </pre>
*/
#define LV2_OBJECT_FOREACH(obj, iter) \
	for (LV2_Object_Iter (iter) = lv2_object_begin(obj); \
	     !lv2_object_iter_is_end(obj, (iter)); \
	     (iter) = lv2_object_iter_next(iter))

/**
   Append a Property body to an Atom that contains properties (e.g. atom:Object).
   @param object Pointer to the atom that contains the property to add.  object.size
   must be valid, but object.type is ignored.
   @param key The key of the new property
   @param value_type The type of the new value
   @param value_size The size of the new value
   @param value_body Pointer to the new value's data
   @return a pointer to the new LV2_Atom_Property in @c body.

   This function will write the property body (not including an LV2_Object
   header) at lv2_atom_pad_size(body + size).  Thus, it can be used with any
   Atom type that contains headerless 32-bit aligned properties.
*/
static inline LV2_Atom_Property*
lv2_object_append(LV2_Object* object,
                  uint32_t    key,
                  uint32_t    value_type,
                  uint32_t    value_size,
                  const void* value_body)
{
	object->size = lv2_atom_pad_size(object->size);
	LV2_Atom_Property* prop = (LV2_Atom_Property*)(
		(uint8_t*)object + sizeof(LV2_Atom) + object->size);
	prop->key = key;
	prop->value.type = value_type;
	prop->value.size = value_size;
	memcpy(prop->value.body, value_body, value_size);
	object->size += sizeof(LV2_Atom_Property) + value_size;
	return prop;
}

/** Return true iff @c atom is NULL */
static inline bool
lv2_atom_is_null(LV2_Atom* atom)
{
	return !atom || (atom->type == 0 && atom->size == 0);
}

/** A single entry in an Object query. */
typedef struct {
	uint32_t         key;    /**< Key to query (input set by user) */
	const LV2_Atom** value;  /**< Found value (output set by query function) */
} LV2_Object_Query;

static const LV2_Object_Query LV2_OBJECT_QUERY_END = { 0, NULL };

/**
   "Query" an object, getting a pointer to the values for various keys.

   The value pointer of each item in @c query will be set to the location of
   the corresponding value in @c object.  Every value pointer in @c query MUST
   be initialised to NULL.  This function reads @c object in a single linear
   sweep.  By allocating @c query on the stack, objects can be "queried"
   quickly without allocating any memory.  This function is realtime safe.
*/
static inline int
lv2_object_query(const LV2_Object* object, LV2_Object_Query* query)
{
	int matches   = 0;
	int n_queries = 0;

	/* Count number of query keys so we can short-circuit when done */
	for (LV2_Object_Query* q = query; q->key; ++q)
		++n_queries;

	LV2_OBJECT_FOREACH(object, o) {
		const LV2_Atom_Property* prop = lv2_object_iter_get(o);
		for (LV2_Object_Query* q = query; q->key; ++q) {
			if (q->key == prop->key && !*q->value) {
				*q->value = &prop->value;
				if (++matches == n_queries)
					return matches;
				break;
			}
		}
	}
	return matches;
}

#endif /* LV2_ATOM_HELPERS_H */