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 #include <gst/gstbuffer.h> 109 110 /** 111 * GstMetaInitFunction: 112 * @meta: a #GstMeta 113 * @params: parameters passed to the init function 114 * @buffer: a #GstBuffer 115 * 116 * Function called when @meta is initialized in @buffer. 117 */ 118 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer); 119 120 /** 121 * GstMetaFreeFunction: 122 * @meta: a #GstMeta 123 * @buffer: a #GstBuffer 124 * 125 * Function called when @meta is freed in @buffer. 126 */ 127 typedef void (*GstMetaFreeFunction) (GstMeta *meta, GstBuffer *buffer); 128 129 /** 130 * gst_meta_transform_copy: 131 * 132 * GQuark for the "gst-copy" transform. 133 */ 134 135 GST_API GQuark _gst_meta_transform_copy; 136 137 /** 138 * GST_META_TRANSFORM_IS_COPY: 139 * @type: a transform type 140 * 141 * Check if the transform type is a copy transform 142 */ 143 #define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy) 144 145 /** 146 * GstMetaTransformCopy: 147 * @region: %TRUE if only region is copied 148 * @offset: the offset to copy, 0 if @region is %FALSE, otherwise > 0 149 * @size: the size to copy, -1 or the buffer size when @region is %FALSE 150 * 151 * Extra data passed to a "gst-copy" transform #GstMetaTransformFunction. 152 */ 153 typedef struct { 154 gboolean region; 155 gsize offset; 156 gsize size; 157 } GstMetaTransformCopy; 158 159 /** 160 * GstMetaTransformFunction: 161 * @transbuf: a #GstBuffer 162 * @meta: a #GstMeta 163 * @buffer: a #GstBuffer 164 * @type: the transform type 165 * @data: transform specific data. 166 * 167 * Function called for each @meta in @buffer as a result of performing a 168 * transformation on @transbuf. Additional @type specific transform data 169 * is passed to the function as @data. 170 * 171 * Implementations should check the @type of the transform and parse 172 * additional type specific fields in @data that should be used to update 173 * the metadata on @transbuf. 174 * 175 * Returns: %TRUE if the transform could be performed 176 */ 177 typedef gboolean (*GstMetaTransformFunction) (GstBuffer *transbuf, 178 GstMeta *meta, GstBuffer *buffer, 179 GQuark type, gpointer data); 180 181 /** 182 * GstMetaInfo: 183 * @api: tag identifying the metadata structure and api 184 * @type: type identifying the implementor of the api 185 * @size: size of the metadata 186 * @init_func: function for initializing the metadata 187 * @free_func: function for freeing the metadata 188 * @transform_func: function for transforming the metadata 189 * 190 * The #GstMetaInfo provides information about a specific metadata 191 * structure. 192 */ 193 struct _GstMetaInfo { 194 GType api; 195 GType type; 196 gsize size; 197 198 GstMetaInitFunction init_func; 199 GstMetaFreeFunction free_func; 200 GstMetaTransformFunction transform_func; 201 202 /* No padding needed, GstMetaInfo is always allocated by GStreamer and is 203 * not subclassable or stack-allocatable, so we can extend it as we please 204 * just like interfaces */ 205 }; 206 207 GST_API 208 GType gst_meta_api_type_register (const gchar *api, 209 const gchar **tags); 210 GST_API 211 gboolean gst_meta_api_type_has_tag (GType api, GQuark tag); 212 213 GST_API 214 const GstMetaInfo * gst_meta_register (GType api, const gchar *impl, 215 gsize size, 216 GstMetaInitFunction init_func, 217 GstMetaFreeFunction free_func, 218 GstMetaTransformFunction transform_func); 219 GST_API 220 const GstMetaInfo * gst_meta_get_info (const gchar * impl); 221 222 GST_API 223 const gchar* const* gst_meta_api_type_get_tags (GType api); 224 225 GST_API 226 guint64 gst_meta_get_seqnum (const GstMeta * meta); 227 228 GST_API 229 gint gst_meta_compare_seqnum (const GstMeta * meta1, 230 const GstMeta * meta2); 231 232 /* some default tags */ 233 234 GST_API GQuark _gst_meta_tag_memory; 235 236 /** 237 * GST_META_TAG_MEMORY: 238 * 239 * Metadata tagged with this tag depends on the particular memory 240 * or buffer that it is on. 241 * 242 * Deprecated: The GQuarks are not exported by any public API, use 243 * GST_META_TAG_MEMORY_STR instead. 244 */ 245 #ifndef GST_DISABLE_DEPRECATED 246 #define GST_META_TAG_MEMORY (_gst_meta_tag_memory) 247 #endif 248 249 G_END_DECLS 250 251 #endif /* __GST_META_H__ */ 252