Function: vdec_send_frame

aclError aclvdecSendFrame(aclvdecChannelDesc *channelDesc, acldvppStreamDesc *input, acldvppPicDesc *output, aclvdecFrameConfig *config, void* userData)

ret = acl.media.vdec_send_frame(vdec_channel_desc, dvpp_stream_desc, dvpp_pic_desc, vdec_frame_config, user_data)

Feeds a frame (the input buffer, as well as the output buffer) to the decoder for decoding. This API is asynchronous.

vdec_channel_desc: int, pointer address of the channel description.

It must be the same as the dvpp_channel_desc argument passed to the acl.media.dvpp_create_channel call.

Call the acl.media.vdec_set_channel_desc APIs to set attributes of the channel description, including the decoding channel ID, thread, callback function, and video coding protocol.

dvpp_pic_desc: int, pointer address of the output image description. You need to allocate the output buffer in advance.

When dvpp_pic_desc is an input, the user needs to:

• Call acl.media.dvpp_create_pic_desc to create an image description.
• Call the acl.media.dvpp_set_pic_desc APIs to set the data buffer, buffer size, width, height, and format of the output image.
  • The output width and height correspond to four parameters: width, height, width_stride, and height_stride. When the width is less than 16, width_stride must be aligned to 32 instead of 16. If none of the four parameters are set, the input width and height are used. If only some of the four parameters are set, the API returns an error.
  • If the output image format is set in this API call, the setting is applied. Otherwise, the setting in the channel description is applied.
  • For details about the requirements on the output image format, see Functions and Restrictions.

When dvpp_pic_desc is used as an output, the user need to call the acl.media.dvpp_get_pic_desc series in the callback function to obtain the decoded image data. For an interlaced stream, two fields are transmitted every frame. It is normal that one of two transmitted fields has no decoding output and the error code ERR_DECODE_NOPIC = 0x20000 is returned. The decoding output of the interlaced stream is stored in the output buffer corresponding to the odd field.

vdec_frame_config: int, pointer address of the decoding configuration. This parameter is reserved and can be set to 0 currently.

user_data: Python object, pointer address of the user-defined data.

If you want to obtain the sequence number of the decoded frame, define the user_data parameter. Then, the sequence number can be passed to the VDEC callback function to determine the frame to be processed.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

• This API is asynchronous. The API call delivers a task rather than executes a task. After this API is called, call the synchronization API (for example, acl.rt.synchronize_stream) to ensure that the task is complete.

• Before sending data, ensure that a channel is created. Otherwise, an error code is returned.

• Streams must be sent in the unit of frames. Only one complete frame of streams is sent at a time.

• It is not allowed to send an empty stream packet with eos = 0 (stream length is 0 or stream address is empty).

• After all streams are sent, an empty stream packet with EOS = 1 can be sent, indicating the end of the current stream file. After the eos is transmitted, this API returns only after all transmitted frames are decoded and the user callback function is processed.

• Due to stream exception or decoding timeout, the acl.media.vdec_send_frame API may fail to send frames or the EOS frame. You are advised to obtain the return code of this API when writing code. If this API fails to be called, handle the exception.
• acl.rt.launch_callback is encapsulated in acl.media.vdec_send_frame to insert a callback function that needs to be executed to the stream. To implement the VDEC function, acl.rt.launch_callback does not need to be called separately.

For details about the API call sequence and example, see VDEC.