2 * Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
4 * gstmeta.h: Header for Metadata structures
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.
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.
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.
23 #ifndef __GST_META_H__
24 #define __GST_META_H__
30 typedef struct _GstMeta GstMeta;
31 typedef struct _GstMetaInfo GstMetaInfo;
33 #define GST_META_CAST(meta) ((GstMeta *)(meta))
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.
43 * Extra metadata flags.
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),
51 GST_META_FLAG_LAST = (1 << 16)
58 * A flags word containing #GstMetaFlags flags set on @meta
60 #define GST_META_FLAGS(meta) (GST_META_CAST (meta)->flags)
62 * GST_META_FLAG_IS_SET:
64 * @flag: the #GstMetaFlags to check.
66 * Gives the status of a specific flag on a metadata.
68 #define GST_META_FLAG_IS_SET(meta,flag) !!(GST_META_FLAGS (meta) & (flag))
72 * @flag: the #GstMetaFlags to set.
74 * Sets a metadata flag on a metadata.
76 #define GST_META_FLAG_SET(meta,flag) (GST_META_FLAGS (meta) |= (flag))
78 * GST_META_FLAG_UNSET:
80 * @flag: the #GstMetaFlags to clear.
82 * Clears a metadata flag.
84 #define GST_META_FLAG_UNSET(meta,flag) (GST_META_FLAGS (meta) &= ~(flag))
87 * GST_META_TAG_MEMORY_STR:
89 * This metadata stays relevant as long as memory layout is unchanged.
90 * In hindsight, this tag should have been called "memory-layout".
94 #define GST_META_TAG_MEMORY_STR "memory"
97 * GST_META_TAG_MEMORY_REFERENCE_STR:
99 * This metadata stays relevant until a deep copy is made.
103 #define GST_META_TAG_MEMORY_REFERENCE_STR "memory-reference"
107 * @flags: extra flags for the metadata
108 * @info: pointer to the #GstMetaInfo
110 * Base structure for metadata. Custom metadata will put this structure
111 * as the first member of their structure.
115 const GstMetaInfo *info;
121 * Simple typing wrapper around #GstMeta
129 #include <gst/gstbuffer.h>
132 * GstMetaInitFunction:
134 * @params: parameters passed to the init function
135 * @buffer: a #GstBuffer
137 * Function called when @meta is initialized in @buffer.
139 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
142 * GstMetaFreeFunction:
144 * @buffer: a #GstBuffer
146 * Function called when @meta is freed in @buffer.
148 typedef void (*GstMetaFreeFunction) (GstMeta *meta, GstBuffer *buffer);
151 * gst_meta_transform_copy:
153 * GQuark for the "gst-copy" transform.
156 GST_API GQuark _gst_meta_transform_copy;
159 * GST_META_TRANSFORM_IS_COPY:
160 * @type: a transform type
162 * Check if the transform type is a copy transform
164 #define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy)
167 * GstMetaTransformCopy:
168 * @region: %TRUE if only region is copied
169 * @offset: the offset to copy, 0 if @region is %FALSE, otherwise > 0
170 * @size: the size to copy, -1 or the buffer size when @region is %FALSE
172 * Extra data passed to a "gst-copy" transform #GstMetaTransformFunction.
178 } GstMetaTransformCopy;
181 * GstMetaTransformFunction:
182 * @transbuf: a #GstBuffer
184 * @buffer: a #GstBuffer
185 * @type: the transform type
186 * @data: transform specific data.
188 * Function called for each @meta in @buffer as a result of performing a
189 * transformation on @transbuf. Additional @type specific transform data
190 * is passed to the function as @data.
192 * Implementations should check the @type of the transform and parse
193 * additional type specific fields in @data that should be used to update
194 * the metadata on @transbuf.
196 * Returns: %TRUE if the transform could be performed
198 typedef gboolean (*GstMetaTransformFunction) (GstBuffer *transbuf,
199 GstMeta *meta, GstBuffer *buffer,
200 GQuark type, gpointer data);
203 * GstCustomMetaTransformFunction:
204 * @transbuf: a #GstBuffer
205 * @meta: a #GstCustomMeta
206 * @buffer: a #GstBuffer
207 * @type: the transform type
208 * @data: transform specific data.
209 * @user_data: user data passed when registering the meta
211 * Function called for each @meta in @buffer as a result of performing a
212 * transformation that yields @transbuf. Additional @type specific transform
213 * data is passed to the function as @data.
215 * Implementations should check the @type of the transform and parse
216 * additional type specific fields in @data that should be used to update
217 * the metadata on @transbuf.
219 * Returns: %TRUE if the transform could be performed
222 typedef gboolean (*GstCustomMetaTransformFunction) (GstBuffer *transbuf,
223 GstCustomMeta *meta, GstBuffer *buffer,
224 GQuark type, gpointer data, gpointer user_data);
228 * @api: tag identifying the metadata structure and api
229 * @type: type identifying the implementor of the api
230 * @size: size of the metadata
231 * @init_func: function for initializing the metadata
232 * @free_func: function for freeing the metadata
233 * @transform_func: function for transforming the metadata
235 * The #GstMetaInfo provides information about a specific metadata
238 struct _GstMetaInfo {
243 GstMetaInitFunction init_func;
244 GstMetaFreeFunction free_func;
245 GstMetaTransformFunction transform_func;
247 /* No padding needed, GstMetaInfo is always allocated by GStreamer and is
248 * not subclassable or stack-allocatable, so we can extend it as we please
249 * just like interfaces */
253 GType gst_meta_api_type_register (const gchar *api,
256 gboolean gst_meta_api_type_has_tag (GType api, GQuark tag);
259 const GstMetaInfo * gst_meta_register (GType api, const gchar *impl,
261 GstMetaInitFunction init_func,
262 GstMetaFreeFunction free_func,
263 GstMetaTransformFunction transform_func);
266 const GstMetaInfo * gst_meta_register_custom (const gchar *name, const gchar **tags,
267 GstCustomMetaTransformFunction transform_func,
268 gpointer user_data, GDestroyNotify destroy_data);
271 gboolean gst_meta_info_is_custom (const GstMetaInfo *info);
274 GstStructure * gst_custom_meta_get_structure (GstCustomMeta *meta);
277 gboolean gst_custom_meta_has_name (GstCustomMeta *meta, const gchar * name);
280 const GstMetaInfo * gst_meta_get_info (const gchar * impl);
283 const gchar* const* gst_meta_api_type_get_tags (GType api);
286 guint64 gst_meta_get_seqnum (const GstMeta * meta);
289 gint gst_meta_compare_seqnum (const GstMeta * meta1,
290 const GstMeta * meta2);
292 /* some default tags */
294 GST_API GQuark _gst_meta_tag_memory;
295 GST_API GQuark _gst_meta_tag_memory_reference;
298 * GST_META_TAG_MEMORY:
300 * Metadata tagged with this tag depends on the particular memory
301 * or buffer that it is on.
303 * Deprecated: The GQuarks are not exported by any public API, use
304 * GST_META_TAG_MEMORY_STR instead.
306 #ifndef GST_DISABLE_DEPRECATED
307 #define GST_META_TAG_MEMORY (_gst_meta_tag_memory)
312 #endif /* __GST_META_H__ */