| Message ID | 20190603231905.9536-1-sw@jkqxz.net |
|---|---|
| State | Accepted |
| Commit | 451a51124d5d02f86696420288068e77d8e3e055 |
| Headers | show |
> -----Original Message----- > From: ffmpeg-devel [mailto:ffmpeg-devel-bounces@ffmpeg.org] On Behalf Of > Mark Thompson > Sent: Tuesday, June 04, 2019 7:19 AM > To: ffmpeg-devel@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@ffmpeg.org > https://ffmpeg.org/mailman/listinfo/ffmpeg-devel > > To unsubscribe, visit link above, or email > ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".
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;