From f5855d50ad9a1fb6d5e3e8d2318909dce342c1f1 Mon Sep 17 00:00:00 2001
From: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
Date: Fri, 9 Feb 2018 14:45:08 +0100
Subject: [PATCH] videometa: add support for downstream parameters to ROI meta

The current GstVideoRegionOfInterestMeta API allows elements to detect
and name ROI but doesn't tell anything about how this information is
meant to be consumed by downstream elements.
Typically, encoders may want to tweak their encoding settings for a
given ROI to increase or decrease their quality.
Each encoder has its own set of settings so that's not something that
can be standardized.

This patch adds encoder-specific parameters to the meta which can be
used to configure the encoding of a specific ROI.

A typical use case would be: source ! roi-detector ! encoder
with a buffer probe on the encoder sink pad set by the application.
Thanks to the probe the application will be able to tell to the encoder
how this specific region should be encoded.

Users could also develop their specific roi detectors meant to be used with a
specific encoder and directly putting the encoder parameters when
detecting the ROI.

https://bugzilla.gnome.org/show_bug.cgi?id=793338
---
 gst-libs/gst/video/gstvideometa.c | 63 ++++++++++++++++++++++++++++++-
 gst-libs/gst/video/gstvideometa.h | 10 +++++
 2 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/gst-libs/gst/video/gstvideometa.c b/gst-libs/gst/video/gstvideometa.c
index 58b2680715..501efd30b5 100644
--- a/gst-libs/gst/video/gstvideometa.c
+++ b/gst-libs/gst/video/gstvideometa.c
@@ -736,6 +736,7 @@ gst_video_region_of_interest_meta_init (GstMeta * meta, gpointer params,
   emeta->id = 0;
   emeta->parent_id = 0;
   emeta->x = emeta->y = emeta->w = emeta->h = 0;
+  emeta->params = NULL;
 
   return TRUE;
 }
@@ -743,7 +744,9 @@ gst_video_region_of_interest_meta_init (GstMeta * meta, gpointer params,
 static void
 gst_video_region_of_interest_meta_free (GstMeta * meta, GstBuffer * buffer)
 {
-  // nothing to do
+  GstVideoRegionOfInterestMeta *emeta = (GstVideoRegionOfInterestMeta *) meta;
+
+  g_list_free_full (emeta->params, (GDestroyNotify) gst_structure_free);
 }
 
 const GstMetaInfo *
@@ -850,6 +853,64 @@ gst_buffer_add_video_region_of_interest_meta_id (GstBuffer * buffer,
   return meta;
 }
 
+/**
+ * gst_video_region_of_interest_meta_add_param:
+ * @meta: a #GstVideoRegionOfInterestMeta
+ * @s: (transfer full): a #GstStructure
+ *
+ * Attach element-specific parameters to @meta meant to be used by downstream
+ * elements which may handle this ROI.
+ * The name of @s is used to identify the element these parameters are meant for.
+ *
+ * This is typically used to tell encoders how they should encode this specific region.
+ * For example, a structure named "roi/x264enc" could be used to give the
+ * QP offsets this encoder should use when encoding the region described in @meta.
+ * Multiple parameters can be defined for the same meta so different encoders
+ * can be supported by cross platform applications).
+ *
+ * Since: 1.14
+ */
+void
+gst_video_region_of_interest_meta_add_param (GstVideoRegionOfInterestMeta *
+    meta, GstStructure * s)
+{
+  g_return_if_fail (meta);
+  g_return_if_fail (s);
+
+  meta->params = g_list_append (meta->params, s);
+}
+
+/**
+ * gst_video_region_of_interest_meta_get_param:
+ * @meta: a #GstVideoRegionOfInterestMeta
+ *
+ * Retrieve the parameter for @meta having @name as structure name,
+ * or %NULL if there is none.
+ *
+ * Returns: (transfer none) (nullable): a #GstStructure
+ *
+ * Since: 1.14
+ * @see_also: gst_video_region_of_interest_meta_add_param()
+ */
+GstStructure *
+gst_video_region_of_interest_meta_get_param (GstVideoRegionOfInterestMeta *
+    meta, const gchar * name)
+{
+  GList *l;
+
+  g_return_val_if_fail (meta, NULL);
+  g_return_val_if_fail (name, NULL);
+
+  for (l = meta->params; l; l = g_list_next (l)) {
+    GstStructure *s = l->data;
+
+    if (gst_structure_has_name (s, name))
+      return s;
+  }
+
+  return NULL;
+}
+
 /* Time Code Meta implementation *******************************************/
 
 GType
diff --git a/gst-libs/gst/video/gstvideometa.h b/gst-libs/gst/video/gstvideometa.h
index 477a29762d..cb2ea1c826 100644
--- a/gst-libs/gst/video/gstvideometa.h
+++ b/gst-libs/gst/video/gstvideometa.h
@@ -281,6 +281,7 @@ gboolean  gst_video_gl_texture_upload_meta_upload     (GstVideoGLTextureUploadMe
  * @y: y component of upper-left corner
  * @w: bounding box width
  * @h: bounding box height
+ * @params: list of #GstStructure containing element-specific params for downstream, see gst_video_region_of_interest_meta_add_params(). (Since: 1.14)
  *
  * Extra buffer metadata describing an image region of interest
  */
@@ -295,6 +296,8 @@ typedef struct {
   guint y;
   guint w;
   guint h;
+
+  GList *params;
 } GstVideoRegionOfInterestMeta;
 
 GST_EXPORT
@@ -325,6 +328,13 @@ GstVideoRegionOfInterestMeta *gst_buffer_add_video_region_of_interest_meta_id (G
                                                                                guint         y,
                                                                                guint         w,
                                                                                guint         h);
+GST_EXPORT
+void gst_video_region_of_interest_meta_add_param (GstVideoRegionOfInterestMeta * meta,
+                                                  GstStructure * s);
+
+GST_EXPORT
+GstStructure *gst_video_region_of_interest_meta_get_param (GstVideoRegionOfInterestMeta * meta,
+                                                           const gchar * name);
 
 /**
  * GstVideoTimeCodeMeta: