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  * @buffer: a #GstBuffer
  53  *
  54  * Function called when @meta is initialized in @buffer.
  55  */
  56 typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
  57
  58 /**
  59  * GstMetaFreeFunction:
  60  * @meta: a #GstMeta
  61  * @buffer: a #GstBuffer
  62  *
  63  * Function called when @meta is freed in @buffer.
  64  */
  65 typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
  66
  67 typedef void (*GstMetaCopyFunction)     (GstBuffer *dest, GstMeta *meta,
  68                                          GstBuffer *buffer, gsize offset, gsize size);
  69 /**
  70  * GstMetaTransformFunction:
  71  * @transbuf: a #GstBuffer
  72  * @meta: a #GstMeta
  73  * @buffer: a #GstBuffer
  74  * @data: transform specific data.
  75  *
  76  * Function called for each @meta in @buffer as a result of performing a
  77  * transformation on @transbuf. Additional type specific transform data
  78  * is passed to the function.
  79  *
  80  * Implementations should check the type of the transform @data and parse
  81  * additional type specific field that should be used to perform the transform.
  82  */
  83 typedef void (*GstMetaTransformFunction) (GstBuffer *transbuf, GstMeta *meta,
  84                                           GstBuffer *buffer, gpointer data);
  85
  86 /**
  87  * GstMetaSerializeFunction:
  88  * @meta: a #GstMeta
  89  */
  90 typedef gchar * (*GstMetaSerializeFunction) (GstMeta *meta);
  91
  92 /**
  93  * GstMetaDeserializeFunction:
  94  * @meta: a #GstMeta
  95  */
  96 typedef gboolean (*GstMetaDeserializeFunction) (GstMeta *meta,
  97                                                 const gchar *s);
  98
  99 /**
 100  * GstMetaInfo:
 101  * @api: tag indentifying the metadata structure and api
 102  * @impl: tag indentifying the implementor of the api
 103  * @size: size of the metadata
 104  * @init_func: function for initializing the metadata
 105  * @free_func: function for freeing the metadata
 106  * @copy_func: function for copying the metadata
 107  * @transform_func: function for transforming the metadata
 108  * @serialize_func: function for serializing
 109  * @deserialize_func: function for deserializing
 110  *
 111  * The #GstMetaInfo provides information about a specific metadata
 112  * structure.
 113  */
 114 struct _GstMetaInfo {
 115   GQuark                     api;
 116   GQuark                     impl;
 117   gsize                      size;
 118
 119   GstMetaInitFunction        init_func;
 120   GstMetaFreeFunction        free_func;
 121   GstMetaCopyFunction        copy_func;
 122   GstMetaTransformFunction   transform_func;
 123   GstMetaSerializeFunction   serialize_func;
 124   GstMetaDeserializeFunction deserialize_func;
 125 };
 126
 127 void _gst_meta_init (void);
 128
 129 const GstMetaInfo *  gst_meta_register        (const gchar *api, const gchar *impl,
 130                                                gsize size,
 131                                                GstMetaInitFunction        init_func,
 132                                                GstMetaFreeFunction        free_func,
 133                                                GstMetaCopyFunction        copy_func,
 134                                                GstMetaTransformFunction   transform_func,
 135                                                GstMetaSerializeFunction   serialize_func,
 136                                                GstMetaDeserializeFunction deserialize_func);
 137 const GstMetaInfo *  gst_meta_get_info        (const gchar * impl);
 138
 139 /* default metadata */
 140
 141 /* timing metadata */
 142 typedef struct _GstMetaTiming GstMetaTiming;
 143
 144 const GstMetaInfo *gst_meta_timing_get_info(void);
 145 #define GST_META_TIMING_INFO (gst_meta_timing_get_info())
 146
 147 struct _GstMetaTiming {
 148   GstMeta        meta;        /* common meta header */
 149
 150   GstClockTime   dts;         /* decoding timestamp */
 151   GstClockTime   pts;         /* presentation timestamp */
 152   GstClockTime   duration;    /* duration of the data */
 153   GstClockTime   clock_rate;  /* clock rate for the above values */
 154 };
 155
 156 #define gst_buffer_get_meta_timing(b)  ((GstMetaTiming*)gst_buffer_get_meta((b),GST_META_TIMING_INFO))
 157 #define gst_buffer_add_meta_timing(b)  ((GstMetaTiming*)gst_buffer_add_meta((b),GST_META_TIMING_INFO,NULL))
 158
 159 G_END_DECLS
 160
 161 #endif /* __GST_META_H__ */