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
28G_BEGIN_DECLS
29
30typedef struct _GstMeta GstMeta;
31typedef struct _GstMetaInfo GstMetaInfo;
32
33#define GST_META_CAST(meta) ((GstMeta *)(meta))
34
35/**
36 * GstMetaFlags:
37 * @GST_META_FLAG_NONE: no flags
38 * @GST_META_FLAG_READONLY: metadata should not be modified
39 * @GST_META_FLAG_POOLED: metadata is managed by a bufferpool
40 * @GST_META_FLAG_LOCKED: metadata should not be removed
41 * @GST_META_FLAG_LAST: additional flags can be added starting from this flag.
42 *
43 * Extra metadata flags.
44 */
45typedef enum {
46 GST_META_FLAG_NONE = 0,
47 GST_META_FLAG_READONLY = (1 << 0),
48 GST_META_FLAG_POOLED = (1 << 1),
49 GST_META_FLAG_LOCKED = (1 << 2),
50
51 GST_META_FLAG_LAST = (1 << 16)
52} GstMetaFlags;
53
54/**
55 * GST_META_FLAGS:
56 * @meta: a #GstMeta.
57 *
58 * A flags word containing #GstMetaFlags flags set on @meta
59 */
60#define GST_META_FLAGS(meta) (GST_META_CAST (meta)->flags)
61/**
62 * GST_META_FLAG_IS_SET:
63 * @meta: a #GstMeta.
64 * @flag: the #GstMetaFlags to check.
65 *
66 * Gives the status of a specific flag on a metadata.
67 */
68#define GST_META_FLAG_IS_SET(meta,flag) !!(GST_META_FLAGS (meta) & (flag))
69/**
70 * GST_META_FLAG_SET:
71 * @meta: a #GstMeta.
72 * @flag: the #GstMetaFlags to set.
73 *
74 * Sets a metadata flag on a metadata.
75 */
76#define GST_META_FLAG_SET(meta,flag) (GST_META_FLAGS (meta) |= (flag))
77/**
78 * GST_META_FLAG_UNSET:
79 * @meta: a #GstMeta.
80 * @flag: the #GstMetaFlags to clear.
81 *
82 * Clears a metadata flag.
83 */
84#define GST_META_FLAG_UNSET(meta,flag) (GST_META_FLAGS (meta) &= ~(flag))
85
86/**
87 * GST_META_TAG_MEMORY_STR:
88 *
89 * This metadata stays relevant as long as memory layout is unchanged.
90 *
91 * Since: 1.2
92 */
93#define GST_META_TAG_MEMORY_STR "memory"
94
95/**
96 * GstMeta:
97 * @flags: extra flags for the metadata
98 * @info: pointer to the #GstMetaInfo
99 *
100 * Base structure for metadata. Custom metadata will put this structure
101 * as the first member of their structure.
102 */
103struct _GstMeta {
104 GstMetaFlags flags;
105 const GstMetaInfo *info;
106};
107
108/**
109 * GstCustomMeta:
110 *
111 * Simple typing wrapper around #GstMeta
112 *
113 * Since: 1.20
114 */
115typedef struct {
116 GstMeta meta;
117} GstCustomMeta;
118
119#include <gst/gstbuffer.h>
120
121/**
122 * GstMetaInitFunction:
123 * @meta: a #GstMeta
124 * @params: parameters passed to the init function
125 * @buffer: a #GstBuffer
126 *
127 * Function called when @meta is initialized in @buffer.
128 */
129typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
130
131/**
132 * GstMetaFreeFunction:
133 * @meta: a #GstMeta
134 * @buffer: a #GstBuffer
135 *
136 * Function called when @meta is freed in @buffer.
137 */
138typedef void (*GstMetaFreeFunction) (GstMeta *meta, GstBuffer *buffer);
139
140/**
141 * gst_meta_transform_copy:
142 *
143 * GQuark for the "gst-copy" transform.
144 */
145
146GST_API GQuark _gst_meta_transform_copy;
147
148/**
149 * GST_META_TRANSFORM_IS_COPY:
150 * @type: a transform type
151 *
152 * Check if the transform type is a copy transform
153 */
154#define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy)
155
156/**
157 * GstMetaTransformCopy:
158 * @region: %TRUE if only region is copied
159 * @offset: the offset to copy, 0 if @region is %FALSE, otherwise > 0
160 * @size: the size to copy, -1 or the buffer size when @region is %FALSE
161 *
162 * Extra data passed to a "gst-copy" transform #GstMetaTransformFunction.
163 */
164typedef struct {
165 gboolean region;
166 gsize offset;
167 gsize size;
168} GstMetaTransformCopy;
169
170/**
171 * GstMetaTransformFunction:
172 * @transbuf: a #GstBuffer
173 * @meta: a #GstMeta
174 * @buffer: a #GstBuffer
175 * @type: the transform type
176 * @data: transform specific data.
177 *
178 * Function called for each @meta in @buffer as a result of performing a
179 * transformation on @transbuf. Additional @type specific transform data
180 * is passed to the function as @data.
181 *
182 * Implementations should check the @type of the transform and parse
183 * additional type specific fields in @data that should be used to update
184 * the metadata on @transbuf.
185 *
186 * Returns: %TRUE if the transform could be performed
187 */
188typedef gboolean (*GstMetaTransformFunction) (GstBuffer *transbuf,
189 GstMeta *meta, GstBuffer *buffer,
190 GQuark type, gpointer data);
191
192/**
193 * GstCustomMetaTransformFunction:
194 * @transbuf: a #GstBuffer
195 * @meta: a #GstCustomMeta
196 * @buffer: a #GstBuffer
197 * @type: the transform type
198 * @data: transform specific data.
199 * @user_data: user data passed when registering the meta
200 *
201 * Function called for each @meta in @buffer as a result of performing a
202 * transformation on @transbuf. Additional @type specific transform data
203 * is passed to the function as @data.
204 *
205 * Implementations should check the @type of the transform and parse
206 * additional type specific fields in @data that should be used to update
207 * the metadata on @transbuf.
208 *
209 * Returns: %TRUE if the transform could be performed
210 * Since: 1.20
211 */
212typedef gboolean (*GstCustomMetaTransformFunction) (GstBuffer *transbuf,
213 GstCustomMeta *meta, GstBuffer *buffer,
214 GQuark type, gpointer data, gpointer user_data);
215
216/**
217 * GstMetaInfo:
218 * @api: tag identifying the metadata structure and api
219 * @type: type identifying the implementor of the api
220 * @size: size of the metadata
221 * @init_func: function for initializing the metadata
222 * @free_func: function for freeing the metadata
223 * @transform_func: function for transforming the metadata
224 *
225 * The #GstMetaInfo provides information about a specific metadata
226 * structure.
227 */
228struct _GstMetaInfo {
229 GType api;
230 GType type;
231 gsize size;
232
233 GstMetaInitFunction init_func;
234 GstMetaFreeFunction free_func;
235 GstMetaTransformFunction transform_func;
236
237 /* No padding needed, GstMetaInfo is always allocated by GStreamer and is
238 * not subclassable or stack-allocatable, so we can extend it as we please
239 * just like interfaces */
240};
241
242GST_API
243GType gst_meta_api_type_register (const gchar *api,
244 const gchar **tags);
245GST_API
246gboolean gst_meta_api_type_has_tag (GType api, GQuark tag);
247
248GST_API
249const GstMetaInfo * gst_meta_register (GType api, const gchar *impl,
250 gsize size,
251 GstMetaInitFunction init_func,
252 GstMetaFreeFunction free_func,
253 GstMetaTransformFunction transform_func);
254
255GST_API
256const GstMetaInfo * gst_meta_register_custom (const gchar *name, const gchar **tags,
257 GstCustomMetaTransformFunction transform_func,
258 gpointer user_data, GDestroyNotify destroy_data);
259
260GST_API
261gboolean gst_meta_info_is_custom (const GstMetaInfo *info);
262
263GST_API
264GstStructure * gst_custom_meta_get_structure (GstCustomMeta *meta);
265
266GST_API
267gboolean gst_custom_meta_has_name (GstCustomMeta *meta, const gchar * name);
268
269GST_API
270const GstMetaInfo * gst_meta_get_info (const gchar * impl);
271
272GST_API
273const gchar* const* gst_meta_api_type_get_tags (GType api);
274
275GST_API
276guint64 gst_meta_get_seqnum (const GstMeta * meta);
277
278GST_API
279gint gst_meta_compare_seqnum (const GstMeta * meta1,
280 const GstMeta * meta2);
281
282/* some default tags */
283
284GST_API GQuark _gst_meta_tag_memory;
285
286/**
287 * GST_META_TAG_MEMORY:
288 *
289 * Metadata tagged with this tag depends on the particular memory
290 * or buffer that it is on.
291 *
292 * Deprecated: The GQuarks are not exported by any public API, use
293 * GST_META_TAG_MEMORY_STR instead.
294 */
295#ifndef GST_DISABLE_DEPRECATED
296#define GST_META_TAG_MEMORY (_gst_meta_tag_memory)
297#endif
298
299G_END_DECLS
300
301#endif /* __GST_META_H__ */
302

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