gstmeta.h 5.55 KB
Newer Older
1 2 3
/* GStreamer
 * Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
 *
Wim Taymans's avatar
Wim Taymans committed
4
 * gstmeta.h: Header for Metadata structures
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */


Wim Taymans's avatar
Wim Taymans committed
23 24
#ifndef __GST_META_H__
#define __GST_META_H__
25 26 27

G_BEGIN_DECLS

Wim Taymans's avatar
Wim Taymans committed
28 29
typedef struct _GstMeta GstMeta;
typedef struct _GstMetaInfo GstMetaInfo;
30

Wim Taymans's avatar
Wim Taymans committed
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
#define GST_META_CAST(meta)   ((GstMeta *)(meta))

/**
 * GstMetaFlags:
 * @GST_META_FLAG_NONE: no flags
 * @GST_META_FLAG_READONLY: metadata should not be modified
 * @GST_META_FLAG_POOLED: metadata is managed by a bufferpool and should not
 *    be removed
 * @GST_META_FLAG_LAST: additional flags can be added starting from this flag.
 *
 * Extra metadata flags.
 */
typedef enum {
  GST_META_FLAG_NONE        = 0,
  GST_META_FLAG_READONLY    = (1 << 0),
  GST_META_FLAG_POOLED      = (1 << 1),

  GST_META_FLAG_LAST        = (1 << 16)
} GstMetaFlags;

/**
 * GST_META_FLAGS:
 * @meta: a #GstMeta.
 *
 * A flags word containing #GstMetaFlag flags set on @meta
 */
#define GST_META_FLAGS(meta)  (GST_META_CAST (meta)->flags)
/**
 * GST_META_FLAG_IS_SET:
 * @meta: a #GstMeta.
 * @flag: the #GstMetaFlag to check.
 *
 * Gives the status of a specific flag on a metadata.
 */
#define GST_META_FLAG_IS_SET(meta,flag)        !!(GST_META_FLAGS (meta) & (flag))
/**
 * GST_META_FLAG_SET:
 * @meta: a #GstMeta.
 * @flag: the #GstMetaFlag to set.
 *
 * Sets a metadata flag on a metadata.
 */
#define GST_META_FLAG_SET(meta,flag)           (GST_META_FLAGS (meta) |= (flag))
/**
 * GST_META_FLAG_UNSET:
 * @meta: a #GstMeta.
 * @flag: the #GstMetaFlag to clear.
 *
 * Clears a metadata flag.
 */
#define GST_META_FLAG_UNSET(meta,flag)         (GST_META_FLAGS (meta) &= ~(flag))

83
/**
Wim Taymans's avatar
Wim Taymans committed
84
 * GstMeta:
Wim Taymans's avatar
Wim Taymans committed
85
 * @flags: extra flags for the metadata
Wim Taymans's avatar
Wim Taymans committed
86
 * @info: pointer to the #GstMetaInfo
87
 *
Wim Taymans's avatar
Wim Taymans committed
88
 * Base structure for metadata. Custom metadata will put this structure
89 90
 * as the first member of their structure.
 */
Wim Taymans's avatar
Wim Taymans committed
91
struct _GstMeta {
Wim Taymans's avatar
Wim Taymans committed
92
  GstMetaFlags       flags;
Wim Taymans's avatar
Wim Taymans committed
93
  const GstMetaInfo *info;
94 95 96 97 98
};

/**
 * GstMetaInitFunction:
 * @meta: a #GstMeta
Wim Taymans's avatar
Wim Taymans committed
99
 * @params: parameters passed to the init function
100 101 102 103
 * @buffer: a #GstBuffer
 *
 * Function called when @meta is initialized in @buffer.
 */
104
typedef gboolean (*GstMetaInitFunction) (GstMeta *meta, gpointer params, GstBuffer *buffer);
105 106 107 108 109 110 111 112

