subprojects/gstreamer/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 #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  * In hindsight, this tag should have been called "memory-layout".
  91  *
  92  * Since: 1.2
  93  */
  94 #define GST_META_TAG_MEMORY_STR "memory"
  95
  96 /**
  97  * GST_META_TAG_MEMORY_REFERENCE_STR:
  98  *
  99  * This metadata stays relevant until a deep copy is made.
 100  *
 101  * Since: 1.20.4
 102  */
 103 #define GST_META_TAG_MEMORY_REFERENCE_STR "memory-reference"
 104
 105 /**
 106  * GstMeta:
 107  * @flags: extra flags for the metadata
 108  * @info: pointer to the #GstMetaInfo
 109  *
 110  * Base structure for metadata. Custom metadata will put this structure
 111  * as the first member of their structure.
 112  */
 113 struct _GstMeta {
 114   GstMetaFlags       flags;
 115   const GstMetaInfo *info;
 116 };
 117
 118 /**
 119  * GstCustomMeta:
 120  *
 121  * Simple typing wrapper around #GstMeta
 122  *
 123  * Since: 1.20
 124  */
 125 typedef struct {
 126   GstMeta meta;
 127 } GstCustomMeta;
 128
 129 #include <gst/gstbuffer.h>
 130
 131 /**
 132  * GstMetaInitFunction:
 133  * @meta: a #GstMeta
 134  * @params: parameters passed to the init function
 135  * @buffer: a #GstBuffer
 136  *
 137  * Function called when @meta is initialized in @buffer.
 138  */
 139 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
 140
 141 /**
 142  * GstMetaFreeFunction:
 143  * @meta: a #GstMeta
 144  * @buffer: a #GstBuffer
 145  *
 146  * Function called when @meta is freed in @buffer.
 147  */
 148 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
 149
 150 /**
 151  * gst_meta_transform_copy:
 152  *
 153  * GQuark for the "gst-copy" transform.
 154  */
 155
 156 GST_API GQuark _gst_meta_transform_copy;
 157
 158 /**
 159  * GST_META_TRANSFORM_IS_COPY:
 160  * @type: a transform type
 161  *
 162  * Check if the transform type is a copy transform
 163  */
 164 #define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy)
 165
 166 /**
 167  * GstMetaTransformCopy:
 168  * @region: %TRUE if only region is copied
 169  * @offset: the offset to copy, 0 if @region is %FALSE, otherwise > 0
 170  * @size: the size to copy, -1 or the buffer size when @region is %FALSE
 171  *
 172  * Extra data passed to a "gst-copy" transform #GstMetaTransformFunction.
 173  */
 174 typedef struct {
 175   gboolean region;
 176   gsize offset;
 177   gsize size;
 178 } GstMetaTransformCopy;
 179
 180 /**
 181  * GstMetaTransformFunction:
 182  * @transbuf: a #GstBuffer
 183  * @meta: a #GstMeta
 184  * @buffer: a #GstBuffer
 185  * @type: the transform type
 186  * @data: transform specific data.
 187  *
 188  * Function called for each @meta in @buffer as a result of performing a
 189  * transformation on @transbuf. Additional @type specific transform data
 190  * is passed to the function as @data.
 191  *
 192  * Implementations should check the @type of the transform and parse
 193  * additional type specific fields in @data that should be used to update
 194  * the metadata on @transbuf.
 195  *
 196  * Returns: %TRUE if the transform could be performed
 197  */
 198 typedef gboolean (*GstMetaTransformFunction) (GstBuffer *transbuf,
 199                                               GstMeta *meta, GstBuffer *buffer,
 200                                               GQuark type, gpointer data);
 201
 202 /**
 203  * GstCustomMetaTransformFunction:
 204  * @transbuf: a #GstBuffer
 205  * @meta: a #GstCustomMeta
 206  * @buffer: a #GstBuffer
 207  * @type: the transform type
 208  * @data: transform specific data.
 209  * @user_data: user data passed when registering the meta
 210  *
 211  * Function called for each @meta in @buffer as a result of performing a
 212  * transformation that yields @transbuf. Additional @type specific transform
 213  * data is passed to the function as @data.
 214  *
 215  * Implementations should check the @type of the transform and parse
 216  * additional type specific fields in @data that should be used to update
 217  * the metadata on @transbuf.
 218  *
 219  * Returns: %TRUE if the transform could be performed
 220  * Since: 1.20
 221  */
 222 typedef gboolean (*GstCustomMetaTransformFunction) (GstBuffer *transbuf,
 223                                                     GstCustomMeta *meta, GstBuffer *buffer,
 224                                                     GQuark type, gpointer data, gpointer user_data);
 225
 226 /**
 227  * GstMetaInfo:
 228  * @api: tag identifying the metadata structure and api
 229  * @type: type identifying the implementor of the api
 230  * @size: size of the metadata
 231  * @init_func: function for initializing the metadata
 232  * @free_func: function for freeing the metadata
 233  * @transform_func: function for transforming the metadata
 234  *
 235  * The #GstMetaInfo provides information about a specific metadata
 236  * structure.
 237  */
 238 struct _GstMetaInfo {
 239   GType                      api;
 240   GType                      type;
 241   gsize                      size;
 242
 243   GstMetaInitFunction        init_func;
 244   GstMetaFreeFunction        free_func;
 245   GstMetaTransformFunction   transform_func;
 246
 247   /* No padding needed, GstMetaInfo is always allocated by GStreamer and is
 248    * not subclassable or stack-allocatable, so we can extend it as we please
 249    * just like interfaces */
 250 };
 251
 252 GST_API
 253 GType                gst_meta_api_type_register (const gchar *api,
 254                                                  const gchar **tags);
 255 GST_API
 256 gboolean             gst_meta_api_type_has_tag  (GType api, GQuark tag);
 257
 258 GST_API
 259 const GstMetaInfo *  gst_meta_register          (GType api, const gchar *impl,
 260                                                  gsize size,
 261                                                  GstMetaInitFunction      init_func,
 262                                                  GstMetaFreeFunction      free_func,
 263                                                  GstMetaTransformFunction transform_func);
 264
 265 GST_API
 266 const GstMetaInfo *  gst_meta_register_custom   (const gchar *name, const gchar **tags,
 267                                                  GstCustomMetaTransformFunction transform_func,
 268                                                  gpointer user_data, GDestroyNotify destroy_data);
 269
 270 GST_API
 271 gboolean             gst_meta_info_is_custom    (const GstMetaInfo *info);
 272
 273 GST_API
 274 GstStructure *       gst_custom_meta_get_structure (GstCustomMeta *meta);
 275
 276 GST_API
 277 gboolean             gst_custom_meta_has_name (GstCustomMeta *meta, const gchar * name);
 278
 279 GST_API
 280 const GstMetaInfo *  gst_meta_get_info          (const gchar * impl);
 281
 282 GST_API
 283 const gchar* const*  gst_meta_api_type_get_tags (GType api);
 284
 285 GST_API
 286 guint64              gst_meta_get_seqnum        (const GstMeta * meta);
 287
 288 GST_API
 289 gint                 gst_meta_compare_seqnum    (const GstMeta * meta1,
 290                                                  const GstMeta * meta2);
 291
 292 /* some default tags */
 293
 294 GST_API GQuark _gst_meta_tag_memory;
 295 GST_API GQuark _gst_meta_tag_memory_reference;
 296
 297 /**
 298  * GST_META_TAG_MEMORY:
 299  *
 300  * Metadata tagged with this tag depends on the particular memory
 301  * or buffer that it is on.
 302  *
 303  * Deprecated: The GQuarks are not exported by any public API, use
 304  *   GST_META_TAG_MEMORY_STR instead.
 305  */
 306 #ifndef GST_DISABLE_DEPRECATED
 307 #define GST_META_TAG_MEMORY (_gst_meta_tag_memory)
 308 #endif
 309
 310 G_END_DECLS
 311
 312 #endif /* __GST_META_H__ */