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
  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
  78 free_info (gpointer data)
  79 {
  80   g_slice_free (GstMetaInfoImpl, data);
  81 }
  82
  83 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
  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
 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
 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
 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
 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
 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 *
 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
 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 *
 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
 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
 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 *
 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 *
 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 *
 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
 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
 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 }