MI VDEC API

version 2.11


1. OVERVIEW


1.1. Module Description

The video decoder module is used for fulfilling functions such as creating decoding channel, transmitting and controlling code streams, scaling output image, etc.

There are two main types of input sources for vdec module:

  • User reads stream file and sends data to decoding module

  • User sends the stream data received by the network directly to the decoding module

Table 1-1: Chip Decoding Specifications

Chip Hardware Decoding Module Maximum Number of Channels Protocol Resolution Range Maximum Performance
Taiyaki DEC2.0 16 H.264/H.265 H.264: max 8192x8192, min 32x32 H.265: max 8192x8192, min 8x8 H.264: 3840x2160@30fps H.265: 3840x2160@30fps
Takoyaki DEC2.0 4 H.264/H.265 H.264: max 8192x8192, min 32x32 H.265: max 8192x8192, min 8x8 H.264: 1920x1080@30fps H.265: 1920x1080@30fps
Tiramisu DEC2.0 16 H.264/H.265 H.264: max 4096x4096, min 176x128 H.265: max 4096x4096, min 176x128 H.264: 3840x2160@30fps H.265: 3840x2160@30fps

1.2. Decoding Flowchart

1.2.1. Taiyaki Data Flowchart

Figure 1-1: VDEC Data Flowchart

1.2.2. Takoyaki Data Flowchart

Figure 1-2: VDEC Data Flowchart

1.2.3. Tiramisu Data Flowchart

Figure 1-3: VDEC Data Flowchart


1.3. Key Concepts

  • Bitstream send mode

    VDEC decoder provides two ways to send bitstream:

    • Send by stream (E_MI_VDEC_VIDEO_MODE_STREAM): The user can send any length of bitstream to the decoder each time, and the decoding and splicing process of the bitstream frame is completed by the decoder. For H.264/H.265, the end of the current bitstream frame can only be confirmed after receiving the next bitstream. So, in this mode, the image will not be immediately output after inputting a frame of H.264/H.265 bitstream.

    • Send by frame (E_MI_VDEC_VIDEO_MODE_FRAME): Each time the user sends a complete frame of code stream to the decoder and call once the send interface, the decoder considers that the frame coded stream has ended and begins to decode.

    Bitstream send mode can be set in the interface MI_VDEC_CreateChn.

  • Image output order

    According to H.264/H.265 protocol, the decoded image may not be output immediately after decoding. VDEC decoder can output as soon as possible by setting different image output modes. Image output methods include the following two:

    • Decoding order: the decoded image is output in the order of decoding.

    • Display order: the decoded image is output according to the display order in the protocol.

    According to H.264/H.265 protocol, the decoding order of video may be inconsistent with the display order of decoded image. For example, when decoding B frame, P frame before and after B frame is needed as reference, so P frame after B frame is decoded before B frame, but B frame is output before P frame. Output in decoding order is a necessary condition for fast output. If the user chooses to output in decoding order, the decoding order and the display order of the code stream should be the same.

    The combination of sending code stream by frame and outputting by decoding sequence can achieve the purpose of fast decoding and output. The user must ensure that a complete frame code stream is sent each time, and that the decoding sequence and display sequence of the code stream are the same.

    Image output mode “eOutputOrder” can be set in the interface MI_VDEC_SetChnParam.

  • PTS

    When sending a bitstream in frame mode, the decoded output image time stamp PTS is the PTS sent by the user in the MI_VDEC_SendStream interface, and the decoder will not change this value. If the PTS value configured by the user is 0, it means that the frame rate is not controlled by the user, but by the video display module (disp). If the PTS value set by the user is -1, this image will not be displayed by the video display module (disp). If it is another value, it means that the video display module (disp) will control the frame rate according to the PTS value set by the user.

    Note: The PTS value of 0 and non-0 cannot be mixed.

    When sending code stream in stream mode, PTS of decoded output image is set to 0, which means that the frame rate is not controlled by the user, but by the video display module (disp).

  • Bitstream buffer

    The bitstream buffer is used by the user to cache the coded stream input and send it to the decoder for decoding. There is no fixed formula for calculating the size of stream buffer.

    Generally, according to experience, if the resolution is less than or equal to D1, the recommended value is 512KB; if the resolution is in the range (d1,1080p], the recommended value is 1MB; if the resolution is in the range (1080p,4K], the recommended value is 2MB. Users can choose reasonable value settings according to actual needs.

  • eDpbBufMode

    By setting eDpbBufMode, users can set different buffer modes for decoding. According to different scenarios, different buffer modes can be selected to save memory. When E_MI_VDEC_DPB_MODE_NORMAL is set, memory cannot be saved. When E_MI_VDEC_DPB_MODE_INPLACE_ONE_BUF is set, it can only decode a stream type that contains only one reference frame and only one DPB buffer is needed; when E_MI_VDEC_DPB_MODE_INPLACE_TWO_BUF is set, it can only decode a stream type that contains only two reference frames and only two DPB buffer are needed.

  • u32RefFrameNum

    u32refframenum represents the maximum number of reference frames. In the actual scene, the memory of the system may not be infinite. So the user can limit the number of reference frames according to the definition of the product, so as to prompt the user that the current code stream may have exceeded the specification. If the user sets eDpbBufMode to E_MI_VDEC_DPB_MODE_INPLACE_ONE_BUF or E_MI_VDEC_DPB_MODE_INPLACE_TWO_BUF, the parameter is invalid. If the user sets edpbbufmode to E_MI_VDEC_DPB_MODE_NORMAL and the number of reference frames is less than what the decoder actually needed, the decoded image may be abnormal or decoding timeout may happen.

  • Output image scaling

    The user calls MI_VDEC_SetOutputPortAttr to zoom the output image to the resolution required by the image.

    Note that the decoder only supports scaling down the output image.

  • Low latency

    The latency here refers to the latency generated by reordering the image queue to be displayed after decoding the B frame. When decoding the coded stream without B frame, the decoding order and the display order are the same, so there is no latency output, that is, the latency is low. When decoding bitstreams containing B frame, output latency will occur, because B frame has forward and backward reference, making it necessary to wait for the reference image to be decoded before the current frame can be decoded, and besides, the decoded image needs to be reordered.

    These two modes need to be completed by setting bDisableLowLatency. The default value is FALSE, and the user does not need to set it. To decode bitstream with B frame, you need to set bDisableLowLatency to TRUE.

    Note that bDisableLowLatency is TRUE and cannot be used to decode non-B frame streams.

  • Output buffer mode

    The user can call MI_VDEC_SetOutputPortLayoutMode to set the output buffer mode. This interface is only used for chip Takoyaki . This interface can be called when the user needs to manually control the output buffer mode.

    If E_MI_VDEC_OUTBUF_LAYOUT_LINEAR is set, it indicates that the output buffer is in linear mode.

    If E_MI_VDEC_OUTBUF_LAYOUT_TILE is set, it indicates that the output buffer is in tile mode.

    If E_MI_VDEC_OUTBUF_LAYOUT_AUTO is set, it indicates that the output buffer will automatically switch between linear mode and tile mode.

  • Crop the output image

    The user can call MI_VDEC_SetDestCrop to crop the output image. The coordinate X and the width must be aligned with 16. The coordinate Y and the height must be aligned with 2. If calling MI_VDEC_SetDestCrop and MI_VDEC_SetOutputPortAttr together, make sure that the crop size is not greater than the scaling size. Otherwise, an error code of illegal parameter (MI_ERR_VDEC_ILLEGAL_PARAM) will be returned.

    The relationship between crop and scale is as shown below:

    1. If neither scale nor crop is enabled, the output image is the source resolution.

    2. If scale is enabled but crop is disabled, the output image is the same size as the scale info.

    3. If scale is disabled but crop is enabled, the output image is the same size as the crop info.

    4. If both scale and crop are enabled, the image will take the scale size as a reference, then outputs a cropped image.

    If enabling the crop, it will output the same size as the crop info.


