8.3. API Reference

This VDEC function module provides the following APIs for users:

8.3.1. CVI_VDEC_CreateChn

【Description】

Create a video decoding channel.

【Syntax】

CVI_S32 CVI_VDEC_CreateChn(VDEC_CHN VdChn, const VDEC_CHN_ATTR_S *pstAttr);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

pstAttr

Decoding channel property pointer.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • CV181x VDEC module only supports PT_JPEG/PT_MJPEG/PT_H264,CV180x only supports PT_JPEG/PT_MJPEG.

  • When the system is out of memory, CVII_ERR_VDEC_NOMEM error code will be returned.

  • To use JPEG/MJPEG, a VB pool dedicated to VDEC module must be created before creating the decoding channel.

    The size of the VB block required for decoding different protocols varies, which can be referred to the vdecInitVBPool function in the sample_vdec_lib.c file.

【Example】

CVI_S32 SAMPLE_COMM_VDEC_Start(vdecChnCtx *pvdchnCtx)
{
  //Setting VDEC parameters
  VDEC_CHN_ATTR_S stChnAttr, *pstChnAttr = &stChnAttr;
  VDEC_CHN VdecChn = pvdchnCtx->VdecChn;
  SAMPLE_VDEC_ATTR *psvdattr = &pvdchnCtx->stSampleVdecAttr;
  VDEC_CHN_PARAM_S stChnParam;

  pstChnAttr->enType = psvdattr->enType;
  pstChnAttr->enMode = psvdattr->enMode;
  pstChnAttr->u32PicWidth = psvdattr->u32Width;
  pstChnAttr->u32PicHeight = psvdattr->u32Height;
  pstChnAttr->u32StreamBufSize = psvdattr->u32Width * psvdattr->u32Height;
  pstChnAttr->u32FrameBufCnt = psvdattr->u32FrameBufCnt;

  //JPEG, MJPEG need to set VB buffer
  if (psvdattr->enType == PT_JPEG || psvdattr->enType == PT_MJPEG) {
    pstChnAttr->enMode = VIDEO_MODE_FRAME;
    pstChnAttr->u32FrameBufSize = VDEC_GetPicBufferSize(
        pstChnAttr->enType, psvdattr->u32Width, psvdattr->u32Height,
        psvdattr->stSapmleVdecPicture.enPixelFormat, DATA_BITWIDTH_8, 0);
  }
  //create VDEC channel
  CHECK_CHN_RET(CVI_VDEC_CreateChn(VdecChn, pstChnAttr), VdecChn,
                                          "CVI_VDEC_CreateChn");
  //confirm the current default parameter
  CHECK_CHN_RET(CVI_VDEC_GetChnParam(VdecChn, &stChnParam), VdecChn,
                                      "CVI_VDEC_GetChnParam");

  if (psvdattr->enType == PT_H264 || psvdattr->enType == PT_H265) {
  } else {
    stChnParam.stVdecPictureParam.enPixelFormat =
      psvdattr->stSapmleVdecPicture.enPixelFormat;
    stChnParam.stVdecPictureParam.u32Alpha =
      psvdattr->stSapmleVdecPicture.u32Alpha;
  }
  //Set display frame.. parameters
  stChnParam.u32DisplayFrameNum = psvdattr->u32DisplayFrameNum;
  //Set VDEC parameter
  CHECK_CHN_RET(CVI_VDEC_SetChnParam(VdecChn, &stChnParam), VdecChn,
                                    "CVI_MPI_VDEC_GetChnParam");
  //Enable VDEC frame transmission
  CHECK_CHN_RET(CVI_VDEC_StartRecvStream(VdecChn), VdecChn,
                              "CVI_MPI_VDEC_StartRecvStream");
  return CVI_SUCCESS;
}

【Related Topic】

8.3.2. CVI_VDEC_DestroyChn

【Description】

Destroy the video decoding channel.

【Syntax】

CVI_S32 CVI_VDEC_DestroyChn(VDEC_CHN VdChn);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Ensure that the channel is created before destruction.

    Otherwise, an error message indicating that the channel is not created is returned.

  • You must stop receiving the code stream before destroying it (or you have not started receiving the code stream), otherwise an error will be returned.

【Example】

  • None

【Related Topic】

8.3.3. CVI_VDEC_ResetChn

【Description】

Reset the video decoding channel.

【Syntax】

CVI_S32 CVI_VDEC_ResetChn(VDEC_CHN VdChn);

【Parameter】

Parameter

Description

Input/Output

VdChn

Channel ID.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Resetting a channel that does not exist will return CVI_FAILURE.

  • Failure is returned if a channel resets without stopping receiving a stream.

【Example】

  • None

8.3.4. CVI_VDEC_GetChnAttr

