Help Center/ Atlas 300 Application (Model 3000)/ DVPP API Reference/ VDEC Function Interfaces/ VdecCtl
Updated on 2022-03-13 GMT+08:00
View PDF
Share

VdecCtl

Syntax

int VdecCtl(IDVPPAPI*& pIDVPPAPI, int CMD, dvppapi_ctl_msg* MSG, int singleton)

Function

Controls the DVPP executor to implement video decoding. The VdecCtl API is called by using the instance created by CreateVdecApi.

Input
  • IDVPPAPI pointer reference
  • For the VDEC module, the command word (CMD) is DVPP_CTL_VDEC_PROC.
  • Configuration information (MSG) of the VDEC executor in the dvppapi_ctl_msg type. For details about the in pointer in this struct, see Input Parameter: vdec_in_msg.
  • The singleton is reserved for internal use to implement a single pIDVPPAPI instance in the future. It is recommended that the caller set the parameter to 0 currently.

Output

Output buffer in the configuration information (MSG) and output status information of the VDEC (which is all stored in MSG)

Return Value
  • 0: This API is called successfully, but it does not mean that the decoding is successful (because the VDEC is asynchronous).
  • –1: This API fails to be called.

Instructions

The caller calls the VdecCtl function to pass the IDVPPAPI object pointer, the configured dvppapi_ctl_msg, and the correct command word (CMD). The VDEC is asynchronous. When VdecCtl is called, the data in the user stream buffer is copied to the internal input buffer of the VDEC and then returned. Therefore, the decoding is not necessarily successful (only the data is copied successfully) after VdecCtl is called. In addition, after VdecCtl is called, the user stream buffer is released.

Restriction

For a video stream, after you create an instance by calling CreateVdecApi, you must use the same instance to call VdecCtl for video decoding, and then call DestroyVdecApi to release the instance.

Input Parameter: vdec_in_msg

Table 1 Input parameter vdec_in_msg

Member Variable

Description

char video_format[10]

Input video format, for example, h264 or h265. The default value is h264.

Only H.264 and H.265 streams after YUV420SP (NV12 and NV21) encoding are supported.

char image_format[10]

Output frame format, for example, nv12 or nv21. The default value is nv12.

void (*call_back)(FRAME* frame,void * hiai_data)

Callback function. FRAME is the output structure after VDEC decoding. For details, see FRAME structure in Structures and Classes in vdec_in_msg. You can obtain the output result based on this pointer.

It is recommended that only DvppCtl be called in the callback function to output YUV image data. Do not implement other functionality in the callback function. Otherwise, it may take a long time and block the waiting resources during decoding. The maximum consumption allowed by the callback function is related to the frame rate. The calculation formula is as follows: Maximum time consumption = 1/Frame rate. For example, if the frame rate is 30 fps, the maximum time consumption is 0.033s (1/30 fps). If the frame rate is 25 fps, the maximum consumption is 0.04s (1/25 fps).

char* in_buffer

Buffer of input H.264 or H.265 raw video streams.

The buffer for storing the streams (allocated by the user) before decoding is assigned to in_buffer. After VdecCtl is called and a return value is received, this buffer can be freed.

int32_t in_buffer_size

Buffer size of input video streams

void * hiai_data

Pointer to the formal parameter of the output frame callback function after decoding. The object that the pointer points to is defined by the caller.

NOTICE:

Only hiai_data that is passed to the VDEC for the first time is called. To use hiai_data to pass different objects for multiple times, use the following smart pointer object.

std::shared_ptr<HIAI_DATA_SP> hiai_data_sp

If the frame sequence number is not required, this parameter does not need to be specified and the default value is NULL. The frame sequence number is described as follows.

Pointer to the formal parameter of the callback function. HIAI_DATA_SP is the parent class defined in the VDEC. For details, see HIAI_DATA_SP class in Structures and Classes in vdec_in_msg. You can inherit the class to define subclasses. For details, see the sample code in Implementing the VDEC Function. The class object to which this pointer points must be configured with the frame sequence number. Each frame (I-frame, P-frame, or B-frame) maps to a unique sequence number. The frame sequence numbers start from 1 with an increment of 1.

Notes:

  1. The objects of the user-defined subclass hiai_data_sp cannot contain member variables that require large memory. For the decoding of each video stream, the VDEC supports a maximum of 100 hiai_data_sp objects. If the memory requested by the member variables is too large, the memory usage may be too high.
  2. If the objects of the user-defined subclass hiai_data_sp contain member variables that request allocation of memory, free the memory in the destructor function after the memory is allocated to avoid memory leaks.
  3. During video stream decoding, if a hiai_data_sp object is used but an abnormal frame exists in the video stream, the VDEC directly discards the hiai_data_sp object of the abnormal frame. Therefore, you are advised to handle the abnormal frame in the implementation code of the destructor function.
  4. During video stream decoding, if a hiai_data_sp object is used, the reference frame interval of the stream cannot be greater than 30 frames. For example, frame 1 can be referenced for frame 30 rather than frame 31.
  5. The VDEC caches the hiai_data_sp objects passed by the user to a queue. A maximum number of 100 objects are supported. If a frame fails to be decoded, the corresponding hiai_data_sp object is discarded at the earliest time when all the subsequent 30 frames are decoded. For example, if frame 1 fails to be decoded, the corresponding hiai_data_sp object is discarded after frame 31 is decoded. If all frames in the stream are abnormal, the hiai_data_sp object corresponding to frame 1 is discarded when frame 101 starts to be decoded.
  6. Either hiai_data_sp or hiai_data can be used. hiai_data_sp must be used in conjunction with channelId.
  7. If the stream contains B-frames, the frames are numbered according to the display sequence instead of the decoding sequence.

int32_t channelId

ID of the VDEC channel corresponding to the input stream. Different values must be set when different streams are decoded at the same time. The value range is 0–15.

void (*err_report)(VDECERR* vdecErr)

Error reporting callback function, which is used to notify users of decoding exceptions, such as stream errors, hardware faults, and decoder status errors, for subsequent troubleshooting. The VDECERR formal parameter is a structure defined in the VDEC. For details, see VDECERR structure in Structures and Classes in vdec_in_msg.

bool isEOS

End of stream (EOS) flag indicating that the decoding of the current channel is complete. You can ignore this flag. By default, isEOS is set to true in the DestroyVdecApi API so that resources are released when the decoding of the channel ends. If isEOS is set to true, the user-specified configuration is preferentially used in the calling of the VdecCtl API so that resources are released when the decoding of the channel ends. For details, see Implementing the VDEC Function.

int32_t isOneInOneOutMode

Reserved. Use the default value 0.
Parent topic: VDEC Function Interfaces