2. API LIST

This module provides the following APIs:

Name of API Function
MI_VDEC_InitDev Initialize decoding device
MI_VDEC_DeInitDev De initialize decoding device
MI_VDEC_CreateChn Create a decoding channel
MI_VDEC_DestroyChn Destroy a decoding channel
MI_VDEC_GetChnAttr Get decoding channel attribute
MI_VDEC_StartChn Decoding channel starts to receive code stream
MI_VDEC_StopChn Decoding channel stops receiving code stream
MI_VDEC_GetChnStat Get decoding channel status
MI_VDEC_FlushChn Clear decoding channel cache
MI_VDEC_ResetChn Reset decoding channel
MI_VDEC_SetChnParam Set decoding channel parameter
MI_VDEC_GetChnParam Get decoding channel parameter
MI_VDEC_SendStream Send code stream data to decoding channel
MI_VDEC_GetUserData Get decoding channel user data
MI_VDEC_ReleaseUserData Release decoding channel user data
MI_VDEC_SetDisplayMode Set decoding channel display mode
MI_VDEC_GetDisplayMode Get decoding channel display mode
MI_VDEC_SetOutputPortAttr Set decoding channel output port attribute
MI_VDEC_GetOutputPortAttr Get decoding channel output port attribute
MI_VDEC_SetOutputPortLayoutMode Set output port layout mode
MI_VDEC_GetOutputPortLayoutMode Get output port layout mode
MI_VDEC_SetDestCrop Set the decoded image cropping attribute
MI_VDEC_GetDestCrop Get the decoded image cropping attribute

2.1. MI_VDEC_InitDev

  • Function

    Initialize decoding device.

  • Syntax

    MI_S32 MI_VDEC_InitDev(MI_VDEC_InitParam_t *pstInitParam);
    
  • Parameter

    Parameter Name Description Input/Output
    pstInitParam Decoding initialization parameters pointer.
    Data type: MI_VDEC_InitParam_t
    Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_FAILED Unsuccessful
    MI_ERR_VDEC_INITED Device to be initialized is already initialized.
    MI_ERR_VDEC_NULL_PTR Null pointer
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • This interface is optional. There is no need to call this interface if only the default initialization parameters are used.

    • If you choose to use this interface, you must call it before creating a decoding channel; otherwise, it will return the error code MI_ERR_VDEC_INITED which means the device has been initialized.

    • If the interface is called repeatedly, the error code MI_ERR_VDEC_INITED will be returned.

  • Example

    MI_S32 StartVdec(void)
    {
        MI_S32 s32Ret = MI_ERR_VDEC_FAILED;
        MI_VDEC_CHN VdecChn = 0;
        MI_VDEC_InitParam_t stInitParam;
        MI_VDEC_ChnAttr_t stChnAttr;
    
        memset(&stInitParam, 0x0, sizeof(MI_VDEC_InitParam_t));
        memset(&stChnAttr, 0x0, sizeof(MI_VDEC_ChnAttr_t));
    
        stInitParam.bDisableLowLatency = FALSE;
        s32Ret = MI_VDEC_InitDev(&stInitParam);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_InitDev failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        VdecChn = 0;
        stChnAttr.eCodecType    = E_MI_VDEC_CODEC_TYPE_H264;
        stChnAttr.u32PicWidth   = 1920;
        stChnAttr.u32PicHeight  = 1080;
        stChnAttr.eVideoMode    = E_MI_VDEC_VIDEO_MODE_FRAME;
        stChnAttr.u32BufSize    = 1024*1024;
        stChnAttr.eDpbBufMode   = E_MI_VDEC_DPB_MODE_INPLACE_ONE_BUF;
        stChnAttr.stVdecVideoAttr.u32RefFrameNum = 1;
        stChnAttr.u32Priority = 0;
    
        s32Ret = MI_VDEC_CreateChn(VdecChn, &stChnAttr);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_CreateChn failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        return MI_SUCCESS;
    }
    

2.2. MI_VDEC_DeInitDev

  • Function

    De initialize decoding device.

  • Syntax

    MI_S32 MI_VDEC_DeInitDev(void);
    
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_FAILED Unsuccessful
    MI_ERR_VDEC_NOT_INIT Device is not initialized.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • This interface is optional.

    • If you choose to use this interface, you must call it after destroying the decoding channel; otherwise, it will return the error code MI_ERR_VDEC_NOT_INIT which means the device has not been initialized.

    • If the interface is called repeatedly, the error code MI_ERR_VDEC_NOT_INIT will be returned.

  • Example

    MI_S32 StopVdec(void)
    {
        MI_S32 s32Ret = MI_ERR_VDEC_FAILED;
        MI_VDEC_CHN VdecChn = 0;
    
        s32Ret = MI_VDEC_DestroyChn(VdecChn);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_DestroyChn failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        //Confirm that you have destroyed all channels
        s32Ret = MI_VDEC_DeInitDev();
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_DeInitDev failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        return MI_SUCCESS;
    }
    