【Description】

Get video decoding channel attributes.

【Syntax】

CVI_S32 CVI_VDEC_GetChnAttr(VDEC_CHN VdChn, VDEC_CHN_ATTR_S *pstAttr);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

pstAttr

Decode channel property pointer.

Output

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • VDEC channel must have been created.

  • This function is usually used before a CVI_VDEC_SetChnAttr, or when fetching a decoder frame Call before to confirm the channel is normal

【Example】

Refer to SAMPLE_COMM_VDEC_GetPic function in sample_common_vdec.c.

CVI_VOID *SAMPLE_COMM_VDEC_GetPic(CVI_VOID *pArgs)
{
  VDEC_THREAD_PARAM_S *pstVdecThreadParam = (VDEC_THREAD_PARAM_S *)pArgs;
  FILE *fp = CVI_NULL;
  CVI_S32 s32Ret, s32Cnt = 0;
  VDEC_CHN_ATTR_S stAttr;
  VIDEO_FRAME_INFO_S stVFrame;
  CVI_CHAR cSaveFile[256];
  prctl(PR_SET_NAME, "VdecGetPic", 0, 0, 0);
  s32Ret = CVI_VDEC_GetChnAttr(pstVdecThreadParam->s32ChnId, &stAttr);
  if (s32Ret != CVI_SUCCESS) {
    CVI_VDEC_ERR("chn %d get chn attr fail for %#x!\n",
        pstVdecThreadParam->s32ChnId,
        s32Ret);
    return (CVI_VOID *)(CVI_FAILURE);
  }

  if (stAttr.enType != PT_JPEG && stAttr.enType != PT_H264 && stAttr.enType != PT_H265) {
    CVI_VDEC_ERR("chn %d enType %d do not support save file!\n",
        pstVdecThreadParam->s32ChnId,
        stAttr.enType);
    return (CVI_VOID *)(CVI_FAILURE);
  }

  while (1) {
    if (pstVdecThreadParam->eThreadCtrl == THREAD_CTRL_STOP)
      break;

    s32Ret = CVI_VDEC_GetFrame(
        pstVdecThreadParam->s32ChnId,
        &stVFrame,
        pstVdecThreadParam->s32MilliSec);
    CVI_VDEC_TRACE("leave CVI_VDEC_GetFrame %d\n", s32Ret);
    ...
    ...
    }
}

【Related Topic】

8.3.5. CVI_VDEC_SetChnAttr

【Description】

Set video decoding channel attributes.

【Syntax】

CVI_S32 CVI_VDEC_SetChnAttr(VDEC_CHN VdChn, const VDEC_CHN_ATTR_S *pstAttr);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

pstAttr

Decoding channel property pointer.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • VDEC channel must have be created.

  • You must stop receiving streams before changing channel properties.

    Otherwise, an error is returned.

【Example】

  • None.

【Related Topic】

8.3.6. CVI_VDEC_StartRecvStream

【Description】

The decoder starts to receive the bitstream sent by the user.

【Syntax】

CVI_S32 CVI_VDEC_StartRecvStream(VDEC_CHN VdChn);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Before starting the receive stream, you must ensure that the channel has been created, otherwise an error will be returned.

【Example】

Refer to the example of CVI_VDEC_CreateChn.

【Related Topic】

8.3.7. CVI_VDEC_StopRecvStream

【Description】

The decoder stops receiving the bitstream sent by the user.

【Syntax】

CVI_S32 CVI_VDEC_StopRecvStream(VDEC_CHN VdChn);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • This interface must be called before CVI_VDEC_DestroyChn.

【Example】

  • Refer to SAMPLE_COMM_VDEC_Stop in sample_common_vdec.c:

CVI_S32 SAMPLE_COMM_VDEC_Stop(CVI_S32 s32ChnNum)
{
CVI_S32 i;
for (i = 0; i < s32ChnNum; i++) {
CHECK_CHN_RET(CVI_VDEC_DestroyChn(i), i, "CVI_MPI_VDEC_DestroyChn");
CHECK_CHN_RET(CVI_VDEC_StopRecvStream(i), i, "CVI_MPI_VDEC_StopRecvStream");
}

return CVI_SUCCESS;
}

【Related Topic】

  • None

8.3.8. CVI_VDEC_QueryStatus

【Description】

Query the status of decoding channel.

【Syntax】

CVI_S32 CVI_VDEC_QueryStatus(VDEC_CHN VdChn, VDEC_CHN_STATUS_S *pstStatus);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

pstStatus

Video decoding channel state structure pointer

Output

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Before starting to receive the bitstream, the channel must be created.

    Otherwise, an error will be returned.

【Example】

  • Refer to the usage of SAMPLE_COMM_VDEC_CmdCtrl in sample_common_vdec.c.

  • CVI_VDEC_QueryStatus allows users to query the following information:

