docs: Fix typos in function/object descriptions
[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., 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 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
38  * @GST_META_FLAG_LOCKED: metadata should not 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   GST_META_FLAG_LOCKED      = (1 << 2),
48
49   GST_META_FLAG_LAST        = (1 << 16)
50 } GstMetaFlags;
51
52 /**
53  * GST_META_FLAGS:
54  * @meta: a #GstMeta.
55  *
56  * A flags word containing #GstMetaFlags flags set on @meta
57  */
58 #define GST_META_FLAGS(meta)  (GST_META_CAST (meta)->flags)
59 /**
60  * GST_META_FLAG_IS_SET:
61  * @meta: a #GstMeta.
62  * @flag: the #GstMetaFlags to check.
63  *
64  * Gives the status of a specific flag on a metadata.
65  */
66 #define GST_META_FLAG_IS_SET(meta,flag)        !!(GST_META_FLAGS (meta) & (flag))
67 /**
68  * GST_META_FLAG_SET:
69  * @meta: a #GstMeta.
70  * @flag: the #GstMetaFlags to set.
71  *
72  * Sets a metadata flag on a metadata.
73  */
74 #define GST_META_FLAG_SET(meta,flag)           (GST_META_FLAGS (meta) |= (flag))
75 /**
76  * GST_META_FLAG_UNSET:
77  * @meta: a #GstMeta.
78  * @flag: the #GstMetaFlags to clear.
79  *
80  * Clears a metadata flag.
81  */
82 #define GST_META_FLAG_UNSET(meta,flag)         (GST_META_FLAGS (meta) &= ~(flag))
83
84 /**
85  * GST_META_TAG_MEMORY_STR:
86  *
87  * This metadata stays relevant as long as memory layout is unchanged.
88  *
89  * Since: 1.2
90  */
91 #define GST_META_TAG_MEMORY_STR "memory"
92
93 /**
94  * GstMeta:
95  * @flags: extra flags for the metadata
96  * @info: pointer to the #GstMetaInfo
97  *
98  * Base structure for metadata. Custom metadata will put this structure
99  * as the first member of their structure.
100  */
101 struct _GstMeta {
102   GstMetaFlags       flags;
103   const GstMetaInfo *info;
104 };
105
106 /**
107  * GstMetaInitFunction:
108  * @meta: a #GstMeta
109  * @params: parameters passed to the init function
110  * @buffer: a #GstBuffer
111  *
112  * Function called when @meta is initialized in @buffer.
113  */
114 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
115
116 /**
117  * GstMetaFreeFunction:
118  * @meta: a #GstMeta
119  * @buffer: a #GstBuffer
120  *
121  * Function called when @meta is freed in @buffer.
122  */
123 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
124
125 /**
126  * gst_meta_transform_copy:
127  *
128  * GQuark for the "gst-copy" transform.
129  */
130 GST_EXPORT GQuark _gst_meta_transform_copy;
131
132 /**
133  * GST_META_TRANSFORM_IS_COPY:
134  * @type: a transform type
135  *
136  * Check if the transform type is a copy transform
137  */
138 #define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy)
139
140 /**
141  * GstMetaTransformCopy:
142  * @region: %TRUE if only region is copied
143  * @offset: the offset to copy, 0 if @region is %FALSE, otherwise > 0
144  * @size: the size to copy, -1 or the buffer size when @region is %FALSE
145  *
146  * Extra data passed to a "gst-copy" transform #GstMetaTransformFunction.
147  */
148 typedef struct {
149   gboolean region;
150   gsize offset;
151   gsize size;
152 } GstMetaTransformCopy;
153
154 /**
155  * GstMetaTransformFunction:
156  * @transbuf: a #GstBuffer
157  * @meta: a #GstMeta
158  * @buffer: a #GstBuffer
159  * @type: the transform type
160  * @data: transform specific data.
161  *
162  * Function called for each @meta in @buffer as a result of performing a
163  * transformation on @transbuf. Additional @type specific transform data
164  * is passed to the function as @data.
165  *
166  * Implementations should check the @type of the transform and parse
167  * additional type specific fields in @data that should be used to update
168  * the metadata on @transbuf.
169  *
170  * Returns: %TRUE if the transform could be performed
171  */
172 typedef gboolean (*GstMetaTransformFunction) (GstBuffer *transbuf,
173                                               GstMeta *meta, GstBuffer *buffer,
174                                               GQuark type, gpointer data);
175
176 /**
177  * GstMetaInfo:
178  * @api: tag identifying the metadata structure and api
179  * @type: type identifying the implementor of the api
180  * @size: size of the metadata
181  * @init_func: function for initializing the metadata
182  * @free_func: function for freeing the metadata
183  * @transform_func: function for transforming the metadata
184  *
185  * The #GstMetaInfo provides information about a specific metadata
186  * structure.
187  */
188 struct _GstMetaInfo {
189   GType                      api;
190   GType                      type;
191   gsize                      size;
192
193   GstMetaInitFunction        init_func;
194   GstMetaFreeFunction        free_func;
195   GstMetaTransformFunction   transform_func;
196
197   /*< private >*/
198   gpointer _gst_reserved[GST_PADDING];
199 };
200
201 GType                gst_meta_api_type_register (const gchar *api,
202                                                  const gchar **tags);
203 gboolean             gst_meta_api_type_has_tag  (GType api, GQuark tag);
204
205 const GstMetaInfo *  gst_meta_register          (GType api, const gchar *impl,
206                                                  gsize size,
207                                                  GstMetaInitFunction      init_func,
208                                                  GstMetaFreeFunction      free_func,
209                                                  GstMetaTransformFunction transform_func);
210 const GstMetaInfo *  gst_meta_get_info          (const gchar * impl);
211 const gchar* const*  gst_meta_api_type_get_tags (GType api);
212
213 /* some default tags */
214 GST_EXPORT GQuark _gst_meta_tag_memory;
215
216 /**
217  * GST_META_TAG_MEMORY:
218  *
219  * Metadata tagged with this tag depends on the particular memory
220  * or buffer that it is on.
221  *
222  * Deprecated: The GQuarks are not exported by any public API, use
223  *   GST_META_TAG_MEMORY_STR instead.
224  */
225 #define GST_META_TAG_MEMORY (_gst_meta_tag_memory)
226
227 G_END_DECLS
228
229 #endif /* __GST_META_H__ */