[FFmpeg-devel] [PATCH v2 2/6] lavu/frame: Expand ROI documentation

[Mark Thompson]

Clarify and add examples for the behaviour of the quantisation offset,
and define how multiple ranges should be handled.
---
 libavutil/frame.h | 46 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 34 insertions(+), 12 deletions(-)

diff --git a/libavutil/frame.h b/libavutil/frame.h
index cc3b78d8b6..4933538ad4 100644
--- a/libavutil/frame.h
+++ b/libavutil/frame.h
@@ -207,22 +207,21 @@ typedef struct AVFrameSideData {
 } AVFrameSideData;
 
 /**
- * Structure to hold Region Of Interest.
+ * Structure describing a single Region Of Interest.
  *
- * self_size specifies the size of this data structure. This value
- * should be set to sizeof(AVRegionOfInterest). EINVAL is returned if self_size is zero.
+ * When multiple regions are defined in a single side-data block, they
+ * should be ordered from most to least important - some encoders are only
+ * capable of supporting a limited number of distinct regions, so will have
+ * to truncate the list.
  *
- * If the regions overlap, the last value in the list will be used.
- *
- * qoffset is quant offset, and base rule here:
- * returns EINVAL if AVRational.den is zero.
- * the value (num/den) range is [-1.0, 1.0], clamp to +-1.0 if out of range.
- * 0 means no picture quality change,
- * negative offset asks for better quality (and the best with value -1.0),
- * positive offset asks for worse quality (and the worst with value 1.0).
- * How to explain/implement the different quilaity requirement is encoder dependent.
+ * When overlapping regions are defined, the first region containing a given
+ * area of the frame applies.
  */
 typedef struct AVRegionOfInterest {
+    /**
+     * Must be set to the size of this data structure (that is,
+     * sizeof(AVRegionOfInterest)).
+     */
     uint32_t self_size;
     /**
      * x/y coordinates of the top-left corner and width/height of the
@@ -236,6 +235,29 @@ typedef struct AVRegionOfInterest {
     int y;
     int width;
     int height;
+    /**
+     * Quantisation offset.
+     *
+     * Must be in the range -1 to +1.  A value of zero indicates no quality
+     * change.  A negative value asks for better quality (less quantisation),
+     * while a positive value asks for worse quality (greater quantisation).
+     *
+     * The range is calibrated so that the extreme values indicate the
+     * largest possible offset - if the rest of the frame is encoded with the
+     * worst possible quality, an offset of -1 indicates that this region
+     * should be encoded with the best possible quality anyway.  Intermediate
+     * values are then interpolated in some codec-dependent way.
+     *
+     * For example, in 10-bit H.264 the quantisation parameter varies between
+     * -12 and 51.  A typical qoffset value of -1/10 therefore indicates that
+     * this region should be encoded with a QP around one-tenth of the full
+     * range better than the rest of the frame.  So, if most of the frame
+     * were to be encoded with a QP of around 30, this region would get a QP
+     * of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3).
+     * An extreme value of -1 would indicate that this region should be
+     * encoded with the best possible quality regardless of the treatment of
+     * the rest of the frame - that is, should be encoded at a QP of -12.
+     */
     AVRational qoffset;
 } AVRegionOfInterest;
 
-- 
2.19.2