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
  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  * GstMeta:
  86  * @flags: extra flags for the metadata
  87  * @info: pointer to the #GstMetaInfo
  88  *
  89  * Base structure for metadata. Custom metadata will put this structure
  90  * as the first member of their structure.
  91  */
  92 struct _GstMeta {
  93   GstMetaFlags       flags;
  94   const GstMetaInfo *info;
  95 };
  96
  97 /**
  98  * GstMetaInitFunction:
  99  * @meta: a #GstMeta
 100  * @params: parameters passed to the init function
 101  * @buffer: a #GstBuffer
 102  *
 103  * Function called when @meta is initialized in @buffer.
 104  */
 105 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
 106
 107 /**
 108  * GstMetaFreeFunction:
 109  * @meta: a #GstMeta
 110  * @buffer: a #GstBuffer
 111  *
 112  * Function called when @meta is freed in @buffer.
 113  */
 114 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
 115
 116 /**
 117  * gst_meta_transform_copy:
 118  *
 119  * GQuark for the "gst-copy" transform.
 120  */
 121 GST_EXPORT GQuark _gst_meta_transform_copy;
 122
 123 /**
 124  * GST_META_TRANSFORM_IS_COPY:
 125  * @type: a transform type
 126  *
 127  * Check if the transform type is a copy transform
 128  */
 129 #define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy)
 130
 131 /**
 132  * GstMetaTransformCopy:
 133  * @region: %TRUE if only region is copied
 134  * @offset: the offset to copy, 0 if @region is %FALSE, otherwise > 0
 135  * @size: the size to copy, -1 or the buffer size when @region is %FALSE
 136  *
 137  * Extra data passed to a "gst-copy" transform #GstMetaTransformFunction.
 138  */
 139 typedef struct {
 140   gboolean region;
 141   gsize offset;
 142   gsize size;
 143 } GstMetaTransformCopy;
 144
 145 /**
 146  * GstMetaTransformFunction:
 147  * @transbuf: a #GstBuffer
 148  * @meta: a #GstMeta
 149  * @buffer: a #GstBuffer
 150  * @type: the transform type
 151  * @data: transform specific data.
 152  *
 153  * Function called for each @meta in @buffer as a result of performing a
 154  * transformation on @transbuf. Additional @type specific transform data
 155  * is passed to the function as @data.
 156  *
 157  * Implementations should check the @type of the transform and parse
 158  * additional type specific fields in @data that should be used to update
 159  * the metadata on @transbuf.
 160  *
 161  * Returns: %TRUE if the transform could be performed
 162  */
 163 typedef gboolean (*GstMetaTransformFunction) (GstBuffer *transbuf,
 164                                               GstMeta *meta, GstBuffer *buffer,
 165                                               GQuark type, gpointer data);
 166
 167 /**
 168  * GstMetaInfo:
 169  * @api: tag indentifying the metadata structure and api
 170  * @type: type indentifying the implementor of the api
 171  * @size: size of the metadata
 172  * @init_func: function for initializing the metadata
 173  * @free_func: function for freeing the metadata
 174  * @transform_func: function for transforming the metadata
 175  *
 176  * The #GstMetaInfo provides information about a specific metadata
 177  * structure.
 178  */
 179 struct _GstMetaInfo {
 180   GType                      api;
 181   GType                      type;
 182   gsize                      size;
 183
 184   GstMetaInitFunction        init_func;
 185   GstMetaFreeFunction        free_func;
 186   GstMetaTransformFunction   transform_func;
 187
 188   /*< private >*/
 189   gpointer _gst_reserved[GST_PADDING];
 190 };
 191
 192 GType                gst_meta_api_type_register (const gchar *api,
 193                                                  const gchar **tags);
 194 gboolean             gst_meta_api_type_has_tag  (GType api, GQuark tag);
 195
 196 const GstMetaInfo *  gst_meta_register          (GType api, const gchar *impl,
 197                                                  gsize size,
 198                                                  GstMetaInitFunction      init_func,
 199                                                  GstMetaFreeFunction      free_func,
 200                                                  GstMetaTransformFunction transform_func);
 201 const GstMetaInfo *  gst_meta_get_info          (const gchar * impl);
 202
 203 /* some default tags */
 204 GST_EXPORT GQuark _gst_meta_tag_memory;
 205
 206 /**
 207  * GST_META_TAG_MEMORY:
 208  *
 209  * Metadata tagged with this tag depends on the particular memory
 210  * or buffer that it is on.
 211  */
 212 #define GST_META_TAG_MEMORY (_gst_meta_tag_memory)
 213
 214 G_END_DECLS
 215
 216 #endif /* __GST_META_H__ */