enType:Encoding format.

bStartRecvStream:Whether frame to decoder has started to be transmitted.

u32DecodeStreamFrames:The number of frames decoded.

u32LeftPics:The number of remaining images.

stVdecDecErr:Decoder error status(s32FormatErr:format error,

s32PicSizeErrSet:Image size error, s32StreamUnsprt:Stream format not supported …)。

【Related Topic】

  • None

8.3.9. CVI_VDEC_SetChnParam

【Description】

Set decoding channel parameters.

【Syntax】

CVI_S32 CVI_VDEC_SetChnParam(VDEC_CHN VdChn, const VDEC_CHN_PARAM_S *pstParam);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

pstParam

Channel parameter

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Ensure that the channel is created before starting the receiving stream.

    Otherwise, an error is returned.

【Example】

Refer to SAMPLE_COMM_VDEC_Start function in sample_common_vdec.c:

CVI_S32 SAMPLE_COMM_VDEC_Start(vdecChnCtx *pvdchnCtx)
{
  VDEC_CHN_ATTR_S stChnAttr, *pstChnAttr = &stChnAttr;
  VDEC_CHN VdecChn = pvdchnCtx->VdecChn;
  SAMPLE_VDEC_ATTR *psvdattr = &pvdchnCtx->stSampleVdecAttr;
  VDEC_CHN_PARAM_S stChnParam;

  pstChnAttr->enType = psvdattr->enType;
  pstChnAttr->enMode = psvdattr->enMode;
  pstChnAttr->u32PicWidth = psvdattr->u32Width;
  pstChnAttr->u32PicHeight = psvdattr->u32Height;
  pstChnAttr->u32StreamBufSize = psvdattr->u32Width * psvdattr->u32Height;
  pstChnAttr->u32FrameBufCnt = psvdattr->u32FrameBufCnt;

  if (psvdattr->enType == PT_JPEG || psvdattr->enType == PT_MJPEG) {
    pstChnAttr->enMode = VIDEO_MODE_FRAME;
    pstChnAttr->u32FrameBufSize = VDEC_GetPicBufferSize(
        pstChnAttr->enType, psvdattr->u32Width, psvdattr->u32Height,
        psvdattr->stSapmleVdecPicture.enPixelFormat, DATA_BITWIDTH_8, 0);
  }

  CHECK_CHN_RET(CVI_VDEC_CreateChn(VdecChn, pstChnAttr), VdecChn, "CVI_VDEC_CreateChn");

  CHECK_CHN_RET(CVI_VDEC_GetChnParam(VdecChn, &stChnParam), VdecChn, "CVI_VDEC_GetChnParam");

  if (psvdattr->enType == PT_H264 || psvdattr->enType == PT_H265) {
  } else {
    stChnParam.stVdecPictureParam.enPixelFormat =
      psvdattr->stSapmleVdecPicture.enPixelFormat;
    stChnParam.stVdecPictureParam.u32Alpha =
      psvdattr->stSapmleVdecPicture.u32Alpha;
  }
  stChnParam.u32DisplayFrameNum = psvdattr->u32DisplayFrameNum;

  CHECK_CHN_RET(CVI_VDEC_SetChnParam(VdecChn, &stChnParam), VdecChn, "CVI_MPI_VDEC_GetChnParam");

  CHECK_CHN_RET(CVI_VDEC_StartRecvStream(VdecChn), VdecChn, "CVI_MPI_VDEC_StartRecvStream");
  return CVI_SUCCESS;
}

【Related Topic】

  • None.

8.3.10. CVI_VDEC_GetChnParam

【Description】

Get decoding channel parameters.

【Syntax】

CVI_S32 CVI_VDEC_GetChnParam(VDEC_CHN VdChn, VDEC_CHN_PARAM_S *pstParam);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

pstParam

Channel parameter

Output

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Ensure that the channel is created before starting the receiving stream.

    Otherwise, an error is returned.

【Example】

Refer to SAMPLE_COMM_VDEC_Start function in sample_common_vdec.c.

【Related Topic】

8.3.11. CVI_VDEC_SendStream

【Description】

Send the bitstream data to the video decoding channel.

【Syntax】

CVI_S32 CVI_VDEC_SendStream(VDEC_CHN VdChn, const VDEC_STREAM_S *pstStream, CVI_S32 s32MilliSec);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

pstStream

Decoding bitstream data pointer.

Input

s32MilliSec

Sending bitstream flag.

Value range: -1: Blocking.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Before sending data, it is necessary to ensure CVI_VDEC_CreateChn, CVI_VDEC_StartRecvStream has been called.

  • This interface in mjpeg, jpeg decoding state, send length 0(pstStream->u32Len) will return CVI_SUCCESS;

  • When decoding fails, the error code ERR_CVI_VDEC_SEND_STREAM will be returned.

