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 #include <gst/gstbuffer.h>
  28
  29 G_BEGIN_DECLS
  30
  31 typedef struct _GstMeta GstMeta;
  32 typedef struct _GstMetaInfo GstMetaInfo;
  33
  34 #define GST_META_CAST(meta)   ((GstMeta *)(meta))
  35
  36 /**
  37  * GstMetaFlags:
  38  * @GST_META_FLAG_NONE: no flags
  39  * @GST_META_FLAG_READONLY: metadata should not be modified
  40  * @GST_META_FLAG_POOLED: metadata is managed by a bufferpool
  41  * @GST_META_FLAG_LOCKED: metadata should not be removed
  42  * @GST_META_FLAG_LAST: additional flags can be added starting from this flag.
  43  *
  44  * Extra metadata flags.
  45  */
  46 typedef enum {
  47   GST_META_FLAG_NONE        = 0,
  48   GST_META_FLAG_READONLY    = (1 << 0),
  49   GST_META_FLAG_POOLED      = (1 << 1),
  50   GST_META_FLAG_LOCKED      = (1 << 2),
  51
  52   GST_META_FLAG_LAST        = (1 << 16)
  53 } GstMetaFlags;
  54
  55 /**
  56  * GST_META_FLAGS:
  57  * @meta: a #GstMeta.
  58  *
  59  * A flags word containing #GstMetaFlags flags set on @meta
  60  */
  61 #define GST_META_FLAGS(meta)  (GST_META_CAST (meta)->flags)
  62 /**
  63  * GST_META_FLAG_IS_SET:
  64  * @meta: a #GstMeta.
  65  * @flag: the #GstMetaFlags to check.
  66  *
  67  * Gives the status of a specific flag on a metadata.
  68  */
  69 #define GST_META_FLAG_IS_SET(meta,flag)        !!(GST_META_FLAGS (meta) & (flag))
  70 /**
  71  * GST_META_FLAG_SET:
  72  * @meta: a #GstMeta.
  73  * @flag: the #GstMetaFlags to set.
  74  *
  75  * Sets a metadata flag on a metadata.
  76  */
  77 #define GST_META_FLAG_SET(meta,flag)           (GST_META_FLAGS (meta) |= (flag))
  78 /**
  79  * GST_META_FLAG_UNSET:
  80  * @meta: a #GstMeta.
  81  * @flag: the #GstMetaFlags to clear.
  82  *
  83  * Clears a metadata flag.
  84  */
  85 #define GST_META_FLAG_UNSET(meta,flag)         (GST_META_FLAGS (meta) &= ~(flag))
  86
  87 /**
  88  * GST_META_TAG_MEMORY_STR:
  89  *
  90  * This metadata stays relevant as long as memory layout is unchanged.
  91  *
  92  * Since: 1.2
  93  */
  94 #define GST_META_TAG_MEMORY_STR "memory"
  95
  96 /**
  97  * GstMeta:
  98  * @flags: extra flags for the metadata
  99  * @info: pointer to the #GstMetaInfo
 100  *
 101  * Base structure for metadata. Custom metadata will put this structure
 102  * as the first member of their structure.
 103  */
 104 struct _GstMeta {
 105   GstMetaFlags       flags;
 106   const GstMetaInfo *info;
 107 };
 108
 109 /**
 110  * GstMetaInitFunction:
 111  * @meta: a #GstMeta
 112  * @params: parameters passed to the init function
 113  * @buffer: a #GstBuffer
 114  *
 115  * Function called when @meta is initialized in @buffer.
 116  */
 117 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
 118
 119 /**
 120  * GstMetaFreeFunction:
 121  * @meta: a #GstMeta
 122  * @buffer: a #GstBuffer
 123  *
 124  * Function called when @meta is freed in @buffer.
 125  */
 126 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
 127
 128 /**
 129  * gst_meta_transform_copy:
 130  *
 131  * GQuark for the "gst-copy" transform.
 132  */
 133 GST_EXPORT GQuark _gst_meta_transform_copy;
 134
 135 /**
 136  * GST_META_TRANSFORM_IS_COPY:
 137  * @type: a transform type
 138  *
 139  * Check if the transform type is a copy transform
 140  */
 141 #define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy)
 142
 143 /**
 144  * GstMetaTransformCopy:
 145  * @region: %TRUE if only region is copied
 146  * @offset: the offset to copy, 0 if @region is %FALSE, otherwise > 0
 147  * @size: the size to copy, -1 or the buffer size when @region is %FALSE
 148  *
 149  * Extra data passed to a "gst-copy" transform #GstMetaTransformFunction.
 150  */
 151 typedef struct {
 152   gboolean region;
 153   gsize offset;
 154   gsize size;
 155 } GstMetaTransformCopy;
 156
 157 /**
 158  * GstMetaTransformFunction:
 159  * @transbuf: a #GstBuffer
 160  * @meta: a #GstMeta
 161  * @buffer: a #GstBuffer
 162  * @type: the transform type
 163  * @data: transform specific data.
 164  *
 165  * Function called for each @meta in @buffer as a result of performing a
 166  * transformation on @transbuf. Additional @type specific transform data
 167  * is passed to the function as @data.
 168  *
 169  * Implementations should check the @type of the transform and parse
 170  * additional type specific fields in @data that should be used to update
 171  * the metadata on @transbuf.
 172  *
 173  * Returns: %TRUE if the transform could be performed
 174  */
 175 typedef gboolean (*GstMetaTransformFunction) (GstBuffer *transbuf,
 176                                               GstMeta *meta, GstBuffer *buffer,
 177                                               GQuark type, gpointer data);
 178
 179 /**
 180  * GstMetaInfo:
 181  * @api: tag identifying the metadata structure and api
 182  * @type: type identifying the implementor of the api
 183  * @size: size of the metadata
 184  * @init_func: function for initializing the metadata
 185  * @free_func: function for freeing the metadata
 186  * @transform_func: function for transforming the metadata
 187  *
 188  * The #GstMetaInfo provides information about a specific metadata
 189  * structure.
 190  */
 191 struct _GstMetaInfo {
 192   GType                      api;
 193   GType                      type;
 194   gsize                      size;
 195
 196   GstMetaInitFunction        init_func;
 197   GstMetaFreeFunction        free_func;
 198   GstMetaTransformFunction   transform_func;
 199
 200   /*< private >*/
 201   gpointer _gst_reserved[GST_PADDING];
 202 };
 203
 204 GType                gst_meta_api_type_register (const gchar *api,
 205                                                  const gchar **tags);
 206 gboolean             gst_meta_api_type_has_tag  (GType api, GQuark tag);
 207
 208 const GstMetaInfo *  gst_meta_register          (GType api, const gchar *impl,
 209                                                  gsize size,
 210                                                  GstMetaInitFunction      init_func,
 211                                                  GstMetaFreeFunction      free_func,
 212                                                  GstMetaTransformFunction transform_func);
 213 const GstMetaInfo *  gst_meta_get_info          (const gchar * impl);
 214 const gchar* const*  gst_meta_api_type_get_tags (GType api);
 215
 216 /* some default tags */
 217 GST_EXPORT GQuark _gst_meta_tag_memory;
 218
 219 /**
 220  * GST_META_TAG_MEMORY:
 221  *
 222  * Metadata tagged with this tag depends on the particular memory
 223  * or buffer that it is on.
 224  *
 225  * Deprecated: The GQuarks are not exported by any public API, use
 226  *   GST_META_TAG_MEMORY_STR instead.
 227  */
 228 #ifndef GST_DISABLE_DEPRECATED
 229 #define GST_META_TAG_MEMORY (_gst_meta_tag_memory)
 230 #endif
 231
 232 G_END_DECLS
 233
 234 #endif /* __GST_META_H__ */