hi_mpi_vdec_create_chn

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

Creates a decoding channel based on the configured channel attributes.

Prototype

hi_s32 hi_mpi_vdec_create_chn(hi_vdec_chn chn, const hi_vdec_chn_attr *attr)

Parameters

Parameter	Input/Output	Description
chn	Input	Decoding channel ID. Atlas 350 Accelerator Card: The value range is [0, 256). The maximum number of JPEGD channels is 256. Atlas A3 training product / Atlas A3 inference product : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Among them, a maximum of 256 JPEGD decoding channels and 32 VDEC decoding channels are supported. Atlas A2 training product / Atlas A2 inference product : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Among them, a maximum of 256 JPEGD decoding channels and 32 VDEC decoding channels are supported. Atlas 200I/500 A2 inference product : The value range of this parameter is [0, 128). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 128. Atlas inference product : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256.
attr	Input	Pointer to the decoding channel attributes. If attr is left empty, the error code HI_ERR_VDEC_NULL_PTR is returned. When a setting in the channel attributes pointed by attr exceeds the decoding capability set, the error code HI_ERR_VDEC_ILLEGAL_PARAM is returned.

Parameter

Input/Output

Description

chn

Input

Decoding channel ID.

Atlas 350 Accelerator Card: The value range is [0, 256). The maximum number of JPEGD channels is 256.

Atlas A3 training product / Atlas A3 inference product : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Among them, a maximum of 256 JPEGD decoding channels and 32 VDEC decoding channels are supported.

Atlas A2 training product / Atlas A2 inference product : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Among them, a maximum of 256 JPEGD decoding channels and 32 VDEC decoding channels are supported.

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

Atlas inference product : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256.

attr

Input

Pointer to the decoding channel attributes.

If attr is left empty, the error code HI_ERR_VDEC_NULL_PTR is returned.

When a setting in the channel attributes pointed by attr exceeds the decoding capability set, the error code HI_ERR_VDEC_ILLEGAL_PARAM is returned.

Returns

0: success
Other values: failure. For details, see VDEC/JPEGD Return Codes.

Restrictions

The channel ID of a single device must not be greater than the maximum channel ID.
Before this API call, ensure that a decoding channel has not been created yet or has been destroyed. Otherwise, a failure is returned.
If the OS memory is insufficient, the error code HI_ERR_VDEC_NO_MEM is returned. In this case, you can expand the OS memory as needed.
For H.264 and H.265 decoding, the minimum VB allocation per decoding channel is the sum of the number of reference frames and the number of display frames plus 1. For JPEG decoding, the minimum VB allocation per decoding channel is the number of display frames plus 1. The requested VB allocation varies according to the decode protocol and can be queried by using the hi_vdec_get_pic_buf_size call.
If the H.264 stream to be decoded contains B-frames or the H.265 stream to be decoded supports temporal motion vector prediction (sps_temporal_mvp_enabled_flag = 1), you need to set temporal_mvp_en to 1 when creating a channel. In addition, you need to allocate a video buffer (VB) for outputting the temporal motion vector (Tmv) information of each frame. The size of the VB is much smaller than that of the image VB. The number of required VBs is the number of reference frames plus the number of display frames plus 1. You can obtain the size by calling the hi_vdec_get_tmv_buf_size function, otherwise, errors such as artifacts may occur during decoding..
If B-frames do not need to be decoded during H.264 decoding or streams that support temporal motion vector prediction (sps_temporal_mvp_enabled_flag = 1) do not need to be decoded during H.265 decoding, you can set temporal_mvp_en to 0 when creating a channel. In this case, no TMV information is output, and you do not need to create a TMV VB pool, which saves memory.
Set the requested frame VB size (frame_buf_size) and count (frame_buf_cnt) as well as the requested TMV VB size (tmv_buf_size) based on the stream to be decoded. The decoder allocates private VB pools based on these configurations.
As long as the allocated frame VB and TMV VB are large enough, the decoding channel can decode a stream with any resolution in the valid range. The channel width and height are related only to the size of the stream buffer and SCD buffer.
This API fetches the VDEC result, including the input buffer and output buffer.
For decoding of JPEG(420), JPEG(422), or JPEG(440) input images, if the input width and height are odd numbers, the output width and height are rounded down to the nearest multiples of 2 by default. For decoding of JPEG(444) or JPEG(400) input images, the output width and height are consistent with the input width and height by default. To adjust the width and height alignment mode of the output image, call hi_mpi_vdec_set_jpegd_precision_mode.
In the Ascend virtual instance scenario, the number of channels must meet the following requirements:
In the Ascend virtual instance scenario, the number of VDEC channels is calculated as follows: Number of VDEC channels = (Allocated VDEC hardware units/VDEC hardware units) x 32. If the total number of channels is not an integer, round down the value. The number of JPEGD channels is not affected by the computing power. However, the maximum number of JPEGD+VDEC channels is 256.

In the Ascend virtual instance scenario, the number of VDEC channels is calculated as follows: Number of VDEC channels = (Allocated VDEC hardware units/VDEC hardware units) x 128. If the total number of channels is not an integer, round down the value. The number of JPEGD channels is not affected by the computing power. However, the maximum number of JPEGD+VDEC channels is 128.

In the Ascend virtual instance scenario, the total number of VDEC and JPEGD channels is calculated as follows: Total number of VDEC and JPEGD channels = (Total number of allocated VDEC and JPEGD hardware units/Total number of VDEC and JPEGD hardware units) x 256. If the total number of channels is not an integer, round down the value.

You can run the npu-smi info -t template-info command on the server where AI processor is installed to view the computing power specifications of Ascend virtual instance in each scenario.