venc_set_roi_attr

Applicability

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

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

C Prototype

hi_s32 hi_mpi_venc_set_roi_attr(hi_venc_chn chn, const hi_venc_roi_attr *roi_attr)

Python Function

ret = acl.himpi.venc_set_roi_attr(chn, roi_attr)

Parameters

Parameter	Description
chn	Int, encoding channel ID. 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. For the Atlas 200I/500 A2 inference product, the value range of the encoding channel ID is [0, 128). The JPEGE and VENC functions share channels. The maximum number of channels is 128.
roi_attr	Dict, ROI parameter dictionary. For details, see hi_venc_roi_attr.

Parameter

Description

chn

Int, encoding channel ID.

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.
For the Atlas 200I/500 A2 inference product, the value range of the encoding channel ID is [0, 128). The JPEGE and VENC functions share channels. The maximum number of channels is 128.

roi_attr

Dict, ROI parameter dictionary. For details, see hi_venc_roi_attr.

Return Value

Return Value	Description
ret	Int, error code. 0 indicates success. Other values indicate failure. For details, see VENC/JPEGE Return Codes.

Restrictions

This API is used to set the ROI attributes of an H.264/H.265 channel.

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 acl.himpi.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 determined as a P-skip frame, the P-skip frame effect is preferred.
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: VENC/JPEGE APIs