2.3. MI_VDEC_CreateChn

  • Function

    Create a video decoding channel

  • Syntax

    MI_S32 MI_VDEC_CreateChn(MI_VDEC_CHN VdecChn, MI_VDEC_ChnAttr_t *pstChnAttr)
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Decoding channel number
    Range: [0, MI_VDEC_MAX_CHN_NUM)
    Input
    pstChnAttr Decoding channel attribute pointer
    Data type: MI_VDEC_ChnAttr_t
    Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_FAILED Unsuccessful
    MI_ERR_VDEC_INVALID_CHNID Invalid Channel ID.
    Range: [0, MI_VDEC_MAX_CHN_NUM).
    MI_ERR_VDEC_NOT_INIT Module not successfully initialized
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter or inputted parameter exceeding channel decoding capability.
    MI_ERR_VDEC_CHN_EXIST Channel to be created already exists.
    MI_ERR_VDEC_NOMEM Memory allocation fails (due to for example insufficient memory).
    MI_ERR_VDEC_NULL_PTR Null pointer
    MI_ERR_VDEC_NOT_SUPPORT This operation or function is not supported.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    The channel number cannot exceed the maximum channel range allowed.

  • Example

    MI_S32 StartVdec(void)
    {
        MI_S32 s32Ret = MI_ERR_VDEC_FAILED;
        MI_VDEC_CHN VdecChn = 0;
        MI_VDEC_DisplayMode_e eDisplayMode = E_MI_VDEC_DISPLAY_MODE_MAX;
        MI_VDEC_ChnAttr_t stChnAttr;
        MI_VDEC_OutputPortAttr_t stOutputPortAttr;
    
        memset(&stChnAttr, 0x0, sizeof(MI_VDEC_ChnAttr_t));
        memset(&stOutputPortAttr, 0x0, sizeof(MI_VDEC_OutputPortAttr_t));
    
        VdecChn = 0;
        stChnAttr.eCodecType    = E_MI_VDEC_CODEC_TYPE_H264;
        stChnAttr.u32PicWidth   = 1920;
        stChnAttr.u32PicHeight  = 1080;
        stChnAttr.eVideoMode    = E_MI_VDEC_VIDEO_MODE_FRAME;
        stChnAttr.u32BufSize    = 1024*1024;
        stChnAttr.eDpbBufMode   = E_MI_VDEC_DPB_MODE_INPLACE_ONE_BUF;
        stChnAttr.stVdecVideoAttr.u32RefFrameNum = 1;
        stChnAttr.u32Priority = 0;
    
        s32Ret = MI_VDEC_CreateChn(VdecChn, &stChnAttr);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_CreateChn failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        eDisplayMode = E_MI_VDEC_DISPLAY_MODE_PLAYBACK;
        s32Ret = MI_VDEC_SetDisplayMode (VdecChn, eDisplayMode);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_SetDisplayMode failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        s32Ret = MI_VDEC_StartChn(VdecChn);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_StartChn failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        stOutputPortAttr.u16Width  = 720;
        stOutputPortAttr.u16Height = 576;
        s32Ret = MI_VDEC_SetOutputPortAttr(VdecChn, &stOutputPortAttr);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_SetOutputPortAttr failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
    stCropCfg.bEnable   = TRUE;
    stCropCfg.stRect.u16X  = 0;
    stCropCfg.stRect.u16Y  = 0;    
    stCropCfg.stRect.u16Width = 640;
    stCropCfg.stRect.u16Height = 480;
    s32Ret = MI_S32 MI_VDEC_SetDestCrop(VdecChn, &stCropCfg);
    if(MI_SUCCESS != s32Ret)
    {
        printf("MI_VDEC_SetDestCrop failed, s32Ret: 0x%x.\n", s32Ret);
        return s32Ret;
    }
    
        return MI_SUCCESS;
    }
    

2.4. MI_VDEC_DestroyChn

  • Function

    Destroy a video decoding channel.

  • Syntax

    MI_S32 MI_VDEC_DestroyChn(MI_VDEC_CHN VdecChn);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number.
    Range: [0, MI_VDEC_MAX_CHN_NUM).
    Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_NOT_STOP Channel cannot be closed before code stream reception is stopped.
    MI_ERR_VDEC_CHN_UNEXIST Channel does not exist.
    MI_ERR_VDEC_NOT_INIT Module not successfully initialized
    MI_ERR_VDEC_NOT_SUPPORT This operation or function is not supported.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    Before destroying a channel, code stream reception should be stopped first.

  • Example

    MI_S32 StopVdec(void)
    {
        MI_S32 s32Ret = MI_ERR_VDEC_FAILED;
        MI_VDEC_CHN VdecChn = 0;
    
        // Destroy send stream thread
        ...
    
        s32Ret = MI_VDEC_StopChn(VdecChn);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_StopChn failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        s32Ret = MI_VDEC_DestroyChn(VdecChn);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_DestroyChn failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        return MI_SUCCESS;
    }
    

2.5. MI_VDEC_GetChnAttr

  • Function

    Get video decoding channel attribute.

  • Syntax

    MI_S32 MI_VDEC_GetChnAttr(MI_VDEC_CHN VdecChn, MI_VDEC_ChnAttr_t *pstChnAttr);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number.
    Range: [0, MI_VDEC_MAX_CHN_NUM).
    Input
    pstChnAttr Decoding channel attribute pointer.
    Data type: MI_VDEC_ChnAttr_t.
    Output
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_CHN_UNEXIST Channel does not exist.
    MI_ERR_VDEC_NOT_INIT Module not successfully initialized
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a


2.6. MI_VDEC_StartChn

  • Function

    Start the video decoder.

  • Syntax

    MI_S32 MI_VDEC_StartChn(MI_VDEC_CHN VdecChn);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed.
    MI_ERR_VDEC_NOT_INIT Module not initialized.
    MI_ERR_VDEC_NOT_PERM Illegal operation, for example, no user image is allowed to be inserted before performing this operation.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • Before starting the reception of code stream, be sure the channel to be used has been created; otherwise, an error code of channel not created (MI_ERR_VDEC_CHN_UNEXIST) will be returned.

    • Before starting the reception of code stream, be sure user image insertion is disabled; otherwise, an error code of illegal operation (MI_ERR_VDEC_NOT_PERM) will be returned.

    • Only when code stream reception has been started will it be possible to send code stream successfully by calling MI_VDEC_SendStream.

    • Repeated calling of the code stream receiving interface will return a successful message.

  • Example

    See the example of MI_VDEC_CreateChn.


2.7. MI_VDEC_StopChn

  • Function

    Stop the video decoder.

  • Syntax

    MI_S32 MI_VDEC_Stop(MI_VDEC_CHN VdecChn);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_FAILED Unsuccessful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_NOT_START Channel not started or already stopped
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed.
    MI_ERR_VDEC_NOT_INIT System not initialized or related module not mounted
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • Calling the code stream sending interface MI_VDEC_SendStream after calling this function will return an error message.

    • Repeated calling of the code stream reception stop interface will return an MI_ERR_VDEC_CHN_NOT_START error message.

  • Example

    See the example of MI_VDEC_DestroyChn.


2.8. MI_VDEC_GetChnStat

  • Function

    Get the decoding channel status.

  • Syntax

    MI_S32 MI_VDEC_GetChnStat (MI_VDEC_CHN VdecChn, MI_VDEC_ChnStat_t *pstChnStat);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstChnStat Decoding channel status structure pointer. Output
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_FAILED Unsuccessful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Null pointer.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Example

    See the example of MI_VDEC_SendStream.


2.9. MI_VDEC_FlushChn

  • Function

    Clear decoding channel cache.

  • Syntax

    MI_S32 MI_VDEC_FlushChn(MI_VDEC_CHN VdecChn);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number.Range: [0, MI_VDEC_MAX_CHN_NUM). Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_FAILED Unsuccessful.
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_CHN_NOT_START Channel not started or already stopped.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    This interface can be used to clear the cached data of decoding channel when switching to other GOP during decoding, so that decoding can continue.


2.10. MI_VDEC_ResetChn

  • Function

    Reset a decoding channel.

  • Syntax

    MI_S32 MI_VDEC_ResetChn(MI_VDEC_CHN VdecChn);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number.Range: [0, MI_VDEC_MAX_CHN_NUM). Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_FAILED Unsuccessful.
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_NOT_PERM Unable to reset channel. This function cannot be called along with the MI_VDEC_SendStream.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    This interface is currently not supported.


2.11. MI_VDEC_SetChnParam

  • Function

    Set decoding channel parameter.

  • Syntax

    MI_S32 MI_VDEC_SetChnParam(MI_VDEC_CHN VdecChn, MI_VDEC_ChnParam_t* pstChnParam);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number.Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstChnParam Channel parameter. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_NOT_PERM Illegal operation. Before calling this function, call MI_VDEC_StopChn to stop channel decoding first.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • This interface is currently not supported.

    • This interface does not support JPEG decoding.


