GstCustomMeta: simplify API

Move the GstStructure field into public struct for direct access, that's easier than having to call a function to get it. It is not an API/ABI breakage to extend the public structure of a GstMeta because they are always allocated by inside GStreamer. The structure is exposed already by gst_custom_meta_get_structure() which does not return a copy/ref, so it is locked into holding a GstStructure forever anyway. Also add gst_meta_register_custom_simple() because most of the time only a name is required, tags and transform functions are more niche use-case. Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/5385>
2024-06-08 17:19:25 +00:00 · 2023-09-23 13:12:57 -04:00 · 2023-09-23 13:12:57 -04:00 · 452ab184cb
parent 4a9a9ed9fc
commit 452ab184cb
3 changed files with 79 additions and 19 deletions
--- a/girs/Gst-1.0.gir
+++ b/girs/Gst-1.0.gir
@ -10501,11 +10501,17 @@ this functionality yet.</doc>
      </function>
    </enumeration>
    <record name="CustomMeta" c:type="GstCustomMeta" version="1.20">
-      <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.h">Simple typing wrapper around #GstMeta</doc>
+      <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.h">Extra custom metadata. The @structure field is the same as returned by
+gst_custom_meta_get_structure().</doc>
      <source-position filename="../subprojects/gstreamer/gst/gstmeta.h"/>
      <field name="meta" writable="1">
+        <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.h">parent #GstMeta</doc>
        <type name="Meta" c:type="GstMeta"/>
      </field>
+      <field name="structure" writable="1">
+        <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.h">a #GstStructure containing custom metadata. (Since: 1.24)</doc>
+        <type name="Structure" c:type="GstStructure*"/>
+      </field>
      <method name="get_structure" c:identifier="gst_custom_meta_get_structure" version="1.20">
        <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.c">Retrieve the #GstStructure backing a custom meta, the structure's mutability
 is conditioned to the writability of the #GstBuffer @meta is attached to.</doc>
@ -25863,6 +25869,21 @@ access metadata.</doc>
          </parameter>
        </parameters>
      </function>
+      <function name="register_custom_simple" c:identifier="gst_meta_register_custom_simple" version="1.24">
+        <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.c">Simplified version of gst_meta_register_custom(), with no tags and no
+transform function.</doc>
+        <source-position filename="../subprojects/gstreamer/gst/gstmeta.h"/>
+        <return-value transfer-ownership="none">
+          <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.c">a #GstMetaInfo that can be used to access metadata.</doc>
+          <type name="MetaInfo" c:type="const GstMetaInfo*"/>
+        </return-value>
+        <parameters>
+          <parameter name="name" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.c">the name of the #GstMeta implementation</doc>
+            <type name="utf8" c:type="const gchar*"/>
+          </parameter>
+        </parameters>
+      </function>
    </record>
    <bitfield name="MetaFlags" glib:type-name="GstMetaFlags" glib:get-type="gst_meta_flags_get_type" c:type="GstMetaFlags">
      <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.h">Extra metadata flags.</doc>
@ -51649,6 +51670,21 @@ access metadata.</doc>
        </parameter>
      </parameters>
    </function>
+    <function name="meta_register_custom_simple" c:identifier="gst_meta_register_custom_simple" moved-to="Meta.register_custom_simple" version="1.24">
+      <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.c">Simplified version of gst_meta_register_custom(), with no tags and no
+transform function.</doc>
+      <source-position filename="../subprojects/gstreamer/gst/gstmeta.h"/>
+      <return-value transfer-ownership="none">
+        <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.c">a #GstMetaInfo that can be used to access metadata.</doc>
+        <type name="MetaInfo" c:type="const GstMetaInfo*"/>
+      </return-value>
+      <parameters>
+        <parameter name="name" transfer-ownership="none">
+          <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstmeta.c">the name of the #GstMeta implementation</doc>
+          <type name="utf8" c:type="const gchar*"/>
+        </parameter>
+      </parameters>
+    </function>
    <function name="mini_object_replace" c:identifier="gst_mini_object_replace" moved-to="MiniObject.replace">
      <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstminiobject.c">Atomically modifies a pointer to point to a new mini-object.
 The reference count of @olddata is decreased and the reference count of
--- a/subprojects/gstreamer/gst/gstmeta.c
+++ b/subprojects/gstreamer/gst/gstmeta.c
@ -59,13 +59,6 @@ GQuark _gst_meta_transform_copy;
 GQuark _gst_meta_tag_memory;
 GQuark _gst_meta_tag_memory_reference;

