remove TRACE_NAME from headers
[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  * GstMetaInitFunction:
98  * @meta: a #GstMeta
99  * @params: parameters passed to the init function
100  * @buffer: a #GstBuffer
101  *
102  * Function called when @meta is initialized in @buffer.
103  */
104 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
105
106 /**
107  * GstMetaFreeFunction:
108  * @meta: a #GstMeta
109  * @buffer: a #GstBuffer
110  *
111  * Function called when @meta is freed in @buffer.
112  */
113 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
114
115 /**
116  * GstMetaCopyFunction:
117  * @dest: a destination #GstBuffer
118  * @meta: a #GstMeta
119  * @buffer: a #GstBuffer
120  * @offset: an offset
121  * @size: a size
122  *
123  * Function called when the region at @offset and @size in @buffer is copied
124  * into @dest. The function should update the metadata on @dest using @meta.
125  */
126 typedef void (*GstMetaCopyFunction)     (GstBuffer *dest, GstMeta *meta,
127                                          GstBuffer *buffer, gsize offset, gsize size);
128 /**
129  * GstMetaTransformFunction:
130  * @transbuf: a #GstBuffer
131  * @meta: a #GstMeta
132  * @buffer: a #GstBuffer
133  * @data: transform specific data.
134  *
135  * Function called for each @meta in @buffer as a result of performing a
136  * transformation on @transbuf. Additional type specific transform data
137  * is passed to the function.
138  *
139  * Implementations should check the type of the transform @data and parse
140  * additional type specific field that should be used to perform the transform.
141  */
142 typedef void (*GstMetaTransformFunction) (GstBuffer *transbuf, GstMeta *meta,
143                                           GstBuffer *buffer, gpointer data);
144
145 /**
146  * GstMetaInfo:
147  * @api: tag indentifying the metadata structure and api
148  * @type: type indentifying the implementor of the api
149  * @size: size of the metadata
150  * @init_func: function for initializing the metadata
151  * @free_func: function for freeing the metadata
152  * @copy_func: function for copying the metadata
153  * @transform_func: function for transforming the metadata
154  *
155  * The #GstMetaInfo provides information about a specific metadata
156  * structure.
157  */
158 struct _GstMetaInfo {
159   GQuark                     api;
160   GType                      type;
161   gsize                      size;
162
163   GstMetaInitFunction        init_func;
164   GstMetaFreeFunction        free_func;
165   GstMetaCopyFunction        copy_func;
166   GstMetaTransformFunction   transform_func;
167
168   /*< private >*/
169   gpointer _gst_reserved[GST_PADDING];
170 };
171
172 const GstMetaInfo *  gst_meta_register        (const gchar *api, const gchar *impl,
173                                                gsize size,
174                                                GstMetaInitFunction        init_func,
175                                                GstMetaFreeFunction        free_func,
176                                                GstMetaCopyFunction        copy_func,
177                                                GstMetaTransformFunction   transform_func);
178 const GstMetaInfo *  gst_meta_get_info        (const gchar * impl);
179
180 G_END_DECLS
181
182 #endif /* __GST_META_H__ */