/**
 * GstMetaFreeFunction:
 * @meta: a #GstMeta
 * @buffer: a #GstBuffer
 *
 * Function called when @meta is freed in @buffer.
 */
Wim Taymans's avatar
Wim Taymans committed
113
typedef void (*GstMetaFreeFunction)     (GstMeta *meta, GstBuffer *buffer);
114

Wim Taymans's avatar
Wim Taymans committed
115 116 117 118 119 120 121 122 123 124 125
/**
 * GstMetaCopyFunction:
 * @dest: a destination #GstBuffer
 * @meta: a #GstMeta
 * @buffer: a #GstBuffer
 * @offset: an offset
 * @size: a size
 *
 * Function called when the region at @offset and @size in @buffer is copied
 * into @dest. The function should update the metadata on @dest using @meta.
 */
Wim Taymans's avatar
Wim Taymans committed
126 127
typedef void (*GstMetaCopyFunction)     (GstBuffer *dest, GstMeta *meta,
                                         GstBuffer *buffer, gsize offset, gsize size);
128 129 130
/**
 * GstMetaTransformFunction:
 * @transbuf: a #GstBuffer
131 132
 * @meta: a #GstMeta
 * @buffer: a #GstBuffer
133 134 135 136 137 138 139 140
 * @data: transform specific data.
 *
 * Function called for each @meta in @buffer as a result of performing a
 * transformation on @transbuf. Additional type specific transform data
 * is passed to the function.
 *
 * Implementations should check the type of the transform @data and parse
 * additional type specific field that should be used to perform the transform.
141
 */
142
typedef void (*GstMetaTransformFunction) (GstBuffer *transbuf, GstMeta *meta,
Wim Taymans's avatar
Wim Taymans committed
143
                                          GstBuffer *buffer, gpointer data);
144 145

/**
Wim Taymans's avatar
Wim Taymans committed
146 147
 * GstMetaInfo:
 * @api: tag indentifying the metadata structure and api
148
 * @type: type indentifying the implementor of the api
149 150 151
 * @size: size of the metadata
 * @init_func: function for initializing the metadata
 * @free_func: function for freeing the metadata
Wim Taymans's avatar
Wim Taymans committed
152
 * @copy_func: function for copying the metadata
Wim Taymans's avatar
Wim Taymans committed
153
 * @transform_func: function for transforming the metadata
154
 *
Wim Taymans's avatar
Wim Taymans committed
155
 * The #GstMetaInfo provides information about a specific metadata
156 157
 * structure.
 */
Wim Taymans's avatar
Wim Taymans committed
158 159
struct _GstMetaInfo {
  GQuark                     api;
160
  GType                      type;
161 162 163 164
  gsize                      size;

  GstMetaInitFunction        init_func;
  GstMetaFreeFunction        free_func;
Wim Taymans's avatar
Wim Taymans committed
165
  GstMetaCopyFunction        copy_func;
166
  GstMetaTransformFunction   transform_func;
Wim Taymans's avatar
Wim Taymans committed
167

Wim Taymans's avatar
Wim Taymans committed
168
  /*< private >*/
Wim Taymans's avatar
Wim Taymans committed
169
  gpointer _gst_reserved[GST_PADDING];
170 171
};

Wim Taymans's avatar
Wim Taymans committed
172 173 174 175
const GstMetaInfo *  gst_meta_register        (const gchar *api, const gchar *impl,
                                               gsize size,
                                               GstMetaInitFunction        init_func,
                                               GstMetaFreeFunction        free_func,
Wim Taymans's avatar
Wim Taymans committed
176
                                               GstMetaCopyFunction        copy_func,
177
                                               GstMetaTransformFunction   transform_func);
Wim Taymans's avatar
Wim Taymans committed
178
const GstMetaInfo *  gst_meta_get_info        (const gchar * impl);
179 180 181

G_END_DECLS

Wim Taymans's avatar
Wim Taymans committed
182
#endif /* __GST_META_H__ */