【Example】

Refer to SAMPLE_COMM_VDEC_SendStream function in sample_common_vdec.c.

【Related Topic】

  • None.

8.3.12. CVI_VDEC_GetFrame

【Description】

Get the decoded image of the video decoding channel.

【Syntax】

CVI_S32 CVI_VDEC_GetFrame(VDEC_CHN VdChn,

VIDEO_FRAME_INFO_S *pstFrameInfo, CVI_S32 s32MilliSec);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

s32MilliSec

Sending bitstream flag.

Value range: -1: Blocking.

Input

pstFrameInfo

Pointer to the information of the decoded image.

Output

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Ensure that the channel is created before starting the receiving stream.

    Otherwise, an error is returned.

【Example】

Refer to SAMPLE_COMM_VDEC_GetPic function in sample_common_vdec.c.

【Related Topic】

None.

8.3.13. CVI_VDEC_ReleaseFrame

【Description】

Release the decoded image of the video decoding channel.

【Syntax】

CVI_S32 CVI_VDEC_ReleaseFrame(VDEC_CHN VdChn, const VIDEO_FRAME_INFO_S *pstFrameInfo);

【Parameter】

Parameter

Description

Input/Output

VdChn

Video decoding channel number.

Input

pstFrameInfo

Pointer to the information of the decoded image.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • This interface needs to be paired with CVI_VDEC_GetFrame, and the acquired data should be released immediately after use.

    If it is not released in time, the decoding process will be blocked and has to wait for resources.

  • The released data must be the data obtained by CVI_VDEC_GetFrame from the decoding channel, and no modification to the data information structure is allowed.

  • The image of the video decoding channel must be released before the channel is destroyed.

【Example】

None.

【Related Topic】

None.

8.3.14. CVI_VDEC_SetModParam

【Description】

Set decoding-related module parameters

【Syntax】

CVI_S32 CVI_VDEC_SetModParam(const VDEC_PARAM_MOD_S *pstModParam);

【Parameter】

Parameter

Description

Input/Output

pstModParam

Decoding module parameter pointer.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • This interface can be called before and after channel creation.

  • This interface is mainly used to set the corresponding decoding VB pool acquisition method.

    Users can set the VB mode through VB_SOURCE_E type variable in VDEC_PARAM_MOD_S structure.

【Example】

  • None.

8.3.15. CVI_VDEC_GetModParam

【Description】

Get decoding-related module parameters

【Syntax】

CVI_S32 CVI_VDEC_GetModParam(VDEC_PARAM_MOD_S *pstModParam);

【Parameter】

Parameter

Description

Input/Output

pstModParam

Decoding module parameter pointer.

Output

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Usually used before CVI_VDEC_SetModParam.

【Example】

  • None.

8.3.16. CVI_VDEC_AttachVbPool

【Description】

Bind the decoding channel to a video buffer VB pool.

【Syntax】

CVI_S32 CVI_VDEC_AttachVbPool(VDEC_CHN VdChn, const VDEC_CHN_POOL_S *pstPool);

【Parameter】

Parameter

Description

Input/Output

VdChn

Channel number.

Input

pstPool

The Id number of the video buffer VB pool.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Ensure that the channel has been created, otherwise CVI_FAILURE error code will be returned.

  • Users must call the interface CVI_VB_CreatePool to create a video buffer VB pool, and then bind the current encoding channel to the fixed PoolId VB pool by calling the interface CVI_VDEC_AttachVbPool.

    Multiple encoding channels can be bound to the same VB pool, but the same encoding channel cannot be bound to multiple VB pools.

  • pstPool must be a valid PoolId of the created VB pool, including the VB pool for storing Picture and the VB pool for storing Picture information.

  • When calling this interface, the user must make sure that it is set in VB_SOURCE_USER mode through CVI_VDEC_SetModParam.

【Example】

  • None.

8.3.17. CVI_VDEC_DetachVbPool

【Description】

Unbind the decoding channel from a video cache VB pool.

【Syntax】

CVI_S32 CVI_VDEC_DetachVbPool(VDEC_CHN VdChn);

【Parameter】

Parameter

Description

Input/Output

VdChn

Channel number.

Input

【Return Value】

Return Value

Description

0

Success.

Non 0

Failure. For details, please refer to Error Codes.

【Requirement】

  • Header files: cvi_vdec.h, cvi_comm_video.h, cvi_comm_vdec.h

  • Library files: libvdec.so/libvdec.a

【Note】

  • Ensure that the channel has been created, otherwise CVI_FAILURE error code will be returned.

【Example】

  • None.