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 28 G_BEGIN_DECLS 29 30 typedef struct _GstMeta GstMeta; 31 typedef 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 */ 45 typedef 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 */ 103 struct _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 */ 115 typedef 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 */ 129 typedef 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 */ 138 typedef void (*GstMetaFreeFunction) (GstMeta *meta, GstBuffer *buffer); 139 140 /** 141 * gst_meta_transform_copy: 142 * 143 * GQuark for the "gst-copy" transform. 144 */ 145 146 GST_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 */ 164 typedef 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 */ 188 typedef 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 */ 212 typedef 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 */ 228 struct _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 242 GST_API 243 GType gst_meta_api_type_register (const gchar *api, 244 const gchar **tags); 245 GST_API 246 gboolean gst_meta_api_type_has_tag (GType api, GQuark tag); 247 248 GST_API 249 const 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 255 GST_API 256 const GstMetaInfo * gst_meta_register_custom (const gchar *name, const gchar **tags, 257 GstCustomMetaTransformFunction transform_func, 258 gpointer user_data, GDestroyNotify destroy_data); 259 260 GST_API 261 gboolean gst_meta_info_is_custom (const GstMetaInfo *info); 262 263 GST_API 264 GstStructure * gst_custom_meta_get_structure (GstCustomMeta *meta); 265 266 GST_API 267 gboolean gst_custom_meta_has_name (GstCustomMeta *meta, const gchar * name); 268 269 GST_API 270 const GstMetaInfo * gst_meta_get_info (const gchar * impl); 271 272 GST_API 273 const gchar* const* gst_meta_api_type_get_tags (GType api); 274 275 GST_API 276 guint64 gst_meta_get_seqnum (const GstMeta * meta); 277 278 GST_API 279 gint gst_meta_compare_seqnum (const GstMeta * meta1, 280 const GstMeta * meta2); 281 282 /* some default tags */ 283 284 GST_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 299 G_END_DECLS 300 301 #endif /* __GST_META_H__ */ 302