[FFmpeg-devel] [PATCH v3 1/5] lavu/frame: Improve ROI documentation

[Guo, Yejun]

> -----Original Message-----
> From: ffmpeg-devel [mailto:ffmpeg-devel-bounces at ffmpeg.org] On Behalf Of
> Mark Thompson
> Sent: Tuesday, June 04, 2019 7:19 AM
> To: ffmpeg-devel at ffmpeg.org
> Subject: [FFmpeg-devel] [PATCH v3 1/5] lavu/frame: Improve ROI
> documentation
> 
> Clarify and add examples for the behaviour of the quantisation offset,
> and define how multiple ranges should be handled.
> ---
>  libavutil/frame.h | 59 ++++++++++++++++++++++++++++++++++-------------
>  1 file changed, 43 insertions(+), 16 deletions(-)
> 
> diff --git a/libavutil/frame.h b/libavutil/frame.h
> index 8aa3e88367..3fe6d75c8b 100644
> --- a/libavutil/frame.h
> +++ b/libavutil/frame.h
> @@ -207,31 +207,58 @@ 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;
> +    /**
> +     * Distance in pixels from the top edge of the frame to the top and
> +     * bottom edges and from the left edge of the frame to the left and
> +     * right edges of the rectangle defining this 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).
> +     * 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;
> 

LGTM, thanks.

> --
> 2.20.1
> 
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel at ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
> 
> To unsubscribe, visit link above, or email
> ffmpeg-devel-request at ffmpeg.org with subject "unsubscribe".