2 * Copyright (C) 2011 Wim Taymans <wim.taymans@gmail.com>
4 * gstmeta.c: metadata operations
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.
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.
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.
25 * @short_description: Buffer metadata
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.
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.
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.
42 * A specific implementation can be retrieved by name with gst_meta_get_info().
44 * See #GstBuffer for how the metadata can be added, retrieved and removed from
47 #include "gst_private.h"
49 #include "gstbuffer.h"
55 static GHashTable *metainfo = NULL;
58 GQuark _gst_meta_transform_copy;
59 GQuark _gst_meta_tag_memory;
60 GQuark _gst_meta_tag_memory_reference;
66 GstStructure *structure;
72 GstCustomMetaTransformFunction custom_transform_func;
73 gpointer custom_transform_user_data;
74 GDestroyNotify custom_transform_destroy_notify;
79 free_info (gpointer data)
81 g_slice_free (GstMetaInfoImpl, data);
85 _priv_gst_meta_initialize (void)
87 g_rw_lock_init (&lock);
88 metainfo = g_hash_table_new_full (g_str_hash, g_str_equal, NULL, free_info);
90 _gst_meta_transform_copy = g_quark_from_static_string ("gst-copy");
91 _gst_meta_tag_memory = g_quark_from_static_string ("memory");
92 _gst_meta_tag_memory_reference =
93 g_quark_from_static_string ("memory-reference");
97 notify_custom (gchar * key, GstMetaInfo * info, gpointer unused)
99 GstMetaInfoImpl *impl = (GstMetaInfoImpl *) info;
101 if (impl->is_custom) {
102 if (impl->custom_transform_destroy_notify)
103 impl->custom_transform_destroy_notify (impl->custom_transform_user_data);
109 _priv_gst_meta_cleanup (void)
111 if (metainfo != NULL) {
112 g_hash_table_foreach_remove (metainfo, (GHRFunc) notify_custom, NULL);
113 g_hash_table_unref (metainfo);
119 * gst_meta_api_type_register:
120 * @api: an API to register
121 * @tags: (array zero-terminated=1): tags for @api
123 * Register and return a GType for the @api and associate it with
126 * Returns: a unique GType for @api.
129 gst_meta_api_type_register (const gchar * api, const gchar ** tags)
133 g_return_val_if_fail (api != NULL, 0);
134 g_return_val_if_fail (tags != NULL, 0);
136 GST_CAT_DEBUG (GST_CAT_META, "register API \"%s\"", api);
137 type = g_pointer_type_register_static (api);
139 if (type != G_TYPE_INVALID) {
142 for (i = 0; tags[i]; i++) {
143 GST_CAT_DEBUG (GST_CAT_META, " adding tag \"%s\"", tags[i]);
144 g_type_set_qdata (type, g_quark_from_string (tags[i]),
145 GINT_TO_POINTER (TRUE));
149 g_type_set_qdata (type, GST_QUARK (TAGS), g_strdupv ((gchar **) tags));
155 custom_init_func (GstMeta * meta, gpointer params, GstBuffer * buffer)
157 GstCustomMetaImpl *cmeta = (GstCustomMetaImpl *) meta;
159 cmeta->structure = gst_structure_new_empty (g_type_name (meta->info->type));
161 gst_structure_set_parent_refcount (cmeta->structure,
162 &GST_MINI_OBJECT_REFCOUNT (buffer));
168 custom_free_func (GstMeta * meta, GstBuffer * buffer)
170 GstCustomMetaImpl *cmeta = (GstCustomMetaImpl *) meta;
172 gst_structure_set_parent_refcount (cmeta->structure, NULL);
173 gst_structure_free (cmeta->structure);
177 custom_transform_func (GstBuffer * transbuf, GstMeta * meta,
178 GstBuffer * buffer, GQuark type, gpointer data)
180 GstCustomMetaImpl *custom, *cmeta = (GstCustomMetaImpl *) meta;
181 GstMetaInfoImpl *info = (GstMetaInfoImpl *) meta->info;
183 if (info->custom_transform_func)
184 return info->custom_transform_func (transbuf, (GstCustomMeta *) meta,
185 buffer, type, data, info->custom_transform_user_data);
187 if (GST_META_TRANSFORM_IS_COPY (type)) {
189 (GstCustomMetaImpl *) gst_buffer_add_meta (transbuf, meta->info, NULL);
190 gst_structure_set_parent_refcount (custom->structure, NULL);
191 gst_structure_take (&custom->structure,
192 gst_structure_copy (cmeta->structure));
193 gst_structure_set_parent_refcount (custom->structure,
194 &GST_MINI_OBJECT_REFCOUNT (transbuf));
203 * gst_custom_meta_get_structure:
205 * Retrieve the #GstStructure backing a custom meta, the structure's mutability
206 * is conditioned to the writability of the #GstBuffer @meta is attached to.
208 * Returns: (transfer none): the #GstStructure backing @meta
212 gst_custom_meta_get_structure (GstCustomMeta * meta)
214 g_return_val_if_fail (meta != NULL, NULL);
215 g_return_val_if_fail (gst_meta_info_is_custom (((GstMeta *) meta)->info),
218 return ((GstCustomMetaImpl *) meta)->structure;
222 * gst_custom_meta_has_name:
224 * Checks whether the name of the custom meta is @name
226 * Returns: Whether @name is the name of the custom meta
230 gst_custom_meta_has_name (GstCustomMeta * meta, const gchar * name)
232 g_return_val_if_fail (meta != NULL, FALSE);
233 g_return_val_if_fail (gst_meta_info_is_custom (((GstMeta *) meta)->info),
236 return gst_structure_has_name (((GstCustomMetaImpl *) meta)->structure, name);
240 * gst_meta_register_custom:
241 * @name: the name of the #GstMeta implementation
242 * @tags: (array zero-terminated=1): tags for @api
243 * @transform_func: (scope notified) (nullable): a #GstMetaTransformFunction
244 * @user_data: (closure): user data passed to @transform_func
245 * @destroy_data: #GDestroyNotify for user_data
247 * Register a new custom #GstMeta implementation, backed by an opaque
248 * structure holding a #GstStructure.
250 * The registered info can be retrieved later with gst_meta_get_info() by using
253 * The backing #GstStructure can be retrieved with
254 * gst_custom_meta_get_structure(), its mutability is conditioned by the
255 * writability of the buffer the meta is attached to.
257 * When @transform_func is %NULL, the meta and its backing #GstStructure
258 * will always be copied when the transform operation is copy, other operations
259 * are discarded, copy regions are ignored.
261 * Returns: (transfer none): a #GstMetaInfo that can be used to
266 gst_meta_register_custom (const gchar * name, const gchar ** tags,
267 GstCustomMetaTransformFunction transform_func,
268 gpointer user_data, GDestroyNotify destroy_data)
270 gchar *api_name = g_strdup_printf ("%s-api", name);
272 GstMetaInfoImpl *info;
273 GstMetaInfo *ret = NULL;
275 g_return_val_if_fail (tags != NULL, NULL);
276 g_return_val_if_fail (name != NULL, NULL);
278 api = gst_meta_api_type_register (api_name, tags);
280 if (api == G_TYPE_INVALID)
283 info = (GstMetaInfoImpl *) gst_meta_register (api, name,
284 sizeof (GstCustomMetaImpl),
285 custom_init_func, custom_free_func, custom_transform_func);
290 info->is_custom = TRUE;
291 info->custom_transform_func = transform_func;
292 info->custom_transform_user_data = user_data;
293 info->custom_transform_destroy_notify = destroy_data;
295 ret = (GstMetaInfo *) info;
302 * gst_meta_info_is_custom:
304 * Returns: whether @info was registered as a #GstCustomMeta with
305 * gst_meta_register_custom()
309 gst_meta_info_is_custom (const GstMetaInfo * info)
311 g_return_val_if_fail (info != NULL, FALSE);
313 return ((GstMetaInfoImpl *) info)->is_custom;
317 * gst_meta_api_type_has_tag:
319 * @tag: the tag to check
321 * Check if @api was registered with @tag.
323 * Returns: %TRUE if @api was registered with @tag.
326 gst_meta_api_type_has_tag (GType api, GQuark tag)
328 g_return_val_if_fail (api != 0, FALSE);
329 g_return_val_if_fail (tag != 0, FALSE);
331 return g_type_get_qdata (api, tag) != NULL;
335 * gst_meta_api_type_get_tags:
338 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): an array of tags as strings.
343 gst_meta_api_type_get_tags (GType api)
346 g_return_val_if_fail (api != 0, FALSE);
348 tags = g_type_get_qdata (api, GST_QUARK (TAGS));
353 return (const gchar * const *) tags;
358 * @api: the type of the #GstMeta API
359 * @impl: the name of the #GstMeta implementation
360 * @size: the size of the #GstMeta structure
361 * @init_func: (scope async): a #GstMetaInitFunction
362 * @free_func: (scope async): a #GstMetaFreeFunction
363 * @transform_func: (scope async): a #GstMetaTransformFunction
365 * Register a new #GstMeta implementation.
367 * The same @info can be retrieved later with gst_meta_get_info() by using
370 * Returns: (transfer none): a #GstMetaInfo that can be used to
375 gst_meta_register (GType api, const gchar * impl, gsize size,
376 GstMetaInitFunction init_func, GstMetaFreeFunction free_func,
377 GstMetaTransformFunction transform_func)
382 g_return_val_if_fail (api != 0, NULL);
383 g_return_val_if_fail (impl != NULL, NULL);
384 g_return_val_if_fail (size != 0, NULL);
386 if (init_func == NULL)
387 g_critical ("Registering meta implementation '%s' without init function",
390 /* first try to register the implementation name. It's possible
391 * that this fails because it was already registered. Don't warn,
392 * glib did this for us already. */
393 type = g_pointer_type_register_static (impl);
394 if (type == G_TYPE_INVALID)
397 info = (GstMetaInfo *) g_slice_new (GstMetaInfoImpl);
401 info->init_func = init_func;
402 info->free_func = free_func;
403 info->transform_func = transform_func;
404 ((GstMetaInfoImpl *) info)->is_custom = FALSE;
406 GST_CAT_DEBUG (GST_CAT_META,
407 "register \"%s\" implementing \"%s\" of size %" G_GSIZE_FORMAT, impl,
408 g_type_name (api), size);
410 g_rw_lock_writer_lock (&lock);
411 g_hash_table_insert (metainfo, (gpointer) g_intern_string (impl),
413 g_rw_lock_writer_unlock (&lock);
422 * Lookup a previously registered meta info structure by its implementation name
425 * Returns: (transfer none) (nullable): a #GstMetaInfo with @impl, or
426 * %NULL when no such metainfo exists.
429 gst_meta_get_info (const gchar * impl)
433 g_return_val_if_fail (impl != NULL, NULL);
435 g_rw_lock_reader_lock (&lock);
436 info = g_hash_table_lookup (metainfo, impl);
437 g_rw_lock_reader_unlock (&lock);
443 * gst_meta_get_seqnum:
446 * Gets seqnum for this meta.
451 gst_meta_get_seqnum (const GstMeta * meta)
453 GstMetaItem *meta_item;
456 g_return_val_if_fail (meta != NULL, 0);
459 p -= G_STRUCT_OFFSET (GstMetaItem, meta);
460 meta_item = (GstMetaItem *) p;
461 return meta_item->seq_num;
465 * gst_meta_compare_seqnum:
469 * Meta sequence number compare function. Can be used as #GCompareFunc
470 * or a #GCompareDataFunc.
472 * Returns: a negative number if @meta1 comes before @meta2, 0 if both metas
473 * have an equal sequence number, or a positive integer if @meta1 comes
479 gst_meta_compare_seqnum (const GstMeta * meta1, const GstMeta * meta2)
481 guint64 seqnum1 = gst_meta_get_seqnum (meta1);
482 guint64 seqnum2 = gst_meta_get_seqnum (meta2);
484 if (seqnum1 == seqnum2)
487 return (seqnum1 < seqnum2) ? -1 : 1;