2.12. MI_VDEC_GetChnParam

  • Function

    Get decoding channel parameter.

  • Syntax

    MI_S32 MI_VDEC_GetChnParam(MI_VDEC_CHN VdecChn, MI_VDEC_ChnParam_t* pstChnParam);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstChnParam Channel parameter. Output
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    This interface is currently not supported.


2.13. MI_VDEC_SendStream

  • Function

    Send code stream data to decoding channel.

  • Syntax

    MI_S32 MI_VDEC_SendStream(MI_VDEC_CHN VdecChn,
    MI_VDEC_VideoStream_t *pstVideoStream, MI_S32
    s32MilliSec);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstVideoStream Decoding code stream data pointer. Please refer to the definition given in MI_VDEC_VideoStream_t. Input
    s32MilliSec Set data push timeout time parameter. Range:
    -1: Blocked.
    0: Not blocked.
    Positive values: Timeout time, unit is ms.
    Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed.
    MI_ERR_VDEC_NOT_PERM Illegal operation, e.g. channel not ready.
    MI_ERR_VDEC_BUF_FULL Data frame buffer full after decoding.
    MI_ERR_VDEC_BUSY Data frame buffer full before decoding.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • Frame-based and stream-based data transmissions are both supported. For frame-based case, an entire data frame should be transmitted for each transmission at a time.Stream-based data transmissions is currently not supported.

    • The frame data sent at a time should not exceed half of the size of the stream buffer.

  • Example

    An entire data frame must be sent for each transmission in frame-based transmission. If the current data frame failed during the transmission, re-transmission is required.

    MI_S32 VdecSendStream(void)
    {
        MI_S32 s32Ret = MI_ERR_VDEC_FAILED;
        MI_VDEC_CHN VdecChn = 0;
        MI_S32 s32MilliSec = 0;
        MI_VDEC_VideoStream_t stVideoStream;
        MI_VDEC_ChnStat_t stChnStat;
    
        do{
            //Check if you need stop sending stream
            if(bStop)
            {
                break;
            }
    
            memset(&stChnStat, 0x0, sizeof(MI_VDEC_ChnStat_t));
            s32Ret = MI_VDEC_GetChnStat(VdecChn, &stChnStat);
            if(MI_SUCCESS != s32Ret)
            {
                printf("MI_VDEC_SendStream failed, s32Ret: 0x%x.\n", s32Ret);
                return s32Ret;
            }
    
            //suggest to check chn status
            if(stChnStat.u32LeftStreamBytes < u32StreamSize)
            {
                continue;
            }
    
            memset(&stVideoStream, 0x0, sizeof(MI_VDEC_VideoStream_t));
            stVideoStream.pu8Addr = pu8StreamBuf;
            stVideoStream.u32Len  = u32StreamSize;
            stVideoStream.u64PTS  = u64StreamPts;
            stVideoStream.bEndOfFrame  = TRUE;
            stVideoStream.bEndOfStream = FALSE;
            s32MilliSec = 30;                    //30ms
            s32Ret = MI_VDEC_SendStream(VdecChn, &stVideoStream, s32MilliSec);
            if(MI_SUCCESS != s32Ret)
            {
                printf("MI_VDEC_SendStream failed, s32Ret: 0x%x.\n", s32Ret);
                continue;
            }
        }while(!ShouldStop);
    
        return MI_SUCCESS;
    }
    

2.14. MI_VDEC_GetUserData

  • Function

    Get decoding channel user data.

  • Syntax

    MI_S32 MI_VDEC_GetUserData(MI_VDEC_CHN VdecChn,
    MI_VDEC_UserData_t  *pstUserData, MI_S32 s32MilliSec);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    s32MilliSec Get user data timeout definition. Range:
    -1: Blocked.
    0: Not blocked.
    Positive values: Timeout time, unit is ms.
    Input
    pstUserData Decoded user data. Please refer to the definition given in MI_VDEC_UserData_t. Output
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed.
    MI_ERR_VDEC_NOT_PERM Illegal operation, e.g. channel not ready.
    MI_ERR_VDEC_BUF_FULL Data frame buffer full after decoding.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • This interface is currently not supported.

    • If the user data is H.264/H.265 encoded, a section of private user data will be inserted into the code stream SEI segment.

    • JPEG decoding channel does not support getting user data.

    • After MI_VDEC_GetUserData got the decoded user data, MI_VDEC_ReleaseUserData should be called to release the data gotten.

    • If user data is not gotten in real-time, user data buffer can be full, causing user data to be discarded.


2.15. MI_VDEC_ReleaseUserData

  • Function

    Release user data.

  • Syntax

    MI_S32 MI_VDEC_ReleaseUserData(MI_VDEC_CHN VdecChn,
    MI_VDEC_UserData_t * pstUserData);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstUserData Decoded user data pointer, gotten by MI_VDEC_UserData_t interface. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed.
    MI_ERR_VDEC_NOT_PERM Illegal operation, e.g. channel not ready.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • This interface is currently not supported.

    • This interface must be used in combination with MI_VDEC_GetUserData. The gotten data should be released immediately after use. If not, the buffer can be full, thus causing user data to be discarded.


2.16. MI_VDEC_SetDisplayMode

  • Function

    Set display mode.

  • Syntax

    MI_S32 MI_VDEC_SetDisplayMode(MI_VDEC_CHN VdecChn,
    MI_VDEC_DisplayMode_e eDisplayMode);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    eDisplayMode Display mode enumeration. Please refer to the definition given in MI_VDEC_DisplayMode_e. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Example

    See the example of MI_VDEC_CreateChn.


2.17. MI_VDEC_GetDisplayMode

  • Function

    Get display mode.

  • Syntax

    MI_S32 MI_VDEC_GetDisplayMode(MI_VDEC_CHN VdecChn,
    MI_VDEC_DisplayMode_e *peDisplayMode);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    peDisplayMode Display mode enumeration pointer. Please refer to the definition given in MI_VDEC_DisplayMode_e. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Example

    See the example of MI_VDEC_DestroyChn.


2.18. MI_VDEC_SetOutputPortAttr

  • Function

    Set decoding channel output port attribute

  • Syntax

    MI_S32 MI_VDEC_SetOutputPortAttr (MI_VDEC_CHN VdecChn,
    MI_VDEC_OutputPortAttr_t *pstOutputPortAttr);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstOutputPortAttr Output port attribute. Please refer to the definition given in MI_VDEC_OutputPortAttr_t. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_NULL_PTR Null pointer
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • Before calling this function, be sure the channel to be used has been created; otherwise, an error code of channel not created (MI_ERR_VDEC_CHN_UNEXIST) will be returned.

    • Scaling range[⅛, 1].

    • Scaling up is not supported.

  • Example

    See the example of MI_VDEC_CreateChn.


2.19. MI_VDEC_GetOutputPortAttr

  • Function

    Get decoding channel output port attribute.

  • Syntax

    MI_S32 MI_VDEC_GetOutputPortAttr(MI_VDEC_CHN VdecChn,
    MI_VDEC_OutputPortAttr_t *pstOutputPortAttr);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstOutputPortAttr Output port attribute. Please refer to the definition given in MI_VDEC_OutputPortAttr_t Output
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_NULL_PTR Null pointer.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    Before calling this function, be sure the channel to be used has been created; otherwise, an error code of channel not created (MI_ERR_VDEC_CHN_UNEXIST) will be returned.

  • Example

    See the example of MI_VDEC_DestroyChn.


2.20. MI_VDEC_SetOutputPortLayoutMode

  • Function

    Set output port layout mode

  • Syntax

    MI_S32 MI_VDEC_SetOutputPortLayoutMode(MI_VDEC_OutbufLayoutMode_e eBufTileMode);
    
  • Parameter

    Parameter Name Description Input/Output
    eBufTileMode Output buffer mode. Please refer to the definition given in MI_VDEC_OutbufLayoutMode_e. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_NOT_INIT Device not initialized.
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    Before calling this function, be sure the device has been initialized; otherwise, an error code of channel not created (MI_ERR_VDEC_NOT_INIT) will be returned.

  • Example

    MI_S32 StartVdec(void)
    {
        MI_S32 s32Ret = MI_ERR_VDEC_FAILED;
        MI_VDEC_CHN VdecChn = 0;
        MI_VDEC_OutbufLayoutMode_e eBufTileMode = E_MI_VDEC_OUTBUF_LAYOUT_MAX;
        MI_VDEC_ChnAttr_t stChnAttr;
    
        memset(&stChnAttr, 0x0, sizeof(MI_VDEC_ChnAttr_t));
    
        eBufTileMode = E_MI_VDEC_OUTBUF_LAYOUT_AUTO;
        s32Ret = MI_VDEC_SetOutputPortLayoutMode(eBufTileMode) ;
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_SetOutputPortLayoutMode failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        VdecChn = 0;
        stChnAttr.eCodecType    = E_MI_VDEC_CODEC_TYPE_H264;
        stChnAttr.u32PicWidth   = 1920;
        stChnAttr.u32PicHeight  = 1080;
        stChnAttr.eVideoMode    = E_MI_VDEC_VIDEO_MODE_FRAME;
        stChnAttr.u32BufSize    = 1024*1024;
        stChnAttr.eDpbBufMode   = E_MI_VDEC_DPB_MODE_INPLACE_ONE_BUF;
        stChnAttr.stVdecVideoAttr.u32RefFrameNum = 1;
        stChnAttr.u32Priority = 0;
    
        s32Ret = MI_VDEC_CreateChn(VdecChn, &stChnAttr);
        if(MI_SUCCESS != s32Ret)
        {
            printf("MI_VDEC_CreateChn failed, s32Ret: 0x%x.\n", s32Ret);
            return s32Ret;
        }
    
        return MI_SUCCESS;
    }
    

2.21. MI_VDEC_GetOutputPortLayoutMode

  • Function

    Get output port layout mode

  • Syntax

    MI_S32  MI_VDEC_GetOutputPortLayoutMode(MI_VDEC_OutbufLayoutMode_e *peBufTileMode);
    
  • Parameter

    Parameter Name Description Input/Output
    peBufTileMode Output buffer mode. Please refer to the definition given in MI_VDEC_OutbufLayoutMode_e. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_NOT_INIT Device not initialized.
    MI_ERR_VDEC_NULL_PTR Null pointer
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    Before calling this function, be sure the device has been initialized; otherwise, an error code of channel not created (MI_ERR_VDEC_NOT_INIT) will be returned.


2.22. MI_VDEC_SetDestCrop

  • Function

    Set the decoded image cropping attribute

  • Syntax

    MI_S32 MI_VDEC_SetDestCrop(MI_VDEC_CHN VdecChn, MI_VDEC_CropCfg_t *pstCropCfg);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstCropCfg Cropping attribute. Please refer to the definition given in MI_VDEC_CropCfg_t. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_NULL_PTR Null pointer
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • Alignment Requirement: X or Width should be aligned with 16. Y or Height should be aligned with 2.

    • Before calling this function, be sure the channel to be used has been created; otherwise, an error code of channel not created (MI_ERR_VDEC_CHN_UNEXIST) will be returned.

    • If calling MI_VDEC_SetDestCrop and MI_VDEC_SetOutputPortAttr together, make sure that the crop size is not greater than the scaling size. Otherwise, an error code of illegal parameter (MI_ERR_VDEC_ILLEGAL_PARAM) will be returned.

  • Example

    See the example of MI_VDEC_CreateChn.


2.23. MI_VDEC_GetDestCrop

  • Function

    Get the decoded image cropping attribute

  • Syntax

    MI_S32 MI_VDEC_GetDestCrop(MI_VDEC_CHN VdecChn,
    MI_VDEC_CropCfg_t *pstCropCfg);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstCropCfg Cropping attribute. Please refer to the definition given in MI_VDEC_CropCfg_t. Output
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_NULL_PTR Null pointer
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    Before calling this function, be sure the channel to be used has been created; otherwise, an error code of channel not created (MI_ERR_VDEC_CHN_UNEXIST) will be returned.


2.24. MI_VDEC_ SetChnErrHandlePolicy

  • Function

    Set the decoded image cropping attribute

  • Syntax

    MI_S32 MI_VDEC_SetChnErrHandlePolicy(MI_VDEC_CHN VdecChn,
    MI_VDEC_ErrHandlePolicy_t *pstErrHandlePolicy);
    
  • Parameter

    Parameter Name Description Input/Output
    VdecChn Video decoding channel number. Range: [0, MI_VDEC_MAX_CHN_NUM). Input
    pstErrHandlePolicy Set the output strategy for the data frame having erroneous MB. Please refer to the definition given in MI_VDEC_ErrHandlePolicy_t. Input
  • Return Value

    Return Value Description
    MI_SUCCESS Successful
    MI_ERR_VDEC_INVALID_CHNID Invalid channel ID.
    MI_ERR_VDEC_CHN_UNEXIST Channel not created or already destroyed
    MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter.
    MI_ERR_VDEC_NULL_PTR Null pointer
  • Requirement

    • Header: mi_vdec.h, mi_common.h

    • Library: libmi.a

  • Note

    • Before calling this function, be sure the channel to be used has been created; otherwise, an error code of channel not created (MI_ERR_VDEC_CHN_UNEXIST) will be returned.

3. DATA TYPE

The video decoder related data types and data structures are defined in the table below:

Data Structure Description
MI_VDEC_CodecType_e Define decoding type
MI_VDEC_DPB_BufMode_e Define DPB buffer mode enumeration
MI_VDEC_JpegFormat_e Define JPEG image data format
MI_VDEC_VideoMode_e Define code stream transmission method enumeration
MI_VDEC_ErrCode_e Define code stream transmission method
MI_VDEC_DecodeMode_e Define code stream decoding method
MI_VDEC_OutputOrder_e Define code stream transmission method
MI_VDEC_VideoFormat_e Define decoded image data format enumeration
MI_VDEC_DisplayMode_e Define display mode enumeration
MI_VDEC_OutbufLayoutMode_e Define output buffer layout mode enumeration
MI_VDEC_InitParam_t Define decoding device initialization parameter structure
MI_VDEC_ChnAttr_t Define video decoding channel attribute
MI_VDEC_JpegAttr_t Define JPEG video decoding channel attribute structure
MI_VDEC_VideoAttr_t Define video decoding channel attribute
MI_VDEC_ChnStat_t Define channel status structure
MI_VDEC_ChnParam_t Define decoding channel parameter structure
MI_VDEC_VideoStream_t Define code stream push structure
MI_VDEC_UserData_t Define user data structure
MI_VDEC_OutputPortAttr_t Define output port attribute structure
MI_VDEC_ErrHandlePolicy_t Control whether or not to output frames which have erroneous MB
MI_VDEC_CropCfg_t Define cropping attribute structure

3.1. MI_VDEC_CodecType_e

  • Description

    Define decoding type.

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_CODEC_TYPE_H264 = 0x0, /* H264 */
    
        E_MI_VDEC_CODEC_TYPE_H265, /* H265 */
    
        E_MI_VDEC_CODEC_TYPE_JPEG, /* JPEG */
    
        E_MI_VDEC_CODEC_TYPE_MAX
    
    } MI_VDEC_CodecType_e;
    

3.2. MI_VDEC_DPB_BufMode_e

  • Description

    Define DPB buffer mode enumeration

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_DPB_MODE_NORMAL=0,
    
        E_MI_VDEC_DBP_MODE_INPLACE_ONE_BUF=1,
    
        E_MI_VDEC_DBP_MODE_INPLACE_TWO_BUF=2,
    
        E_MI_VDEC_DPB_MODE_INVALID=0xFFFFFFFF
    
    } MI_VDEC_DPB_BufMode_e;
    
  • Member

    Member Description
    E_MI_VDEC_DPB_MODE_NORMAL Normal buffer mode
    E_MI_VDEC_DBP_MODE_INPLACE_ONE_BUF Inplace one buffer mode.
    E_MI_VDEC_DBP_MODE_INPLACE_TWO_BUF Inplace two buffer mode.

3.3. MI_VDEC_JpegFormat_e

  • Description

    Jpeg image format.

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_JPEG_FORMAT_YCBCR400 = 0x0, /*YUV400*/
    
        E_MI_VDEC_JPEG_FORMAT_YCBCR420, /*YUV420*/
    
        E_MI_VDEC_JPEG_FORMAT_YCBCR422, /*YUV 422*/
    
        E_MI_VDEC_JPEG_FORMAT_YCBCR444, /*YUV 444*/
    
        E_MI_VDEC_JPEG_FORMAT_MAX
    
    } MI_VDEC_JpegFormat_e;
    
  • Note

    This parameter is currently not used.


3.4. MI_VDEC_VideoMode_e

  • Description

    Define code stream transmission method.

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_VIDEO_MODE_STREAM = 0x0,
    
        E_MI_VDEC_VIDEO_MODE_FRAME,
    
        E_MI_VDEC_VIDEO_MODE_MAX
    
    } MI_VDEC_VideoMode_e;
    
  • Member

    Member Description
    E_MI_VIDEO_MODE_STREAM Send code stream in stream-based method.
    E_MI_VIDEO_MODE_FRAME Send code stream in frame-based method.

3.5. MI_VDEC_ErrCode_e

  • Description

    Define code stream transmission method.

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_ERR_CODE_UNKNOW = 0x0,
    
        E_MI_VDEC_ERR_CODE_ILLEGAL_ACCESS,
    
        E_MI_VDEC_ERR_CODE_FRMRATE_UNSUPPORT,
    
        E_MI_VDEC_ERR_CODE_DEC_TIMEOUT,
    
        E_MI_VDEC_ERR_CODE_OUT_OF_MEMORY,
    
        E_MI_VDEC_ERR_CODE_CODEC_TYPE_UNSUPPORT,
    
        E_MI_VDEC_ERR_CODE_ERR_SPS_UNSUPPORT,
    
        E_MI_VDEC_ERR_CODE_ERR_PPS_UNSUPPORT,
    
        E_MI_VDEC_ERR_CODE_REF_LIST_ERR,
    
        E_MI_VDEC_ERR_CODE_MAX
    
    } MI_VDEC_ErrCode_e;
    
  • Member

    Member Description
    E_MI_VDEC_ERR_CODE_UNKNOW Unknown error.
    E_MI_VDEC_ERR_CODE_ILLEGAL_ACCESS Illegal access, e.g. HW not yet initialized or has an error.
    E_MI_VDEC_ERR_CODE_FRMRATE_UNSUPPORT Unsupported frame rate
    E_MI_VDEC_ERR_CODE_DEC_TIMEOUT Coding timeout
    E_MI_VDEC_ERR_CODE_OUT_OF_MEMORY Out of memory
    E_MI_VDEC_ERR_CODE_CODEC_TYPE_UNSUPPORT Unsupported decoding type
    E_MI_VDEC_ERR_CODE_ERR_SPS_UNSUPPORT Unsupported SPS or SPS error
    E_MI_VDEC_ERR_CODE_ERR_PPS_UNSUPPORT Unsupported PPS or PPS error
    E_MI_VDEC_ERR_CODE_REF_LIST_ERR Reference frame list error

3.6. MI_VDEC_DecodeMode_e

  • Description

    Define code stream decoding method.

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_DECODE_MODE_ALL = 0x0,
    
        E_MI_VDEC_DECODE_MODE_I,
    
        E_MI_VDEC_DECODE_MODE_IP,
    
        E_MI_VDEC_DECODE_MODE_MAX
    
    } MI_VDEC_DecodeMode_e;
    
  • Member

    Member Description
    E_MI_VDEC_DECODE_MODE_ALL Decode IPB data frame
    E_MI_VDEC_DECODE_MODE_I Decode I frame only
    E_MI_VDEC_DECODE_MODE_IP Decode IP frame only (B skipped)

3.7. MI_VDEC_OutputOrder_e

  • Description

    Define code stream transmission method.

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_OUTPUT_ORDER_DISPLAY = 0x0,
    
        E_MI_VDEC_OUTPUT_ORDER_DECODE,
    
        E_MI_VDEC_OUTPUT_ORDER_MAX,
    
    } MI_VDEC_OutputOrder_e;
    
  • Member

    Member Description
    E_MI_VDEC_OUTPUT_ORDER_DISPLAY Output data frame by display order
    E_MI_VDEC_OUTPUT_ORDER_DECODE Output data frame by decoding order

3.8. MI_VDEC_VideoFormat_e

  • Description

    Define decoded image data format enumeration

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_VIDEO_FORMAT_TILE = 0x0,
    
        E_MI_VDEC_VIDEO_FORMAT_REDUCE,
    
        E_MI_VDEC_VIDEO_FORMAT_MAX
    
    } MI_VDEC_VideoFormat_e;
    
  • Member

    Member Description
    E_MI_VDEC_VIDEO_FORMAT_TILE TILE data format.
    E_MI_VDEC_VIDEO_FORMAT_REDUCE Data frame compressed format, to reduce memory used by the data frame.
  • Note

    The current data type does not support upper layer setting. You should return to the supported data types.


3.9. MI_VDEC_DisplayMode_e

  • Description

    Define display mode enumeration.

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_DISPLAY_MODE_PREVIEW = 0x0,
    
        E_MI_VDEC_DISPLAY_MODE_PLAYBACK,
    
        E_MI_VDEC_DISPLAY_MODE_MAX,
    
    } MI_VDEC_DisplayMode_e;
    
  • Member

    Member Description
    E_MI_DISPLAY_MODE_PREVIEW Preview mode. Will not refer to PTS output.
    E_MI_DISPLAY_MODE_PLAYBACK Playback mode. Will refer to PTS output.

3.10. MI_VDEC_OutbufLayoutMode_e

  • Description

    Define output buffer layout mode enumeration.

  • Syntax

    typedef enum
    
    {
    
        E_MI_VDEC_OUTBUF_LAYOUT_AUTO = 0x0,
    
        E_MI_VDEC_OUTBUF_LAYOUT_LINEAR,
    
        E_MI_VDEC_OUTBUF_LAYOUT_TILE,
    
        E_MI_VDEC_OUTBUF_LAYOUT_MAX
    
    } MI_VDEC_OutbufLayoutMode_e;
    
  • Member

    Member Description
    E_MI_VDEC_OUTBUF_LAYOUT_AUTO Automatic mode.
    E_MI_VDEC_OUTBUF_LAYOUT_LINEAR Linear mode.
    E_MI_VDEC_OUTBUF_LAYOUT_TILE Tile mode.

3.11. MI_VDEC_InitParam_t

  • Description

    Define decoding device initialization parameter structure.

  • Syntax

    typedef struct MI_VDEC_InitParam_s
    
    {
    
        MI_BOOL bDisableLowLatency;
    
    } MI_VDEC_InitParam_t;
    
  • Member

    Member Description
    bDisableLowLatency Enable or disable low latency mode, default value is false. Parameter type: MI_BOOL
  • Note

    • If bDisableLowLatency is set to true, it means low latency is turned off. This case is applicable to decoding B frame, and it is used to reorder the output of B frame, and the output image will have delay. In addition, the reorder operation will increase memory usage.

    • By default, the low latency mode is enabled, i.e. bdisablelowlatency is false. If the scene does not involve a delay mode, MI_VDEC_InitDev does not need to be called.


3.12. MI_VDEC_ChnAttr_t

  • Description

    Define decoding channel attribute structure.

  • Syntax

    typedef struct MI_VDEC_ChnAttr_s
    
    {
    
        MI_VDEC_CodecType_e eCodecType;
    
        MI_U32 u32BufSize
    
        MI_U32 u32Priority
    
        MI_U32 u32PicWidth
    
        MI_U32 u32PicHeight
    
        MI_VDEC_VideoMode_e eVideoMode
    
        MI_VDEC_DPB_BufMode_e eDpbBufMode;
    
        union
    
        {
    
            MI_VDEC_JpegAttr_t stVdecJpegAttr;
    
            MI_VDEC_VideoAttr_t stVdecVideoAttr;
    
        };
    
    } MI_VDEC_ChnAttr_t;
    
  • Member

    Member Description
    eCodecType Decoding type enumeration value. Parameter type: MI_VDEC_CodecType_e
    u32BufSize Code stream buffer size.
    u32Priority Channel priority, parameter range is 1 ~ 255. The bigger the value, the higher the priority.
    Note: This function is currently not supported.
    u32PicWidth Max. width of decoded image supported by channel (unit: pixel)
    u32PicHeight Max. height of decoded image supported by channel (unit: pixel)
    eVideoMode Code stream transmission method.
    Note: Currently, only frame-based transmission is supported.
    eDpbBufMode DPB buffer mode.
    Note: eDpbBufMode=1 is used only for bitstream which has only one reference
    frame; eDpbBufMode=2 is used only for bitstream which has only two reference
    frames; eDpbBufMode=0 is used for all different kinds of bitstream.
    stVdecJpegAttr JPEG channel related attribute, currently not available for configuration.
    stVdecVideoAttr Attribute of all supported channel types except JPEG.
  • Note

    • The value of u32RefFrameNum will be invalid when eInplaceMode is set to E_MI_VDEC_DPB_MODE_INPLACE_ONE_BUF or E_MI_VDEC_DPB_MODE_INPLACE_TWO_BUF.

    • When eDpbBufMode is set to E_MI_VDEC_DPB_MODE_NORMAL, u32RefFrameNum must be set to limit the maximum number of reference frames. If the value of u32RefFrameNum is smaller than the number of the frame buffer that the decoder needs, the decoder may not start decoding or abnormal image may be outputted.


3.13. MI_VDEC_JpegAttr_t

  • Description

    Define JPEG decoding channel attribute.

  • Syntax

    typedef struct MI_VDEC_JpegAttr_s
    
    {
    
        MI_VDEC_JpegFormat_e eJpegFormat;
    
    }MI_VDEC_JpegAttr_t;
    
  • Member

    Member Description
    eJpegFormat JPEG image storage format.Range is [0,E_MI_JPEG_FORMAT_MAX).
  • Note

    This parameter is currently not available for configuration.


3.14. MI_VDEC_VideoAttr_t

  • Description

    Define video decoding channel attribute.

  • Syntax

    typedef struct MI_VDEC_VideoAttr_s
    
    {
    
        MI_U32 u32RefFrameNum;
    
        MI_VDEC_ErrHandlePolicy_t stErrHandlePolicy;
    
    }MI_VDEC_VideoAttr_t;
    
  • Member

    Member Description
    u32RefFrameNum Reference frame number.
    Range: [0, 16], unit is frame.
    The number of reference frames decides the number of reference frames required for decoding and will influence the memory usage. We suggest setting an appropriate value according to each case concerned.
    For code stream testing, the recommended setting is 2.
    stErrHandlePolicy Set the output strategy for the data frame having erroneous MB. Please refer to the definition given in [MI_VDEC_ErrHandlePolicy_t.
  • Note

    • The value of u32RefFrameNum will be invalid when eDpbBufMode is set to E_MI_VDEC_DPB_MODE_INPLACE_ONE_BUF or E_MI_VDEC_DPB_MODE_INPLACE_TWO_BUF.

    • When eDpbBufMode is set to E_MI_VDEC_DPB_MODE_NORMAL, u32RefFrameNum must be set to limit the maximum number of reference frames. If the value of u32RefFrameNum is smaller than the number of the frame buffer that the decoder needs, the decoder may not start decoding or abnormal image may be outputted.


3.15. MI_VDEC_ChnStat_t

  • Description

    Define channel status structure.

  • Syntax

    typedef MI_VDEC_ChnStat_s
    
    {
    
        MI_VDEC_CodecType_e eCodecType;
    
        MI_U32 u32LeftStreamBytes;
    
        MI_U32 u32LeftStreamFrames;
    
        MI_U32 u32LeftPics;
    
        MI_BOOL bChnStart;
    
        MI_U32 u32RecvStreamFrames;
    
        MI_U32 u32DecodeStreamFrames;
    
        MI_VDEC_ErrCode_e eErrCode;
    
    } MI_VDEC_ChnStat_t;
    
  • Member

    Member Description
    eCodecType Decoding type
    u32LeftStreamBytes Number of bytes to be decoded in code stream buffer.
    u32LeftStreamFrames Number of frames to be decoded in code stream buffer.
    –1 represents invalid setting.
    This parameter works only for frame-based transmission.
    u32LeftPics Number of pictures remaining in the image buffer.
    bChnStart Indicates whether decoder has been enabled to receive code stream.
    u32RecvStreamFrames Number of code stream frames received in the code stream buffer.
    –1 represents invalid setting.
    This parameter works only for frame-based transmission.
    u32DecodeStreamFrames Number of decoded frames in the code stream buffer.
    eErrCode Decoding error message.

3.16. MI_VDEC_ChnParam_t

  • Description

    Define decoding channel parameter.

  • Syntax

    typedef struct MI_VDEC_ChnParam_s
    
    {
    
        MI_VDEC_DecodeMode_e eDecMode;
    
        MI_VDEC_OutputOrder_e eOutputOrder;
    
        MI_VDEC_VideoFormat_e eVideoFormat;
    
    } MI_VDEC_ChnParam_t;
    
  • Member

    Member Description
    eDecMode Decoding mode, please refer to MI_VDEC_DecodeMode_e definition. Default is E_MI_VDEC_DECODE_MODE_IP. E_MI_VDEC_DECODE_MODE_ALL requires more memory usage.
    eOutputOrder Please refer to the definition given in MI_VDEC_OutputOrder_e. Default is E_MI_VDEC_OUTPUT_ORDER_DECODE, outputting frames by decoding order.
    eVideoFormat Please refer to the definition given in MI_VDEC_VideoFormat_e.

3.17. MI_VDEC_VideoStream_t

  • Description

    Define video coding code stream structure.

  • Syntax

    typedef struct MI_VDEC_VideoStream_s
    
    {
    
        MI_U8* pu8Addr;
    
        MI_U32 u32Len;
    
        MI_U64 u64PTS;
    
        MI_BOOL bEndOfFrame;
    
        MI_BOOL bEndOfStream;
    
    }MI_VDEC_VideoStream_t;
    
  • Member

    Member Description
    pu8Addr Code stream packet address.
    u32Len Code stream packet length, unit is word.
    u64PTS Code stream packet timestamp, unit is millisecond.
    bEndOfFrame End of frame indication (reserved function). Currently only frame-based transmission under frame mode is supported.
    bEndOfStream End of code stream indication. When all the code stream data frames have been transmitted, bEndOfStream must be set to TRUE.
  • Note

    • Frame-based and stream-based data transmissions are both supported. For frame-based case, an entire data frame should be transmitted for each transmission at a time. Stream-based data transmissions is currently not supported.

    • If the code stream frame data contains PTS, the decoded output data will output the same PTS. When PTS=-1, reference is not made to system clock output data frame.


3.18. MI_VDEC_UserData_t

  • Description

    Define user data structure.

  • Syntax

    typedef struct MI_VDEC_UserData_s
    
    {
    
        MI_U8* pu8Addr;
    
        MI_U32 u32Len;
    
        MI_BOOL bValid;
    
    } MI_VDEC_UserData_t;
    
  • Member

    Member Description
    pu8Addr User data virtual address.
    u32Len User data length, in byte unit.
    bValid Current data validity indication. Range: {TRUE, FALSE}.
    TRUE: Valid.
    FALSE: Invalid.

3.19. MI_VDEC_OutputPortAttr_t

  • Description

    Define output port attribute structure.

  • Syntax

    typedef struct MI_VDEC_OutputPortAttr_s
    
    {
    
        MI_U16 u16Width; // Width of target image
    
        MI_U16 u16Height; // Height of target image
    
    }MI_VDEC_OutputPortAttr_t;
    
  • Member

    Member Description
    u16Width Width of output image
    u16Height Height of output image
  • Note

    • Scaling range[⅛, 1].

    • Scaling up is not supported.


3.20. MI_VDEC_ErrHandlePolicy_t

  • Description

    Control whether or not to output frames which have erroneous MB.

  • Syntax

    typedef struct MI_VDEC_ErrHandlePolicy_s
    
    {
    
        MI_BOOL bUseCusPolicy; // FALSE: use default; TRUE: use customized value
    
        MI_U8 u8ErrMBPercentThreshold;
    
    } MI_VDEC_ErrHandlePolicy_t;
    
  • Member

    Member Description
    bUseCusPolicy Decide whether to customize the error frame output strategy.
    u8ErrMBPercentThreshold Set the ratio of the number of error macroblocks to the number of macro blocks in the whole data frame in the case where the data frame is not output. The value range is [0, 100].
  • Note

    • If the value of bUseCusPolicy is FALSE, it means no customization, and the u8ErrMBPercentThreshold will use the default value of 30 built in the system; if the value of bUseCusPolicy is TRUE, the customized u8ErrMBPercentThreshold value is used.

    • The value range of u8ErrMBPercentThreshold is [0, 100]. For example, when the value is 10, it means that when the number of error macroblocks accounts for less than 10% of the total number of macroblocks in the whole frame, the output of the current frame will be displayed, otherwise (greater than or equal to 10%) it will not be displayed. When the value is 0, it means that frames which have error MB will not be displayed. When the value is 100, the current frame will be displayed no matter how many error MBs there are.

    • The u8ErrMBPercentThreshold value calculates the ratio value based on the macroblock.


3.21. MI_VDEC_CropCfg_t

  • Description

    Define cropping attribute structure.

  • Syntax

    typedef struct MI_VDEC_CropCfg_s
    
    {
    
        MI_BOOL bEnable; /* Crop region enable */
    
        MI_SYS_WindowRect_t stRect; /* Crop region */
    
    } MI_VDEC_CropCfg_t;
    
  • Member

    Member Description
    bEnable Cropping indication.
    stRect Cropping window attribute. Please refer to the definition of MI_SYS_WindowRect_t in the document of mi_sys.
  • Note

    • Value ranges:
      u16X: [0, 4096-16], u16Y: [0, 4096-2], u16Width: [16, 4096], u16Height: [2, 4096].

    • Alignment Requirement:
      u16X or u16Width should be aligned with 16. u16Y or u16Height should be aligned with 2.


4. Error code

The video decoding error code is shown in table 4-1:

Table 4-1: VDEC API error codes

Error Code Macro Definition Description
0xA0082001 MI_ERR_VDEC_INVALID_DEVID Invalid Device ID
0xA0082002 MI_ERR_VDEC_INVALID_CHNID Invalid Channel ID
0xA0082003 MI_ERR_VDEC_ILLEGAL_PARAM Illegal parameter or inputted parameter exceeding channel decoding capability
0xA0082004 MI_ERR_VDEC_CHN_EXIST Channel to be created already exists
0xA0082005 MI_ERR_VDEC_CHN_UNEXIST Channel does not exist
0xA0082006 MI_ERR_VDEC_NULL_PTR Null pointer
0xA0082007 MI_ERR_VDEC_NOT_CONFIG Not configured before use
0xA0082008 MI_ERR_VDEC_NOT_SUPPORT This operation or function is not supported
0xA0082009 MI_ERR_VDEC_NOT_PERM Illegal operation, for example, no user image is allowed to be inserted before performing this operation
0xA008200C MI_ERR_VDEC_NOMEM Memory allocation fails (due to for example insufficient memory)
0xA008200D MI_ERR_VDEC_NOBUF Buffer allocation fails(For example, the requested data buffer is too large)
0xA008200E MI_ERR_VDEC_BUF_EMPTY No data in buffer
0xA008200F MI_ERR_VDEC_BUF_FULL Buffer full
0xA0082010 MI_ERR_VDEC_SYS_NOTREADY The system is not initialized or the dependent modules are not loaded
0xA0082011 MI_ERR_VDEC_BADADDR Address error
0xA0082012 MI_ERR_VDEC_BUSY System busy
0xA0082013 MI_ERR_VDEC_CHN_NOT_START Channel not started or already stopped
0xA0082014 MI_ERR_VDEC_CHN_NOT_STOP Channel cannot be closed before code stream reception is stopped
0xA0082015 MI_ERR_VDEC_NOT_INIT Device is not initialized
0xA0082016 MI_ERR_VDEC_INITED Device to be initialized is already initialized
0xA008201F MI_ERR_VDEC_FAILED Unsuccessful