[FFmpeg-devel,1/5] lavu/frame: Expand ROI documentation

Submitted by Mark Thompson on Feb. 27, 2019, 10 p.m.

Details

Message ID 20190227220023.16040-1-sw@jkqxz.net
State New
Headers show

Commit Message

Mark Thompson Feb. 27, 2019, 10 p.m.
Clarify and add examples for the behaviour of the quantisation offset,
and define how multiple ranges should be handled.
---
 libavutil/frame.h | 62 +++++++++++++++++++++++++++++++++++------------
 1 file changed, 46 insertions(+), 16 deletions(-)

Patch hide | download patch | download mbox

diff --git a/libavutil/frame.h b/libavutil/frame.h
index 8aa3e88367..2cd6c33a90 100644
--- a/libavutil/frame.h
+++ b/libavutil/frame.h
@@ -207,31 +207,61 @@  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.
  *
- * Number of pixels to discard from the top/bottom/left/right border of
- * the frame to obtain the region of interest of the frame.
- * They are encoder dependent and will be extended internally
- * if the codec requires an alignment.
- * 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;
+    /**
+     * Number of pixels to discard from the top/bottom/left/right border of
+     * the frame to obtain the region of interest.
+     *
+     * The constraints on a region are encoder dependent, so the region
+     * actually affected may be slightly larger for alignment or other
+     * reasons.
+     */
     int top;
     int bottom;
     int left;
     int right;
+    /**
+     * 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).
+     *
+     * The extreme qoffset values (-1 and +1) therefore indicate that the
+     * region should be encoded with the best/worst possible quality
+     * regardless of the treatment of the rest of the frame - e.g. if qoffset
+     * is -1 in the 10-bit H.264 example, this region should use a QP of -12
+     * independent of the rest of the frame (which could be good quality with
+     * QP -4, or terrible quality with QP 50, or any other value).
+     */
     AVRational qoffset;
 } AVRegionOfInterest;