1/* GStreamer
2 * Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
3 *
4 * gstmeta.h: Header for Metadata structures
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22
23#ifndef __GST_META_H__
24#define __GST_META_H__
25
26#include <glib.h>
27
28#include <gst/gstbytearrayinterface.h>
29
30
31G_BEGIN_DECLS
32
33typedef struct _GstMeta GstMeta;
34typedef struct _GstMetaInfo GstMetaInfo;
35
36#define GST_META_CAST(meta) ((GstMeta *)(meta))
37
38/**
39 * GstMetaFlags:
40 * @GST_META_FLAG_NONE: no flags
41 * @GST_META_FLAG_READONLY: metadata should not be modified
42 * @GST_META_FLAG_POOLED: metadata is managed by a bufferpool
43 * @GST_META_FLAG_LOCKED: metadata should not be removed
44 * @GST_META_FLAG_LAST: additional flags can be added starting from this flag.
45 *
46 * Extra metadata flags.
47 */
48typedef enum {
49 GST_META_FLAG_NONE = 0,
50 GST_META_FLAG_READONLY = (1 << 0),
51 GST_META_FLAG_POOLED = (1 << 1),
52 GST_META_FLAG_LOCKED = (1 << 2),
53
54 GST_META_FLAG_LAST = (1 << 16)
55} GstMetaFlags;
56
57/**
58 * GST_META_FLAGS:
59 * @meta: a #GstMeta.
60 *
61 * A flags word containing #GstMetaFlags flags set on @meta
62 */
63#define GST_META_FLAGS(meta) (GST_META_CAST (meta)->flags)
64/**
65 * GST_META_FLAG_IS_SET:
66 * @meta: a #GstMeta.
67 * @flag: the #GstMetaFlags to check.
68 *
69 * Gives the status of a specific flag on a metadata.
70 */
71#define GST_META_FLAG_IS_SET(meta,flag) !!(GST_META_FLAGS (meta) & (flag))
72/**
73 * GST_META_FLAG_SET:
74 * @meta: a #GstMeta.
75 * @flag: the #GstMetaFlags to set.
76 *
77 * Sets a metadata flag on a metadata.
78 */
79#define GST_META_FLAG_SET(meta,flag) (GST_META_FLAGS (meta) |= (flag))
80/**
81 * GST_META_FLAG_UNSET:
82 * @meta: a #GstMeta.
83 * @flag: the #GstMetaFlags to clear.
84 *
85 * Clears a metadata flag.
86 *
87 */
88#define GST_META_FLAG_UNSET(meta,flag) (GST_META_FLAGS (meta) &= ~(flag))
89
90/**
91 * GST_META_TAG_MEMORY_STR:
92 *
93 * This metadata stays relevant as long as memory layout is unchanged.
94 * In hindsight, this tag should have been called "memory-layout".
95 *
96 * Since: 1.2
97 */
98#define GST_META_TAG_MEMORY_STR "memory"
99
100/**
101 * GST_META_TAG_MEMORY_REFERENCE_STR:
102 *
103 * This metadata stays relevant until a deep copy is made.
104 *
105 * Since: 1.20.4
106 */
107#define GST_META_TAG_MEMORY_REFERENCE_STR "memory-reference"
108
109/**
110 * GstMeta:
111 * @flags: extra flags for the metadata
112 * @info: pointer to the #GstMetaInfo
113 *
114 * Base structure for metadata. Custom metadata will put this structure
115 * as the first member of their structure.
116 */
117struct _GstMeta {
118 GstMetaFlags flags;
119 const GstMetaInfo *info;
120};
121
122/**
123 * GstCustomMeta.structure:
124 *
125 * #GstStructure containing custom metadata.
126 *
127 * Since: 1.24
128 */
129
130/**
131 * GstCustomMeta:
132 * @meta: parent #GstMeta
133 * @structure: a #GstStructure containing custom metadata. (Since: 1.24)
134 *
135 * Extra custom metadata. The @structure field is the same as returned by
136 * gst_custom_meta_get_structure().
137 *
138 * Since 1.24 it can be serialized using gst_meta_serialize() and
139 * gst_meta_deserialize(), but only if the #GstStructure does not contain any
140 * fields that cannot be serialized, see %GST_SERIALIZE_FLAG_STRICT.
141 *
142 * Since: 1.20
143 */
144typedef struct {
145 GstMeta meta;
146 GstStructure *structure;
147} GstCustomMeta;
148
149#include <gst/gstbuffer.h>
150
151/**
152 * GstMetaInitFunction:
153 * @meta: a #GstMeta
154 * @params: parameters passed to the init function
155 * @buffer: a #GstBuffer
156 *
157 * Function called when @meta is initialized in @buffer.
158 */
159typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
160
161/**
162 * GstMetaFreeFunction:
163 * @meta: a #GstMeta
164 * @buffer: a #GstBuffer
165 *
166 * Function called when @meta is freed in @buffer.
167 */
168typedef void (*GstMetaFreeFunction) (GstMeta *meta, GstBuffer *buffer);
169
170/**
171 * gst_meta_transform_copy:
172 *
173 * GQuark for the "gst-copy" transform.
174 */
175
176GST_API GQuark _gst_meta_transform_copy;
177
178/**
179 * GST_META_TRANSFORM_IS_COPY:
180 * @type: a transform type
181 *
182 * Check if the transform type is a copy transform
183 */
184#define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy)
185
186/**
187 * GstMetaTransformCopy:
188 * @region: %TRUE if only region is copied
189 * @offset: the offset to copy, 0 if @region is %FALSE, otherwise > 0
190 * @size: the size to copy, -1 or the buffer size when @region is %FALSE
191 *
192 * Extra data passed to a "gst-copy" transform #GstMetaTransformFunction.
193 */
194typedef struct {
195 gboolean region;
196 gsize offset;
197 gsize size;
198} GstMetaTransformCopy;
199
200/**
201 * GstMetaTransformFunction:
202 * @transbuf: a #GstBuffer
203 * @meta: a #GstMeta
204 * @buffer: a #GstBuffer
205 * @type: the transform type
206 * @data: transform specific data.
207 *
208 * Function called for each @meta in @buffer as a result of performing a
209 * transformation on @transbuf. Additional @type specific transform data
210 * is passed to the function as @data.
211 *
212 * Implementations should check the @type of the transform and parse
213 * additional type specific fields in @data that should be used to update
214 * the metadata on @transbuf.
215 *
216 * Returns: %TRUE if the transform could be performed
217 */
218typedef gboolean (*GstMetaTransformFunction) (GstBuffer *transbuf,
219 GstMeta *meta, GstBuffer *buffer,
220 GQuark type, gpointer data);
221
222/**
223 * GstCustomMetaTransformFunction:
224 * @transbuf: a #GstBuffer
225 * @meta: a #GstCustomMeta
226 * @buffer: a #GstBuffer
227 * @type: the transform type
228 * @data: transform specific data.
229 * @user_data: user data passed when registering the meta
230 *
231 * Function called for each @meta in @buffer as a result of performing a
232 * transformation that yields @transbuf. Additional @type specific transform
233 * data is passed to the function as @data.
234 *
235 * Implementations should check the @type of the transform and parse
236 * additional type specific fields in @data that should be used to update
237 * the metadata on @transbuf.
238 *
239 * Returns: %TRUE if the transform could be performed
240 * Since: 1.20
241 */
242typedef gboolean (*GstCustomMetaTransformFunction) (GstBuffer *transbuf,
243 GstCustomMeta *meta, GstBuffer *buffer,
244 GQuark type, gpointer data, gpointer user_data);
245
246/**
247 * GstMetaSerializeFunction:
248 * @meta: a #GstMeta
249 * @data: #GstByteArrayInterface to append serialization data
250 * @version: (out): version of the serialization format
251 *
252 * Serialize @meta into a format that can be stored or transmitted and later
253 * deserialized by #GstMetaDeserializeFunction.
254 *
255 * By default version is set to 0, it should be bumped if incompatible changes
256 * are made to the format so %GstMetaDeserializeFunction can deserialize each
257 * version.
258 *
259 * Returns: %TRUE on success, %FALSE otherwise.
260 *
261 * Since: 1.24
262 */
263typedef gboolean (*GstMetaSerializeFunction) (const GstMeta *meta,
264 GstByteArrayInterface *data, guint8 *version);
265
266/**
267 * GstMetaDeserializeFunction:
268 * @info: #GstMetaInfo of the meta
269 * @buffer: a #GstBuffer
270 * @data: data obtained from #GstMetaSerializeFunction
271 * @size: size of data to avoid buffer overflow
272 *
273 * Recreate a #GstMeta from serialized data returned by
274 * #GstMetaSerializeFunction and add it to @buffer.
275 *
276 * Returns: (transfer none) (nullable): the metadata owned by @buffer, or %NULL.
277 *
278 * Since: 1.24
279 */
280typedef GstMeta *(*GstMetaDeserializeFunction) (const GstMetaInfo *info,
281 GstBuffer *buffer, const guint8 *data, gsize size, guint8 version);
282
283/**
284 * GstMetaClearFunction:
285 * @buffer: a #GstBuffer
286 * @meta: a #GstMeta
287 *
288 * Clears the content of the meta. This will be called by the GstBufferPool
289 * when a pooled buffer is returned.
290 *
291 * Since: 1.24
292 */
293typedef void (*GstMetaClearFunction) (GstBuffer *buffer, GstMeta *meta);
294
295/**
296 * GstMetaInfo.serialize_func:
297 *
298 * Function for serializing the metadata, or %NULL if not supported by this
299 * meta.
300 *
301 * Since: 1.24
302 */
303
304/**
305 * GstMetaInfo.deserialize_func:
306 *
307 * Function for deserializing the metadata, or %NULL if not supported by this
308 * meta.
309 *
310 * Since: 1.24
311 */
312
313/**
314 * GstMetaInfo.clear_func:
315 *
316 * Function for clearing the metadata, or %NULL if not supported by this
317 * meta. This is called by the buffer pool when a buffer is returned for
318 * pooled metas.
319 *
320 * Since: 1.24
321 */
322
323/**
324 * GstMetaInfo:
325 * @api: tag identifying the metadata structure and api
326 * @type: type identifying the implementor of the api
327 * @size: size of the metadata
328 * @init_func: function for initializing the metadata
329 * @free_func: function for freeing the metadata
330 * @transform_func: function for transforming the metadata
331 * @serialize_func: function for serializing the metadata into a #GstStructure,
332 * or %NULL if not supported by this meta. (Since 1.24)
333 * @deserialize_func: function for deserializing the metadata from a
334 * #GstStructure, or %NULL if not supported by this meta. (Since 1.24)
335 *
336 * The #GstMetaInfo provides information about a specific metadata
337 * structure.
338 */
339struct _GstMetaInfo {
340 GType api;
341 GType type;
342 gsize size;
343
344 GstMetaInitFunction init_func;
345 GstMetaFreeFunction free_func;
346 GstMetaTransformFunction transform_func;
347 GstMetaSerializeFunction serialize_func;
348 GstMetaDeserializeFunction deserialize_func;
349 GstMetaClearFunction clear_func;
350
351 /* No padding needed, GstMetaInfo is always allocated by GStreamer and is
352 * not subclassable or stack-allocatable, so we can extend it as we please
353 * just like interfaces */
354};
355
356GST_API
357GType gst_meta_api_type_register (const gchar *api,
358 const gchar **tags);
359GST_API
360gboolean gst_meta_api_type_has_tag (GType api, GQuark tag);
361
362GST_API
363const GstMetaInfo * gst_meta_register (GType api, const gchar *impl,
364 gsize size,
365 GstMetaInitFunction init_func,
366 GstMetaFreeFunction free_func,
367 GstMetaTransformFunction transform_func);
368
369GST_API
370GstMetaInfo * gst_meta_info_new (GType api,
371 const gchar *impl,
372 gsize size);
373GST_API
374const GstMetaInfo * gst_meta_info_register (GstMetaInfo *info);
375
376GST_API
377const GstMetaInfo * gst_meta_register_custom (const gchar *name, const gchar **tags,
378 GstCustomMetaTransformFunction transform_func,
379 gpointer user_data, GDestroyNotify destroy_data);
380
381GST_API
382const GstMetaInfo * gst_meta_register_custom_simple (const gchar *name);
383
384GST_API
385gboolean gst_meta_info_is_custom (const GstMetaInfo *info);
386
387GST_API
388GstStructure * gst_custom_meta_get_structure (GstCustomMeta *meta);
389
390GST_API
391gboolean gst_custom_meta_has_name (GstCustomMeta *meta, const gchar * name);
392
393GST_API
394const GstMetaInfo * gst_meta_get_info (const gchar * impl);
395
396GST_API
397const gchar* const* gst_meta_api_type_get_tags (GType api);
398
399GST_API
400guint64 gst_meta_get_seqnum (const GstMeta * meta);
401
402GST_API
403gint gst_meta_compare_seqnum (const GstMeta * meta1,
404 const GstMeta * meta2);
405
406GST_API
407gboolean gst_meta_serialize (const GstMeta *meta,
408 GstByteArrayInterface *data);
409GST_API
410gboolean gst_meta_serialize_simple (const GstMeta *meta,
411 GByteArray *data);
412GST_API
413GstMeta * gst_meta_deserialize (GstBuffer *buffer,
414 const guint8 *data,
415 gsize size,
416 guint32 *consumed);
417
418/* some default tags */
419
420GST_API GQuark _gst_meta_tag_memory;
421GST_API GQuark _gst_meta_tag_memory_reference;
422
423/**
424 * GST_META_TAG_MEMORY:
425 *
426 * Metadata tagged with this tag depends on the particular memory
427 * or buffer that it is on.
428 *
429 * Deprecated: The GQuarks are not exported by any public API, use
430 * GST_META_TAG_MEMORY_STR instead.
431 */
432#ifndef GST_DISABLE_DEPRECATED
433#define GST_META_TAG_MEMORY (_gst_meta_tag_memory)
434#endif
435
436G_END_DECLS
437
438#endif /* __GST_META_H__ */
439

source code of include/gstreamer-1.0/gst/gstmeta.h