-typedef struct
-{
-  GstCustomMeta meta;
-
-  GstStructure *structure;
-} GstCustomMetaImpl;
-
 typedef struct
 {
  GstMetaInfo info;
@ -154,7 +147,7 @@ gst_meta_api_type_register (const gchar * api, const gchar ** tags)
 static gboolean
 custom_init_func (GstMeta * meta, gpointer params, GstBuffer * buffer)
 {
-  GstCustomMetaImpl *cmeta = (GstCustomMetaImpl *) meta;
+  GstCustomMeta *cmeta = (GstCustomMeta *) meta;

  cmeta->structure = gst_structure_new_empty (g_type_name (meta->info->type));

@ -167,7 +160,7 @@ custom_init_func (GstMeta * meta, gpointer params, GstBuffer * buffer)
 static void
 custom_free_func (GstMeta * meta, GstBuffer * buffer)
 {
-  GstCustomMetaImpl *cmeta = (GstCustomMetaImpl *) meta;
+  GstCustomMeta *cmeta = (GstCustomMeta *) meta;

  gst_structure_set_parent_refcount (cmeta->structure, NULL);
  gst_structure_free (cmeta->structure);
@ -177,16 +170,15 @@ static gboolean
 custom_transform_func (GstBuffer * transbuf, GstMeta * meta,
    GstBuffer * buffer, GQuark type, gpointer data)
 {
-  GstCustomMetaImpl *custom, *cmeta = (GstCustomMetaImpl *) meta;
+  GstCustomMeta *custom, *cmeta = (GstCustomMeta *) meta;
  GstMetaInfoImpl *info = (GstMetaInfoImpl *) meta->info;

  if (info->custom_transform_func)
-    return info->custom_transform_func (transbuf, (GstCustomMeta *) meta,
+    return info->custom_transform_func (transbuf, cmeta,
        buffer, type, data, info->custom_transform_user_data);

  if (GST_META_TRANSFORM_IS_COPY (type)) {
-    custom =
-        (GstCustomMetaImpl *) gst_buffer_add_meta (transbuf, meta->info, NULL);
+    custom = (GstCustomMeta *) gst_buffer_add_meta (transbuf, meta->info, NULL);
    gst_structure_set_parent_refcount (custom->structure, NULL);
    gst_structure_take (&custom->structure,
        gst_structure_copy (cmeta->structure));
@ -215,7 +207,7 @@ gst_custom_meta_get_structure (GstCustomMeta * meta)
  g_return_val_if_fail (gst_meta_info_is_custom (((GstMeta *) meta)->info),
      NULL);

-  return ((GstCustomMetaImpl *) meta)->structure;
+  return meta->structure;
 }

 /**
@ -233,7 +225,7 @@ gst_custom_meta_has_name (GstCustomMeta * meta, const gchar * name)
  g_return_val_if_fail (gst_meta_info_is_custom (((GstMeta *) meta)->info),
      FALSE);

-  return gst_structure_has_name (((GstCustomMetaImpl *) meta)->structure, name);
+  return gst_structure_has_name (meta->structure, name);
 }

 /**
@ -281,7 +273,7 @@ gst_meta_register_custom (const gchar * name, const gchar ** tags,
    goto done;

  info = (GstMetaInfoImpl *) gst_meta_register (api, name,
-      sizeof (GstCustomMetaImpl),
+      sizeof (GstCustomMeta),
      custom_init_func, custom_free_func, custom_transform_func);

  if (!info)
@ -298,6 +290,23 @@ done:
  return ret;
 }

+/**
+ * gst_meta_register_custom_simple:
+ * @name: the name of the #GstMeta implementation
+ *
+ * Simplified version of gst_meta_register_custom(), with no tags and no
+ * transform function.
+ *
+ * Returns: (transfer none): a #GstMetaInfo that can be used to access metadata.
+ * Since: 1.24
+ */
+const GstMetaInfo *
+gst_meta_register_custom_simple (const gchar * name)
+{
+  const gchar *tags[] = { NULL };
+  return gst_meta_register_custom (name, tags, NULL, NULL, NULL);
+}
+
 /**
 * gst_meta_info_is_custom:
 *
--- a/subprojects/gstreamer/gst/gstmeta.h
+++ b/subprojects/gstreamer/gst/gstmeta.h
@ -116,14 +116,26 @@ struct _GstMeta {
 };

 /**
- * GstCustomMeta:
+ * GstCustomMeta.structure:
 *
- * Simple typing wrapper around #GstMeta
+ * #GstStructure containing custom metadata.
+ *
+ * Since: 1.24
+ */
+
+/**
+ * GstCustomMeta:
+ * @meta: parent #GstMeta
+ * @structure: a #GstStructure containing custom metadata. (Since: 1.24)
+ *
+ * Extra custom metadata. The @structure field is the same as returned by
+ * gst_custom_meta_get_structure().
 *
 * Since: 1.20
 */
 typedef struct {
  GstMeta meta;
+  GstStructure *structure;
 } GstCustomMeta;

 #include <gst/gstbuffer.h>
@ -267,6 +279,9 @@ const GstMetaInfo *  gst_meta_register_custom   (const gchar *name, const gchar
                                                 GstCustomMetaTransformFunction transform_func,
                                                 gpointer user_data, GDestroyNotify destroy_data);

+GST_API
+const GstMetaInfo *  gst_meta_register_custom_simple (const gchar *name);
+
 GST_API
 gboolean             gst_meta_info_is_custom    (const GstMetaInfo *info);