Merge branch 'master' into 0.11
[platform/upstream/gstreamer.git] / gst / gstmeta.h
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., 59 Temple Place - Suite 330,
19  * Boston, MA 02111-1307, USA.
20  */
21
22
23 #ifndef __GST_META_H__
24 #define __GST_META_H__
25
26 G_BEGIN_DECLS
27
28 typedef struct _GstMeta GstMeta;
29 typedef struct _GstMetaInfo GstMetaInfo;
30
31 #define GST_META_CAST(meta)   ((GstMeta *)(meta))
32
33 /**
34  * GstMetaFlags:
35  * @GST_META_FLAG_NONE: no flags
36  * @GST_META_FLAG_READONLY: metadata should not be modified
37  * @GST_META_FLAG_POOLED: metadata is managed by a bufferpool and should not
38  *    be removed
39  * @GST_META_FLAG_LAST: additional flags can be added starting from this flag.
40  *
41  * Extra metadata flags.
42  */
43 typedef enum {
44   GST_META_FLAG_NONE        = 0,
45   GST_META_FLAG_READONLY    = (1 << 0),
46   GST_META_FLAG_POOLED      = (1 << 1),
47
48   GST_META_FLAG_LAST        = (1 << 16)
49 } GstMetaFlags;
50
51 /**
52  * GST_META_FLAGS:
53  * @meta: a #GstMeta.
54  *
55  * A flags word containing #GstMetaFlag flags set on @meta
56  */
57 #define GST_META_FLAGS(meta)  (GST_META_CAST (meta)->flags)
58 /**
59  * GST_META_FLAG_IS_SET:
60  * @meta: a #GstMeta.
61  * @flag: the #GstMetaFlag to check.
62  *
63  * Gives the status of a specific flag on a metadata.
64  */
65 #define GST_META_FLAG_IS_SET(meta,flag)        !!(GST_META_FLAGS (meta) & (flag))
66 /**
67  * GST_META_FLAG_SET:
68  * @meta: a #GstMeta.
69  * @flag: the #GstMetaFlag to set.
70  *
71  * Sets a metadata flag on a metadata.
72  */
73 #define GST_META_FLAG_SET(meta,flag)           (GST_META_FLAGS (meta) |= (flag))
74 /**
75  * GST_META_FLAG_UNSET:
76  * @meta: a #GstMeta.
77  * @flag: the #GstMetaFlag to clear.
78  *
79  * Clears a metadata flag.
80  */
81 #define GST_META_FLAG_UNSET(meta,flag)         (GST_META_FLAGS (meta) &= ~(flag))
82
83 /**
84  * GstMeta:
85  * @flags: extra flags for the metadata
86  * @info: pointer to the #GstMetaInfo
87  *
88  * Base structure for metadata. Custom metadata will put this structure
89  * as the first member of their structure.
90  */
91 struct _GstMeta {
92   GstMetaFlags       flags;
93   const GstMetaInfo *info;
94 };
95
96 /**
97  * GST_META_TRACE_NAME:
98  *
99  * The name used for tracing memory allocations.
100  */
101 #define GST_META_TRACE_NAME           "GstMeta"
102
103 /**
104  * GstMetaInitFunction:
105  * @meta: a #GstMeta
106  * @params: parameters passed to the init function
107  * @buffer: a #GstBuffer
108  *
109  * Function called when @meta is initialized in @buffer.
110  */
111 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
112
113 /**
114  * GstMetaFreeFunction:
115  * @meta: a #GstMeta
116  * @buffer: a #GstBuffer
117  *
118  * Function called when @meta is freed in @buffer.
119  */
120 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
121
122 /**
123  * GstMetaCopyFunction:
124  * @dest: a destination #GstBuffer
125  * @meta: a #GstMeta
126  * @buffer: a #GstBuffer
127  * @offset: an offset
128  * @size: a size
129  *
130  * Function called when the region at @offset and @size in @buffer is copied
131  * into @dest. The function should update the metadata on @dest using @meta.
132  */
133 typedef void (*GstMetaCopyFunction)     (GstBuffer *dest, GstMeta *meta,
134                                          GstBuffer *buffer, gsize offset, gsize size);
135 /**
136  * GstMetaTransformFunction:
137  * @transbuf: a #GstBuffer
138  * @meta: a #GstMeta
139  * @buffer: a #GstBuffer
140  * @data: transform specific data.
141  *
142  * Function called for each @meta in @buffer as a result of performing a
143  * transformation on @transbuf. Additional type specific transform data
144  * is passed to the function.
145  *
146  * Implementations should check the type of the transform @data and parse
147  * additional type specific field that should be used to perform the transform.
148  */
149 typedef void (*GstMetaTransformFunction) (GstBuffer *transbuf, GstMeta *meta,
150                                           GstBuffer *buffer, gpointer data);
151
152 /**
153  * GstMetaInfo:
154  * @api: tag indentifying the metadata structure and api
155  * @type: type indentifying the implementor of the api
156  * @size: size of the metadata
157  * @init_func: function for initializing the metadata
158  * @free_func: function for freeing the metadata
159  * @copy_func: function for copying the metadata
160  * @transform_func: function for transforming the metadata
161  *
162  * The #GstMetaInfo provides information about a specific metadata
163  * structure.
164  */
165 struct _GstMetaInfo {
166   GQuark                     api;
167   GType                      type;
168   gsize                      size;
169
170   GstMetaInitFunction        init_func;
171   GstMetaFreeFunction        free_func;
172   GstMetaCopyFunction        copy_func;
173   GstMetaTransformFunction   transform_func;
174
175   /*< private >*/
176   gpointer _gst_reserved[GST_PADDING];
177 };
178
179 const GstMetaInfo *  gst_meta_register        (const gchar *api, const gchar *impl,
180                                                gsize size,
181                                                GstMetaInitFunction        init_func,
182                                                GstMetaFreeFunction        free_func,
183                                                GstMetaCopyFunction        copy_func,
184                                                GstMetaTransformFunction   transform_func);
185 const GstMetaInfo *  gst_meta_get_info        (const gchar * impl);
186
187 G_END_DECLS
188
189 #endif /* __GST_META_H__ */