subprojects/gstreamer/gst/gstmeta.c

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