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 #include "gstquark.h"
54
55 static GHashTable *metainfo = NULL;
56 static GRWLock lock;
57
58 GQuark _gst_meta_transform_copy;
59 GQuark _gst_meta_tag_memory;
60
61 typedef struct
62 {
63 GstCustomMeta meta;
64
65 GstStructure *structure;
66 } GstCustomMetaImpl;
67
68 typedef struct
69 {
70 GstMetaInfo info;
71 GstCustomMetaTransformFunction custom_transform_func;
72 gpointer custom_transform_user_data;
73 GDestroyNotify custom_transform_destroy_notify;
74 gboolean is_custom;
75 } GstMetaInfoImpl;
76
77 static void
free_info(gpointer data)78 free_info (gpointer data)
79 {
80 g_slice_free (GstMetaInfoImpl, data);
81 }
82
83 void
_priv_gst_meta_initialize(void)84 _priv_gst_meta_initialize (void)
85 {
86 g_rw_lock_init (&lock);
87 metainfo = g_hash_table_new_full (g_str_hash, g_str_equal, NULL, free_info);
88
89 _gst_meta_transform_copy = g_quark_from_static_string ("gst-copy");
90 _gst_meta_tag_memory = g_quark_from_static_string ("memory");
91 }
92
93 static gboolean
notify_custom(gchar * key,GstMetaInfo * info,gpointer unused)94 notify_custom (gchar * key, GstMetaInfo * info, gpointer unused)
95 {
96 GstMetaInfoImpl *impl = (GstMetaInfoImpl *) info;
97
98 if (impl->is_custom) {
99 if (impl->custom_transform_destroy_notify)
100 impl->custom_transform_destroy_notify (impl->custom_transform_user_data);
101 }
102 return TRUE;
103 }
104
105 void
_priv_gst_meta_cleanup(void)106 _priv_gst_meta_cleanup (void)
107 {
108 if (metainfo != NULL) {
109 g_hash_table_foreach_remove (metainfo, (GHRFunc) notify_custom, NULL);
110 g_hash_table_unref (metainfo);
111 metainfo = NULL;
112 }
113 }
114
115 /**
116 * gst_meta_api_type_register:
117 * @api: an API to register
118 * @tags: (array zero-terminated=1): tags for @api
119 *
120 * Register and return a GType for the @api and associate it with
121 * @tags.
122 *
123 * Returns: a unique GType for @api.
124 */
125 GType
gst_meta_api_type_register(const gchar * api,const gchar ** tags)126 gst_meta_api_type_register (const gchar * api, const gchar ** tags)
127 {
128 GType type;
129
130 g_return_val_if_fail (api != NULL, 0);
131 g_return_val_if_fail (tags != NULL, 0);
132
133 GST_CAT_DEBUG (GST_CAT_META, "register API \"%s\"", api);
134 type = g_pointer_type_register_static (api);
135
136 if (type != 0) {
137 gint i;
138
139 for (i = 0; tags[i]; i++) {
140 GST_CAT_DEBUG (GST_CAT_META, " adding tag \"%s\"", tags[i]);
141 g_type_set_qdata (type, g_quark_from_string (tags[i]),
142 GINT_TO_POINTER (TRUE));
143 }
144 }
145
146 g_type_set_qdata (type, GST_QUARK (TAGS), g_strdupv ((gchar **) tags));
147
148 return type;
149 }
150
151 static gboolean
custom_init_func(GstMeta * meta,gpointer params,GstBuffer * buffer)152 custom_init_func (GstMeta * meta, gpointer params, GstBuffer * buffer)
153 {
154 GstCustomMetaImpl *cmeta = (GstCustomMetaImpl *) meta;
155
156 cmeta->structure = gst_structure_new_empty (g_type_name (meta->info->type));
157
158 gst_structure_set_parent_refcount (cmeta->structure,
159 &GST_MINI_OBJECT_REFCOUNT (buffer));
160
161 return TRUE;
162 }
163
164 static void
custom_free_func(GstMeta * meta,GstBuffer * buffer)165 custom_free_func (GstMeta * meta, GstBuffer * buffer)
166 {
167 GstCustomMetaImpl *cmeta = (GstCustomMetaImpl *) meta;
168
169 gst_structure_set_parent_refcount (cmeta->structure, NULL);
170 gst_structure_free (cmeta->structure);
171 }
172
173 static gboolean
custom_transform_func(GstBuffer * transbuf,GstMeta * meta,GstBuffer * buffer,GQuark type,gpointer data)174 custom_transform_func (GstBuffer * transbuf, GstMeta * meta,
175 GstBuffer * buffer, GQuark type, gpointer data)
176 {
177 GstCustomMetaImpl *custom, *cmeta = (GstCustomMetaImpl *) meta;
178 GstMetaInfoImpl *info = (GstMetaInfoImpl *) meta->info;
179
180 if (info->custom_transform_func)
181 return info->custom_transform_func (transbuf, (GstCustomMeta *) meta,
182 buffer, type, data, info->custom_transform_user_data);
183
184 if (GST_META_TRANSFORM_IS_COPY (type)) {
185 custom =
186 (GstCustomMetaImpl *) gst_buffer_add_meta (transbuf, meta->info, NULL);
187 gst_structure_set_parent_refcount (custom->structure, NULL);
188 gst_structure_take (&custom->structure,
189 gst_structure_copy (cmeta->structure));
190 gst_structure_set_parent_refcount (custom->structure,
191 &GST_MINI_OBJECT_REFCOUNT (buffer));
192 } else {
193 return FALSE;
194 }
195
196 return TRUE;
197 }
198
199 /**
200 * gst_custom_meta_get_structure:
201 *
202 * Retrieve the #GstStructure backing a custom meta, the structure's mutability
203 * is conditioned to the writability of the #GstBuffer @meta is attached to.
204 *
205 * Returns: (transfer none): the #GstStructure backing @meta
206 * Since: 1.20
207 */
208 GstStructure *
gst_custom_meta_get_structure(GstCustomMeta * meta)209 gst_custom_meta_get_structure (GstCustomMeta * meta)
210 {
211 g_return_val_if_fail (meta != NULL, NULL);
212 g_return_val_if_fail (gst_meta_info_is_custom (((GstMeta *) meta)->info),
213 NULL);
214
215 return ((GstCustomMetaImpl *) meta)->structure;
216 }
217
218 /**
219 * gst_custom_meta_has_name:
220 *
221 * Checks whether the name of the custom meta is @name
222 *
223 * Returns: Whether @name is the name of the custom meta
224 * Since: 1.20
225 */
226 gboolean
gst_custom_meta_has_name(GstCustomMeta * meta,const gchar * name)227 gst_custom_meta_has_name (GstCustomMeta * meta, const gchar * name)
228 {
229 g_return_val_if_fail (meta != NULL, FALSE);
230 g_return_val_if_fail (gst_meta_info_is_custom (((GstMeta *) meta)->info),
231 FALSE);
232
233 return gst_structure_has_name (((GstCustomMetaImpl *) meta)->structure, name);
234 }
235
236 /**
237 * gst_meta_register_custom:
238 * @name: the name of the #GstMeta implementation
239 * @tags: (array zero-terminated=1): tags for @api
240 * @transform_func: (scope notified) (nullable): a #GstMetaTransformFunction
241 * @user_data: (closure): user data passed to @transform_func
242 * @destroy_data: #GDestroyNotify for user_data
243 *
244 * Register a new custom #GstMeta implementation, backed by an opaque
245 * structure holding a #GstStructure.
246 *
247 * The registered info can be retrieved later with gst_meta_get_info() by using
248 * @name as the key.
249 *
250 * The backing #GstStructure can be retrieved with
251 * gst_custom_meta_get_structure(), its mutability is conditioned by the
252 * writability of the buffer the meta is attached to.
253 *
254 * When @transform_func is %NULL, the meta and its backing #GstStructure
255 * will always be copied when the transform operation is copy, other operations
256 * are discarded, copy regions are ignored.
257 *
258 * Returns: (transfer none): a #GstMetaInfo that can be used to
259 * access metadata.
260 * Since: 1.20
261 */
262 const GstMetaInfo *
gst_meta_register_custom(const gchar * name,const gchar ** tags,GstCustomMetaTransformFunction transform_func,gpointer user_data,GDestroyNotify destroy_data)263 gst_meta_register_custom (const gchar * name, const gchar ** tags,
264 GstCustomMetaTransformFunction transform_func,
265 gpointer user_data, GDestroyNotify destroy_data)
266 {
267 gchar *api_name = g_strdup_printf ("%s-api", name);
268 GType api;
269 GstMetaInfoImpl *info;
270 GstMetaInfo *ret = NULL;
271
272 g_return_val_if_fail (tags != NULL, NULL);
273 g_return_val_if_fail (name != NULL, NULL);
274
275 api = gst_meta_api_type_register (api_name, tags);
276 g_free (api_name);
277 if (api == G_TYPE_INVALID)
278 goto done;
279
280 info = (GstMetaInfoImpl *) gst_meta_register (api, name,
281 sizeof (GstCustomMetaImpl),
282 custom_init_func, custom_free_func, custom_transform_func);
283
284 if (!info)
285 goto done;
286
287 info->is_custom = TRUE;
288 info->custom_transform_func = transform_func;
289 info->custom_transform_user_data = user_data;
290 info->custom_transform_destroy_notify = destroy_data;
291
292 ret = (GstMetaInfo *) info;
293
294 done:
295 return ret;
296 }
297
298 /**
299 * gst_meta_info_is_custom:
300 *
301 * Returns: whether @info was registered as a #GstCustomMeta with
302 * gst_meta_register_custom()
303 * Since:1.20
304 */
305 gboolean
gst_meta_info_is_custom(const GstMetaInfo * info)306 gst_meta_info_is_custom (const GstMetaInfo * info)
307 {
308 g_return_val_if_fail (info != NULL, FALSE);
309
310 return ((GstMetaInfoImpl *) info)->is_custom;
311 }
312
313 /**
314 * gst_meta_api_type_has_tag:
315 * @api: an API
316 * @tag: the tag to check
317 *
318 * Check if @api was registered with @tag.
319 *
320 * Returns: %TRUE if @api was registered with @tag.
321 */
322 gboolean
gst_meta_api_type_has_tag(GType api,GQuark tag)323 gst_meta_api_type_has_tag (GType api, GQuark tag)
324 {
325 g_return_val_if_fail (api != 0, FALSE);
326 g_return_val_if_fail (tag != 0, FALSE);
327
328 return g_type_get_qdata (api, tag) != NULL;
329 }
330
331 /**
332 * gst_meta_api_type_get_tags:
333 * @api: an API
334 *
335 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): an array of tags as strings.
336 *
337 * Since: 1.2
338 */
339 const gchar *const *
gst_meta_api_type_get_tags(GType api)340 gst_meta_api_type_get_tags (GType api)
341 {
342 const gchar **tags;
343 g_return_val_if_fail (api != 0, FALSE);
344
345 tags = g_type_get_qdata (api, GST_QUARK (TAGS));
346
347 if (!tags[0])
348 return NULL;
349
350 return (const gchar * const *) tags;
351 }
352
353 /**
354 * gst_meta_register:
355 * @api: the type of the #GstMeta API
356 * @impl: the name of the #GstMeta implementation
357 * @size: the size of the #GstMeta structure
358 * @init_func: (scope async): a #GstMetaInitFunction
359 * @free_func: (scope async): a #GstMetaFreeFunction
360 * @transform_func: (scope async): a #GstMetaTransformFunction
361 *
362 * Register a new #GstMeta implementation.
363 *
364 * The same @info can be retrieved later with gst_meta_get_info() by using
365 * @impl as the key.
366 *
367 * Returns: (transfer none): a #GstMetaInfo that can be used to
368 * access metadata.
369 */
370
371 const GstMetaInfo *
gst_meta_register(GType api,const gchar * impl,gsize size,GstMetaInitFunction init_func,GstMetaFreeFunction free_func,GstMetaTransformFunction transform_func)372 gst_meta_register (GType api, const gchar * impl, gsize size,
373 GstMetaInitFunction init_func, GstMetaFreeFunction free_func,
374 GstMetaTransformFunction transform_func)
375 {
376 GstMetaInfo *info;
377 GType type;
378
379 g_return_val_if_fail (api != 0, NULL);
380 g_return_val_if_fail (impl != NULL, NULL);
381 g_return_val_if_fail (size != 0, NULL);
382
383 if (init_func == NULL)
384 g_critical ("Registering meta implementation '%s' without init function",
385 impl);
386
387 /* first try to register the implementation name. It's possible
388 * that this fails because it was already registered. Don't warn,
389 * glib did this for us already. */
390 type = g_pointer_type_register_static (impl);
391 if (type == 0)
392 return NULL;
393
394 info = (GstMetaInfo *) g_slice_new (GstMetaInfoImpl);
395 info->api = api;
396 info->type = type;
397 info->size = size;
398 info->init_func = init_func;
399 info->free_func = free_func;
400 info->transform_func = transform_func;
401 ((GstMetaInfoImpl *) info)->is_custom = FALSE;
402
403 GST_CAT_DEBUG (GST_CAT_META,
404 "register \"%s\" implementing \"%s\" of size %" G_GSIZE_FORMAT, impl,
405 g_type_name (api), size);
406
407 g_rw_lock_writer_lock (&lock);
408 g_hash_table_insert (metainfo, (gpointer) g_intern_string (impl),
409 (gpointer) info);
410 g_rw_lock_writer_unlock (&lock);
411
412 return info;
413 }
414
415 /**
416 * gst_meta_get_info:
417 * @impl: the name
418 *
419 * Lookup a previously registered meta info structure by its implementation name
420 * @impl.
421 *
422 * Returns: (transfer none) (nullable): a #GstMetaInfo with @impl, or
423 * %NULL when no such metainfo exists.
424 */
425 const GstMetaInfo *
gst_meta_get_info(const gchar * impl)426 gst_meta_get_info (const gchar * impl)
427 {
428 GstMetaInfo *info;
429
430 g_return_val_if_fail (impl != NULL, NULL);
431
432 g_rw_lock_reader_lock (&lock);
433 info = g_hash_table_lookup (metainfo, impl);
434 g_rw_lock_reader_unlock (&lock);
435
436 return info;
437 }
438
439 /**
440 * gst_meta_get_seqnum:
441 * @meta: a #GstMeta
442 *
443 * Gets seqnum for this meta.
444 *
445 * Since: 1.16
446 */
447 guint64
gst_meta_get_seqnum(const GstMeta * meta)448 gst_meta_get_seqnum (const GstMeta * meta)
449 {
450 GstMetaItem *meta_item;
451 guint8 *p;
452
453 g_return_val_if_fail (meta != NULL, 0);
454
455 p = (guint8 *) meta;
456 p -= G_STRUCT_OFFSET (GstMetaItem, meta);
457 meta_item = (GstMetaItem *) p;
458 return meta_item->seq_num;
459 }
460
461 /**
462 * gst_meta_compare_seqnum:
463 * @meta1: a #GstMeta
464 * @meta2: a #GstMeta
465 *
466 * Meta sequence number compare function. Can be used as #GCompareFunc
467 * or a #GCompareDataFunc.
468 *
469 * Returns: a negative number if @meta1 comes before @meta2, 0 if both metas
470 * have an equal sequence number, or a positive integer if @meta1 comes
471 * after @meta2.
472 *
473 * Since: 1.16
474 */
475 gint
gst_meta_compare_seqnum(const GstMeta * meta1,const GstMeta * meta2)476 gst_meta_compare_seqnum (const GstMeta * meta1, const GstMeta * meta2)
477 {
478 guint64 seqnum1 = gst_meta_get_seqnum (meta1);
479 guint64 seqnum2 = gst_meta_get_seqnum (meta2);
480
481 if (seqnum1 == seqnum2)
482 return 0;
483
484 return (seqnum1 < seqnum2) ? -1 : 1;
485 }
486