From: Guillaume Desmottes <guillaume.desmottes@collabora.com>
Date: Sat, 25 May 2019 17:23:35 +0000 (+0200)
Subject: videometa: document how the meta can be used to negotiate buffers layout
X-Git-Tag: 1.19.3~511^2~885
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=e5c9a921addc3721b73b7dd4fb0a6d6b06049f75;p=platform%2Fupstream%2Fgstreamer.git

videometa: document how the meta can be used to negotiate buffers layout

I'm going to use this new API in gst-omx so an encoder can request
v4l2src to produce buffers matching the encoder stride and slice heights
preventing copies of incoming buffers.
---

diff --git a/gst-libs/gst/video/gstvideometa.h b/gst-libs/gst/video/gstvideometa.h
index 3519a54..4abf173 100644
--- a/gst-libs/gst/video/gstvideometa.h
+++ b/gst-libs/gst/video/gstvideometa.h
@@ -59,6 +59,21 @@ typedef struct _GstVideoCropMeta GstVideoCropMeta;
  * to no padding and no alignment. Since: 1.18
  *
  * Extra buffer metadata describing image properties
+ *
+ * This meta can also be used by downstream elements to specifiy their
+ * buffer layout requirements for upstream. Upstream should try to
+ * fit those requirements, if possible, in order to prevent buffer copies.
+ *
+ * This is done by passing a custom #GstStructure to
+ * gst_query_add_allocation_meta() when handling the ALLOCATION query.
+ * This structure should be named 'video-meta' and can have the following
+ * fields:
+ * - padding-top (uint): extra pixels on the top
+ * - padding-bottom (uint): extra pixels on the bottom
+ * - padding-left (uint): extra pixels on the left side
+ * - padding-right (uint): extra pixels on the right side
+ * The padding fields have the same semantic as #GstVideoMeta.alignment
+ * and so represent the paddings requested on produced video buffers.
  */
 struct _GstVideoMeta {
   GstMeta            meta;