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.
24 * @short_description: Buffer metadata
26 * The #GstMeta structure should be included as the first member of a #GstBuffer
27 * metadata structure. The structure defines the API of the metadata and should
28 * be accessible to all elements using the metadata.
30 * A metadata API is registered with gst_meta_api_type_register() which takes a
31 * name for the metadata API and some tags associated with the metadata.
32 * With gst_meta_api_type_has_tag() one can check if a certain metadata API
33 * contains a given tag.
35 * Multiple implementations of a metadata API can be registered.
36 * To implement a metadata API, gst_meta_register() should be used. This
37 * function takes all parameters needed to create, free and transform metadata
38 * along with the size of the metadata. The function returns a #GstMetaInfo
39 * structure that contains the information for the implementation of the API.
41 * A specific implementation can be retrieved by name with gst_meta_get_info().
43 * See #GstBuffer for how the metadata can be added, retrieved and removed from
46 #include "gst_private.h"
48 #include "gstbuffer.h"
53 static GHashTable *metainfo = NULL;
56 GQuark _gst_meta_transform_copy;
57 GQuark _gst_meta_tag_memory;
60 _priv_gst_meta_initialize (void)
62 g_rw_lock_init (&lock);
63 metainfo = g_hash_table_new (g_str_hash, g_str_equal);
65 _gst_meta_transform_copy = g_quark_from_static_string ("gst-copy");
66 _gst_meta_tag_memory = g_quark_from_static_string ("memory");
70 * gst_meta_api_type_register:
71 * @api: an API to register
72 * @tags: tags for @api
74 * Register and return a GType for the @api and associate it with
77 * Returns: a unique GType for @api.
80 gst_meta_api_type_register (const gchar * api, const gchar ** tags)
84 g_return_val_if_fail (api != NULL, 0);
85 g_return_val_if_fail (tags != NULL, 0);
87 GST_CAT_DEBUG (GST_CAT_META, "register API \"%s\"", api);
88 type = g_pointer_type_register_static (api);
93 for (i = 0; tags[i]; i++) {
94 GST_CAT_DEBUG (GST_CAT_META, " adding tag \"%s\"", tags[i]);
95 g_type_set_qdata (type, g_quark_from_string (tags[i]),
96 GINT_TO_POINTER (TRUE));
100 g_type_set_qdata (type, g_quark_from_string ("tags"),
101 g_strdupv ((gchar **) tags));
107 * gst_meta_api_type_has_tag:
109 * @tag: the tag to check
111 * Check if @api was registered with @tag.
113 * Returns: %TRUE if @api was registered with @tag.
116 gst_meta_api_type_has_tag (GType api, GQuark tag)
118 g_return_val_if_fail (api != 0, FALSE);
119 g_return_val_if_fail (tag != 0, FALSE);
121 return g_type_get_qdata (api, tag) != NULL;
125 * gst_meta_api_type_get_tags:
128 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): an array of tags as strings.
133 gst_meta_api_type_get_tags (GType api)
136 g_return_val_if_fail (api != 0, FALSE);
138 tags = g_type_get_qdata (api, g_quark_from_string ("tags"));
143 return (const gchar * const *) tags;
148 * @api: the type of the #GstMeta API
149 * @impl: the name of the #GstMeta implementation
150 * @size: the size of the #GstMeta structure
151 * @init_func: (scope async): a #GstMetaInitFunction
152 * @free_func: (scope async): a #GstMetaFreeFunction
153 * @transform_func: (scope async): a #GstMetaTransformFunction
155 * Register a new #GstMeta implementation.
157 * The same @info can be retrieved later with gst_meta_get_info() by using
160 * Returns: (transfer none): a #GstMetaInfo that can be used to access metadata.
164 gst_meta_register (GType api, const gchar * impl, gsize size,
165 GstMetaInitFunction init_func, GstMetaFreeFunction free_func,
166 GstMetaTransformFunction transform_func)
171 g_return_val_if_fail (api != 0, NULL);
172 g_return_val_if_fail (impl != NULL, NULL);
173 g_return_val_if_fail (size != 0, NULL);
175 /* first try to register the implementation name. It's possible
176 * that this fails because it was already registered. Don't warn,
177 * glib did this for us already. */
178 type = g_pointer_type_register_static (impl);
182 info = g_slice_new (GstMetaInfo);
186 info->init_func = init_func;
187 info->free_func = free_func;
188 info->transform_func = transform_func;
190 GST_CAT_DEBUG (GST_CAT_META,
191 "register \"%s\" implementing \"%s\" of size %" G_GSIZE_FORMAT, impl,
192 g_type_name (api), size);
194 g_rw_lock_writer_lock (&lock);
195 g_hash_table_insert (metainfo, (gpointer) impl, (gpointer) info);
196 g_rw_lock_writer_unlock (&lock);
205 * Lookup a previously registered meta info structure by its implementation name
208 * Returns: (transfer none) (nullable): a #GstMetaInfo with @impl, or
209 * %NULL when no such metainfo exists.
212 gst_meta_get_info (const gchar * impl)
216 g_return_val_if_fail (impl != NULL, NULL);
218 g_rw_lock_reader_lock (&lock);
219 info = g_hash_table_lookup (metainfo, impl);
220 g_rw_lock_reader_unlock (&lock);