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

2 files changed, 72 insertions, 1 deletions

diff --git a/gst-libs/gst/video/gstvideometa.c b/gst-libs/gst/video/gstvideometa.c
index 58b268071..501efd30b 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 477a29762..cb2ea1c82 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: