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 and should not
  38  *    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
  48   GST_META_FLAG_LAST        = (1 << 16)
  49 } GstMetaFlags;
  50
  51 /**
  52  * GST_META_FLAGS:
  53  * @meta: a #GstMeta.
  54  *
  55  * A flags word containing #GstMetaFlag flags set on @meta
  56  */
  57 #define GST_META_FLAGS(meta)  (GST_META_CAST (meta)->flags)
  58 /**
  59  * GST_META_FLAG_IS_SET:
  60  * @meta: a #GstMeta.
  61  * @flag: the #GstMetaFlag to check.
  62  *
  63  * Gives the status of a specific flag on a metadata.
  64  */
  65 #define GST_META_FLAG_IS_SET(meta,flag)        !!(GST_META_FLAGS (meta) & (flag))
  66 /**
  67  * GST_META_FLAG_SET:
  68  * @meta: a #GstMeta.
  69  * @flag: the #GstMetaFlag to set.
  70  *
  71  * Sets a metadata flag on a metadata.
  72  */
  73 #define GST_META_FLAG_SET(meta,flag)           (GST_META_FLAGS (meta) |= (flag))
  74 /**
  75  * GST_META_FLAG_UNSET:
  76  * @meta: a #GstMeta.
  77  * @flag: the #GstMetaFlag to clear.
  78  *
  79  * Clears a metadata flag.
  80  */
  81 #define GST_META_FLAG_UNSET(meta,flag)         (GST_META_FLAGS (meta) &= ~(flag))
  82
  83 /**
  84  * GstMeta:
  85  * @flags: extra flags for the metadata
  86  * @info: pointer to the #GstMetaInfo
  87  *
  88  * Base structure for metadata. Custom metadata will put this structure
  89  * as the first member of their structure.
  90  */
  91 struct _GstMeta {
  92   GstMetaFlags       flags;
  93   const GstMetaInfo *info;
  94 };
  95
  96 /**
  97  * GST_META_TRACE_NAME:
  98  *
  99  * The name used for tracing memory allocations.
 100  */
 101 #define GST_META_TRACE_NAME           "GstMeta"
 102
 103 /**
 104  * GstMetaInitFunction:
 105  * @meta: a #GstMeta
 106  * @params: parameters passed to the init function
 107  * @buffer: a #GstBuffer
 108  *
 109  * Function called when @meta is initialized in @buffer.
 110  */
 111 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
 112
 113 /**
 114  * GstMetaFreeFunction:
 115  * @meta: a #GstMeta
 116  * @buffer: a #GstBuffer
 117  *
 118  * Function called when @meta is freed in @buffer.
 119  */
 120 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
 121
 122 /**
 123  * GstMetaCopyFunction:
 124  * @dest: a destination #GstBuffer
 125  * @meta: a #GstMeta
 126  * @buffer: a #GstBuffer
 127  * @offset: an offset
 128  * @size: a size
 129  *
 130  * Function called when the region at @offset and @size in @buffer is copied
 131  * into @dest. The function should update the metadata on @dest using @meta.
 132  */
 133 typedef void (*GstMetaCopyFunction)     (GstBuffer *dest, GstMeta *meta,
 134                                          GstBuffer *buffer, gsize offset, gsize size);
 135 /**
 136  * GstMetaTransformFunction:
 137  * @transbuf: a #GstBuffer
 138  * @meta: a #GstMeta
 139  * @buffer: a #GstBuffer
 140  * @data: transform specific data.
 141  *
 142  * Function called for each @meta in @buffer as a result of performing a
 143  * transformation on @transbuf. Additional type specific transform data
 144  * is passed to the function.
 145  *
 146  * Implementations should check the type of the transform @data and parse
 147  * additional type specific field that should be used to perform the transform.
 148  */
 149 typedef void (*GstMetaTransformFunction) (GstBuffer *transbuf, GstMeta *meta,
 150                                           GstBuffer *buffer, gpointer data);
 151
 152 /**
 153  * GstMetaInfo:
 154  * @api: tag indentifying the metadata structure and api
 155  * @type: type indentifying the implementor of the api
 156  * @size: size of the metadata
 157  * @init_func: function for initializing the metadata
 158  * @free_func: function for freeing the metadata
 159  * @copy_func: function for copying the metadata
 160  * @transform_func: function for transforming the metadata
 161  *
 162  * The #GstMetaInfo provides information about a specific metadata
 163  * structure.
 164  */
 165 struct _GstMetaInfo {
 166   GQuark                     api;
 167   GType                      type;
 168   gsize                      size;
 169
 170   GstMetaInitFunction        init_func;
 171   GstMetaFreeFunction        free_func;
 172   GstMetaCopyFunction        copy_func;
 173   GstMetaTransformFunction   transform_func;
 174
 175   /*< private >*/
 176   gpointer _gst_reserved[GST_PADDING];
 177 };
 178
 179 const GstMetaInfo *  gst_meta_register        (const gchar *api, const gchar *impl,
 180                                                gsize size,
 181                                                GstMetaInitFunction        init_func,
 182                                                GstMetaFreeFunction        free_func,
 183                                                GstMetaCopyFunction        copy_func,
 184                                                GstMetaTransformFunction   transform_func);
 185 const GstMetaInfo *  gst_meta_get_info        (const gchar * impl);
 186
 187 G_END_DECLS
 188
 189 #endif /* __GST_META_H__ */