hi_mpi_venc_set_roi_attr

Applicability

Product	Supported
Atlas 350 Accelerator Card	☓
Atlas A3 training product / Atlas A3 inference product	☓
Atlas A2 training product / Atlas A2 inference product	☓
Atlas 200I/500 A2 inference product	√
Atlas inference product	√
Atlas training product	☓

Function Description

Sets the ROI attributes of an H.264/H.265 channel. This is used to limit the QP value of the ROI so that it is different from that of other ROIs. For details about the ROI encoding function, see ROI Encoding Function.

Prototype

hi_s32 hi_mpi_venc_set_roi_attr(hi_venc_chn chn, const hi_venc_roi_attr *roi_attr)

Parameters

Parameter	Input/Output	Description
chn	Input	Encoding channel ID. Atlas 200I/500 A2 inference product : The value range of this parameter is [0, 128). The JPEGE, and VENC functions share the same channels, and the maximum number of channels is 128. For the Atlas inference product , the value range of the encoding channel ID is [0, 256). The JPEGE and VENC functions share channels. The maximum number of channels is 256.
roi_attr	Input	Pointer to the ROI parameters.

Parameter

Input/Output

Description

chn

Input

Encoding channel ID.

Atlas 200I/500 A2 inference product : The value range of this parameter is [0, 128). The JPEGE, and VENC functions share the same channels, and the maximum number of channels is 128.

For the Atlas inference product , the value range of the encoding channel ID is [0, 256). The JPEGE and VENC functions share channels. The maximum number of channels is 256.

roi_attr

Input

Pointer to the ROI parameters.

Returns

0: success
Other values: failure. For details, see VENC/JPEGE Return Codes.

Restrictions

This API must be called after an encoding channel is created and before the channel is destroyed. If this API is called during encoding, the configuration takes effect only after the next frame is encoded.
It is recommended that this API be called after an encoding channel is created and before encoding is started, to reduce the number of the API calls during encoding.
It is recommended that hi_mpi_venc_get_roi_attr be called before this API to obtain the ROI configurations of the current encoding channel.
After this API is called, if the current frame is found to be encoded as a Pskip frame, the Pskip frame takes priority.
After this API is called, some ROI QP values may not be the configured values. In an encoding process, residuals of some code blocks are 0, no data needs to be quantized. As a result, a QP value does not take effect, which is normal and does not affect encoding effects.

ROI Encoding Function

ROI encoding is used to encode a region of interest (ROI).

You can configure an ROI to limit its QP value. This can limit the QP value of the ROI so that it is different from that of other ROIs. Currently, only H.264 and H.265 channels support ROI settings. Eight ROIs are provided for users at the same time.

The eight regions can be overlaid with each other and the overlay priority ranges from 0 to 7. The overlay priority indicates the final QP value of image regions when the regions are overlaid. The final QP value is set according to the region with the highest priority. ROIs can be configured in absolute or relative QP mode.

Absolute QP: The QP value of an ROI is the user-defined QP value.
Relative QP: The QP value of an ROI is the sum of the QP value generated during bit rate control and the user-defined QP offset.

The following figure is used as an example, where the QP values of all macroblocks in the image are 25. ROI 0 is set to the absolute QP mode, with the QP value of 10 and the index of 0. ROI 1 is set to the relative QP mode, with the QP value of –10 and the index of 1. When the two regions are overlaid, the QP is set according to the region with the highest priority (ROI 1). The QP value of ROI 0 except the overlapping part is 10. The QP value of ROI 1 is 15 (25 – 10).

Parent topic: Video Encoding (VENC) and JPEG Encoder (JPEGE)