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 /**
  32  * GstMeta:
  33  * @info: pointer to the #GstMetaInfo
  34  *
  35  * Base structure for metadata. Custom metadata will put this structure
  36  * as the first member of their structure.
  37  */
  38 struct _GstMeta {
  39   const GstMetaInfo *info;
  40 };
  41
  42 /**
  43  * GST_META_TRACE_NAME:
  44  *
  45  * The name used for tracing memory allocations.
  46  */
  47 #define GST_META_TRACE_NAME           "GstMeta"
  48
  49 /**
  50  * GstMetaInitFunction:
  51  * @meta: a #GstMeta
  52  * @params: parameters passed to the init function
  53  * @buffer: a #GstBuffer
  54  *
  55  * Function called when @meta is initialized in @buffer.
  56  */
  57 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
  58
  59 /**
  60  * GstMetaFreeFunction:
  61  * @meta: a #GstMeta
  62  * @buffer: a #GstBuffer
  63  *
  64  * Function called when @meta is freed in @buffer.
  65  */
  66 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
  67
  68 /**
  69  * GstMetaCopyFunction:
  70  * @dest: a destination #GstBuffer
  71  * @meta: a #GstMeta
  72  * @buffer: a #GstBuffer
  73  * @offset: an offset
  74  * @size: a size
  75  *
  76  * Function called when the region at @offset and @size in @buffer is copied
  77  * into @dest. The function should update the metadata on @dest using @meta.
  78  */
  79 typedef void (*GstMetaCopyFunction)     (GstBuffer *dest, GstMeta *meta,
  80                                          GstBuffer *buffer, gsize offset, gsize size);
  81 /**
  82  * GstMetaTransformFunction:
  83  * @transbuf: a #GstBuffer
  84  * @meta: a #GstMeta
  85  * @buffer: a #GstBuffer
  86  * @data: transform specific data.
  87  *
  88  * Function called for each @meta in @buffer as a result of performing a
  89  * transformation on @transbuf. Additional type specific transform data
  90  * is passed to the function.
  91  *
  92  * Implementations should check the type of the transform @data and parse
  93  * additional type specific field that should be used to perform the transform.
  94  */
  95 typedef void (*GstMetaTransformFunction) (GstBuffer *transbuf, GstMeta *meta,
  96                                           GstBuffer *buffer, gpointer data);
  97
  98 /**
  99  * GstMetaInfo:
 100  * @api: tag indentifying the metadata structure and api
 101  * @type: type indentifying the implementor of the api
 102  * @size: size of the metadata
 103  * @init_func: function for initializing the metadata
 104  * @free_func: function for freeing the metadata
 105  * @copy_func: function for copying the metadata
 106  * @transform_func: function for transforming the metadata
 107  *
 108  * The #GstMetaInfo provides information about a specific metadata
 109  * structure.
 110  */
 111 struct _GstMetaInfo {
 112   GQuark                     api;
 113   GType                      type;
 114   gsize                      size;
 115
 116   GstMetaInitFunction        init_func;
 117   GstMetaFreeFunction        free_func;
 118   GstMetaCopyFunction        copy_func;
 119   GstMetaTransformFunction   transform_func;
 120
 121   /*< private >*/
 122   gpointer _gst_reserved[GST_PADDING];
 123 };
 124
 125 const GstMetaInfo *  gst_meta_register        (const gchar *api, const gchar *impl,
 126                                                gsize size,
 127                                                GstMetaInitFunction        init_func,
 128                                                GstMetaFreeFunction        free_func,
 129                                                GstMetaCopyFunction        copy_func,
 130                                                GstMetaTransformFunction   transform_func);
 131 const GstMetaInfo *  gst_meta_get_info        (const gchar * impl);
 132
 133 G_END_DECLS
 134
 135 #endif /* __GST_META_H__ */