1 /* GStreamer
2 * Copyright (C) 2011 Wim Taymans <wim.taymans@gmail.com>
3 *
4 * gstmeta.c: metadata operations
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 * SECTION:gstmeta
24 * @title: GstMeta
25 * @short_description: Buffer metadata
26 *
27 * The #GstMeta structure should be included as the first member of a #GstBuffer
28 * metadata structure. The structure defines the API of the metadata and should
29 * be accessible to all elements using the metadata.
30 *
31 * A metadata API is registered with gst_meta_api_type_register() which takes a
32 * name for the metadata API and some tags associated with the metadata.
33 * With gst_meta_api_type_has_tag() one can check if a certain metadata API
34 * contains a given tag.
35 *
36 * Multiple implementations of a metadata API can be registered.
37 * To implement a metadata API, gst_meta_register() should be used. This
38 * function takes all parameters needed to create, free and transform metadata
39 * along with the size of the metadata. The function returns a #GstMetaInfo
40 * structure that contains the information for the implementation of the API.
41 *
42 * A specific implementation can be retrieved by name with gst_meta_get_info().
43 *
44 * See #GstBuffer for how the metadata can be added, retrieved and removed from
45 * buffers.
46 */
47 #include "gst_private.h"
48
49 #include "gstbuffer.h"
50 #include "gstmeta.h"
51 #include "gstinfo.h"
52 #include "gstutils.h"
53
54 static GHashTable *metainfo = NULL;
55 static GRWLock lock;
56
57 GQuark _gst_meta_transform_copy;
58 GQuark _gst_meta_tag_memory;
59
60 void
_priv_gst_meta_initialize(void)61 _priv_gst_meta_initialize (void)
62 {
63 g_rw_lock_init (&lock);
64 metainfo = g_hash_table_new (g_str_hash, g_str_equal);
65
66 _gst_meta_transform_copy = g_quark_from_static_string ("gst-copy");
67 _gst_meta_tag_memory = g_quark_from_static_string ("memory");
68 }
69
70 /**
71 * gst_meta_api_type_register:
72 * @api: an API to register
73 * @tags: (array zero-terminated=1): tags for @api
74 *
75 * Register and return a GType for the @api and associate it with
76 * @tags.
77 *
78 * Returns: a unique GType for @api.
79 */
80 GType
gst_meta_api_type_register(const gchar * api,const gchar ** tags)81 gst_meta_api_type_register (const gchar * api, const gchar ** tags)
82 {
83 GType type;
84
85 g_return_val_if_fail (api != NULL, 0);
86 g_return_val_if_fail (tags != NULL, 0);
87
88 GST_CAT_DEBUG (GST_CAT_META, "register API \"%s\"", api);
89 type = g_pointer_type_register_static (api);
90
91 if (type != 0) {
92 gint i;
93
94 for (i = 0; tags[i]; i++) {
95 GST_CAT_DEBUG (GST_CAT_META, " adding tag \"%s\"", tags[i]);
96 g_type_set_qdata (type, g_quark_from_string (tags[i]),
97 GINT_TO_POINTER (TRUE));
98 }
99 }
100
101 g_type_set_qdata (type, g_quark_from_string ("tags"),
102 g_strdupv ((gchar **) tags));
103
104 return type;
105 }
106
107 /**
108 * gst_meta_api_type_has_tag:
109 * @api: an API
110 * @tag: the tag to check
111 *
112 * Check if @api was registered with @tag.
113 *
114 * Returns: %TRUE if @api was registered with @tag.
115 */
116 gboolean
gst_meta_api_type_has_tag(GType api,GQuark tag)117 gst_meta_api_type_has_tag (GType api, GQuark tag)
118 {
119 g_return_val_if_fail (api != 0, FALSE);
120 g_return_val_if_fail (tag != 0, FALSE);
121
122 return g_type_get_qdata (api, tag) != NULL;
123 }
124
125 /**
126 * gst_meta_api_type_get_tags:
127 * @api: an API
128 *
129 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): an array of tags as strings.
130 *
131 * Since: 1.2
132 */
133 const gchar *const *
gst_meta_api_type_get_tags(GType api)134 gst_meta_api_type_get_tags (GType api)
135 {
136 const gchar **tags;
137 g_return_val_if_fail (api != 0, FALSE);
138
139 tags = g_type_get_qdata (api, g_quark_from_string ("tags"));
140
141 if (!tags[0])
142 return NULL;
143
144 return (const gchar * const *) tags;
145 }
146
147 /**
148 * gst_meta_register:
149 * @api: the type of the #GstMeta API
150 * @impl: the name of the #GstMeta implementation
151 * @size: the size of the #GstMeta structure
152 * @init_func: (scope async): a #GstMetaInitFunction
153 * @free_func: (scope async): a #GstMetaFreeFunction
154 * @transform_func: (scope async): a #GstMetaTransformFunction
155 *
156 * Register a new #GstMeta implementation.
157 *
158 * The same @info can be retrieved later with gst_meta_get_info() by using
159 * @impl as the key.
160 *
161 * Returns: (transfer none) (nullable): a #GstMetaInfo that can be used to
162 * access metadata.
163 */
164
165 const GstMetaInfo *
gst_meta_register(GType api,const gchar * impl,gsize size,GstMetaInitFunction init_func,GstMetaFreeFunction free_func,GstMetaTransformFunction transform_func)166 gst_meta_register (GType api, const gchar * impl, gsize size,
167 GstMetaInitFunction init_func, GstMetaFreeFunction free_func,
168 GstMetaTransformFunction transform_func)
169 {
170 GstMetaInfo *info;
171 GType type;
172
173 g_return_val_if_fail (api != 0, NULL);
174 g_return_val_if_fail (impl != NULL, NULL);
175 g_return_val_if_fail (size != 0, NULL);
176
177 if (init_func == NULL)
178 g_critical ("Registering meta implementation '%s' without init function",
179 impl);
180
181 /* first try to register the implementation name. It's possible
182 * that this fails because it was already registered. Don't warn,
183 * glib did this for us already. */
184 type = g_pointer_type_register_static (impl);
185 if (type == 0)
186 return NULL;
187
188 info = g_slice_new (GstMetaInfo);
189 info->api = api;
190 info->type = type;
191 info->size = size;
192 info->init_func = init_func;
193 info->free_func = free_func;
194 info->transform_func = transform_func;
195
196 GST_CAT_DEBUG (GST_CAT_META,
197 "register \"%s\" implementing \"%s\" of size %" G_GSIZE_FORMAT, impl,
198 g_type_name (api), size);
199
200 g_rw_lock_writer_lock (&lock);
201 g_hash_table_insert (metainfo, (gpointer) impl, (gpointer) info);
202 g_rw_lock_writer_unlock (&lock);
203
204 return info;
205 }
206
207 /**
208 * gst_meta_get_info:
209 * @impl: the name
210 *
211 * Lookup a previously registered meta info structure by its implementation name
212 * @impl.
213 *
214 * Returns: (transfer none) (nullable): a #GstMetaInfo with @impl, or
215 * %NULL when no such metainfo exists.
216 */
217 const GstMetaInfo *
gst_meta_get_info(const gchar * impl)218 gst_meta_get_info (const gchar * impl)
219 {
220 GstMetaInfo *info;
221
222 g_return_val_if_fail (impl != NULL, NULL);
223
224 g_rw_lock_reader_lock (&lock);
225 info = g_hash_table_lookup (metainfo, impl);
226 g_rw_lock_reader_unlock (&lock);
227
228 return info;
229 }
230
231 /**
232 * gst_meta_get_seqnum:
233 * @meta: a #GstMeta
234 *
235 * Gets seqnum for this meta.
236 *
237 * Since: 1.16
238 */
239 guint64
gst_meta_get_seqnum(const GstMeta * meta)240 gst_meta_get_seqnum (const GstMeta * meta)
241 {
242 GstMetaItem *meta_item;
243 guint8 *p;
244
245 g_return_val_if_fail (meta != NULL, 0);
246
247 p = (guint8 *) meta;
248 p -= G_STRUCT_OFFSET (GstMetaItem, meta);
249 meta_item = (GstMetaItem *) p;
250 return meta_item->seq_num;
251 }
252
253 /**
254 * gst_meta_compare_seqnum:
255 * @meta1: a #GstMeta
256 * @meta2: a #GstMeta
257 *
258 * Meta sequence number compare function. Can be used as #GCompareFunc
259 * or a #GCompareDataFunc.
260 *
261 * Returns: a negative number if @meta1 comes before @meta2, 0 if both metas
262 * have an equal sequence number, or a positive integer if @meta1 comes
263 * after @meta2.
264 *
265 * Since: 1.16
266 */
267 gint
gst_meta_compare_seqnum(const GstMeta * meta1,const GstMeta * meta2)268 gst_meta_compare_seqnum (const GstMeta * meta1, const GstMeta * meta2)
269 {
270 guint64 seqnum1 = gst_meta_get_seqnum (meta1);
271 guint64 seqnum2 = gst_meta_get_seqnum (meta2);
272
273 if (seqnum1 == seqnum2)
274 return 0;
275
276 return (seqnum1 < seqnum2) ? -1 : 1;
277 }
278