FFmpeg
Data Fields
AVRegionOfInterest Struct Reference

Structure describing a single Region Of Interest. More...

#include <frame.h>

Data Fields

uint32_t self_size
 Must be set to the size of this data structure (that is, sizeof(AVRegionOfInterest)). More...
 
int top
 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. More...
 
int bottom
 
int left
 
int right
 
AVRational qoffset
 Quantisation offset. More...
 

Detailed Description

Structure describing a single Region Of Interest.

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.

When overlapping regions are defined, the first region containing a given area of the frame applies.

Definition at line 242 of file frame.h.

Field Documentation

◆ self_size

uint32_t AVRegionOfInterest::self_size

Must be set to the size of this data structure (that is, sizeof(AVRegionOfInterest)).

Definition at line 247 of file frame.h.

Referenced by addroi_filter_frame(), dump_roi(), libx265_encode_set_roi(), set_roi_map(), vaapi_encode_issue(), and X264_frame().

◆ top

int AVRegionOfInterest::top

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.

Definition at line 257 of file frame.h.

Referenced by addroi_filter_frame(), dump_roi(), libx265_encode_set_roi(), set_roi_map(), vaapi_encode_issue(), and X264_frame().

◆ bottom

int AVRegionOfInterest::bottom

◆ left

int AVRegionOfInterest::left

◆ right

int AVRegionOfInterest::right

◆ qoffset

AVRational AVRegionOfInterest::qoffset

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.

Definition at line 284 of file frame.h.

Referenced by addroi_filter_frame(), dump_roi(), libx265_encode_set_roi(), set_roi_map(), vaapi_encode_issue(), and X264_frame().


The documentation for this struct was generated from the following file: