MI VDEC API

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

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:

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:

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