virtualenv/FFmpeg
1
0
Fork 0
mirror of https://github.com/FFmpeg/FFmpeg.git synced 2024-11-21 10:55:51 +02:00
Code Issues Releases Activity

lavu/frame: Improve ROI documentation

Browse Source 
Clarify and add examples for the behaviour of the quantisation offset,
and define how multiple ranges should be handled.
This commit is contained in:
Mark Thompson 2019-06-04 00:19:01 +01:00
parent cd3578a8e4
commit 451a51124d
1 changed files with 43 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
libavutil/frame.h
View File

@ -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;