跳到主要内容
版本：2.8.1

视频输入 (VI)

概述​

本文档主要介绍VI的API和数据类型。

视频输入（VI）模块实现的功能：通过 MIPI Rx（含 MIPI 接口、LVDS 接口），BT.1120，BT.656，BT.601，DC 等接口接收视频数据。VI 将接收到的数据存入到指定的内存区域，实现视频数据的采集。

基本概念​

DEV 设备​

视频输入设备支持若干种时序输入，负责对时序进行解析。

PIPE 管道​

视频输入 PIPE 绑定在设备后端，负责设备解析后的数据再处理。（目前暂未实现内容，采用直通方式，同 Dev 相同 id 设置即可）。

CHANNEL 通道​

视频输入最后一级的获取通道，如 Dev 为 ISP 时输出有 3 个 channel。

CAC 色差纠正​

CAC （Chromatic Aberration Correction）模块用于修正图像中的色差问题，色差通常由于透镜和光学元件的制造或设计不完美引起。通过调整颜色补偿系数微调图像中的不同颜色，以改善颜色准确性，从而提高整体图像质量，特别适用于消除边缘区域和高对比度区域的紫边。

功能描述​

功能框图​

VI 在软件层次上划分 3 个部分。

VI 从软件上划分了输入设备（Dev），输入 PIPE（采用 Dev 直通到 chn，暂未实现）、输出通道（channel）三个层级。

各芯片的设备、PIPE、通道个数差异如下所示：

芯片DevPIPEchannel
A210443

说明：

例如 A210 支持 4 个 Dev 表示可以最大支持 4 路 sensor 输入，4 条 PIPE 对应 4 个 sensor，每条 PIPE 有 3 个 channel 输出。

VI 处理流程框图如下所示。

alt text

A210 VI 硬件处理流程框图如下所示。其中 A210 支持 ISP 多路输出。

alt text

注意：

如 VI 使用过程无赋值 aEntityName（参考 VI_ISP_OPT_S 结构体定义），则默认 chn0_out 对应mainpath，chn1_out 对应 selfpath，chn2_out 对应 fbcpath。多路 ISP 使用时建议通过 dev/pipe/channel 使用默认定义。

各路输出分辨率限制如下表：

aEntityNamenamemax outputsupport output fmt
/dev/videox_pipe0zhisp_mainpath3840×2160, 最大支持 8 倍缩放RAW/NV12/NV16/YUYV/UYVY
/dev/videox_pipe1zhisp_selfpath119201080, 最大支持 8 倍缩放NV12/NV16/YUYV/UYVY
/dev/videox_pipe2zhisp_selfpath219201080, 最大支持 8 倍缩放NV12/NV16/YUYV/UYVY

注意：

A210 支持的 4 条 PIPE 是分时复用一个 ISP 硬件，使用 4k@60fps 时仅支持一条 PIPE 运行。4 条 PIPE 运行时最大支持每条 PIPE 输出 1080p@30fps。


示例代码​

TEST_VI_CTX_S *ctx;
ctx = reinterpret_cast<TEST_VI_CTX_S *>(malloc(sizeof(TEST_VI_CTX_S)));
memset(ctx, 0, sizeof(TEST_VI_CTX_S));
ctx->width = 1920;
ctx->height = 1080;
ctx->devId = 0;
ctx->pipeId = ctx->devId;
ctx->channelId = 1;
ctx->loopCountSet = 100;

//0. get dev config status
s32Ret = ZH_MPI_VI_GetDevAttr(ctx->devId, &ctx->stDevAttr);
if (s32Ret == ZH_ERR_VI_NOT_CONFIG) {
    //0-1.config dev
    s32Ret = ZH_MPI_VI_SetDevAttr(ctx->devId, &ctx->stDevAttr);
    if (s32Ret != ZH_SUCCESS) {
        ZH_LOGE("ZH_MPI_VI_SetDevAttr %x", s32Ret);
        goto __FAILED1;
    }
} else {
    ZH_LOGE("ZH_MPI_VI_SetDevAttr already");
}

//1.get dev enable status
s32Ret = ZH_MPI_VI_GetDevIsEnable(ctx->devId);
if (s32Ret != ZH_SUCCESS) {
    //1-2.enable dev
    s32Ret = ZH_MPI_VI_EnableDev(ctx->devId);
    if (s32Ret != ZH_SUCCESS) {
        ZH_LOGE("ZH_MPI_VI_EnableDev %x", s32Ret);
        goto __FAILED1;
    }
    //1-3.bind dev/pipe
    ctx->stBindPipe.u32Num = ctx->pipeId;
    ctx->stBindPipe.PipeId[0] = ctx->pipeId;
    s32Ret = ZH_MPI_VI_SetDevBindPipe(ctx->devId, &ctx->stBindPipe);
    if (s32Ret != ZH_SUCCESS) {
        ZH_LOGE("ZH_MPI_VI_SetDevBindPipe %x", s32Ret);
        goto __FAILED2;
    }
} else {
    ZH_LOGE("ZH_MPI_VI_EnableDev already");
}

//2.config channel
ctx->stChnAttr.stSize.u32Width = ctx->width;
ctx->stChnAttr.stSize.u32Height = ctx->height;
s32Ret = ZH_MPI_VI_SetChnAttr(ctx->pipeId, ctx->channelId, &ctx->stChnAttr);
if (s32Ret != ZH_SUCCESS) {
    ZH_LOGE("ZH_MPI_VI_SetChnAttr %x", s32Ret);
    goto __FAILED2;
}

//3.enable channel
s32Ret = ZH_MPI_VI_EnableChn(ctx->pipeId, ctx->channelId);
if (s32Ret != ZH_SUCCESS) {
    ZH_LOGE("ZH_MPI_VI_EnableChn %x", s32Ret);
    goto __FAILED2;
}

//4.save debug file
if (ctx->stDebugFile.bCfg) {
    s32Ret = ZH_MPI_VI_ChnSaveFile(ctx->pipeId, ctx->channelId, &ctx->stDebugFile);
    ZH_LOGE("ZH_MPI_VI_ChnSaveFile %x", s32Ret);
}

while (loopCount < ctx->loopCountSet) {
    //5.get the frame
    s32Ret = ZH_MPI_VI_GetChnFrame(ctx->pipeId, ctx->channelId, &ctx->stViFrame, waitTime);
    if (s32Ret == ZH_SUCCESS) {
        void *data = ZH_MPI_MB_Handle2VirAddr(ctx->stViFrame.pMbBlk);
        //6.get the channel status
        s32Ret = ZH_MPI_VI_QueryChnStatus(ctx->pipeId, ctx->channelId, &ctx->stChnStatus);
        //7.release the frame
        s32Ret = ZH_MPI_VI_ReleaseChnFrame(ctx->pipeId, ctx->channelId, &ctx->stViFrame);
        if (s32Ret != ZH_SUCCESS) {
            ZH_LOGE("ZH_MPI_VI_ReleaseChnFrame fail %x", s32Ret);
        }
        loopCount++;
    } else {
        ZH_LOGE("ZH_MPI_VI_GetChnFrame timeout %x", s32Ret);
    }
    usleep(10*1000);
}

//8. disable one chn
s32Ret = ZH_MPI_VI_DisableChn(ctx->pipeId, ctx->channelId);
ZH_LOGE("ZH_MPI_VI_DisableChn %x", s32Ret);

//9.disable dev(will disabled all chn)
__FAILED2:
s32Ret = ZH_MPI_VI_DisableDev(ctx->devId);
ZH_LOGE("ZH_MPI_VI_DisableDev %x", s32Ret);

详细测试 DEMO，请参考发布文件: test_mpi_vi.cpp。

API 参考​

该功能模块为用户提供以下 API：

ZH_MPI_VI_SetDevAttr​

描述

设置 VI 设备参数。

语法

ZH_S32 ZH_MPI_VI_SetDevAttr(VI_DEV ViDev, const VI_DEV_ATTR_S *pstDevAttr);

参数

参数名数据类型描述输入/输出
ViDevVI_DEVVI 设备号。取值范围：[0,VI_MAX_DEV_NUM)。输入
pstDevAttrconst VI_DEV_ATTR_S*VI 设备属性。静态属性。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

同一个进程在设置设备属性之前需要先查询 VI 的属性是否已经设置过，同一个进程只能设置一次属性，如果要重新设置需要先禁用后再重新设置。

ZH_MPI_VI_GetDevAttr​

描述

获取 VI 设备属性。

语法

ZH_S32 ZH_MPI_VI_GetDevAttr(VI_DEV ViDev, VI_DEV_ATTR_S *pstDevAttr);

参数

参数名数据类型描述输入/输出
ViDevVI_DEVVI 设备号。取值范围：[0,VI_MAX_DEV_NUM)。输入
pstDevAttrVI_DEV_ATTR_S*VI 设备属性。输出

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

  • 获取的属性为前一次配置的属性。
  • 如果从未配置过属性，则返回属性未配置的错误。

ZH_MPI_VI_EnableDev​

描述

启用 VI 设备。

语法

ZH_S32 ZH_MPI_VI_EnableDev(VI_DEV ViDev);

参数

参数名数据类型描述输入/输出
ViDevVI_DEVVI 设备号。取值范围：[0,VI_MAX_DEV_NUM)。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

  • 要求在启用前配置 VI 设备属性，否则会返回属性未配置的错误。
  • 如果 VI 设备已经启用，重复启用，则返回正在使用中的错误。

ZH_MPI_VI_DisableDev​

描述

禁用 VI 设备。

语法

ZH_S32 ZH_MPI_VI_DisableDev(VI_DEV ViDev);

参数

参数名数据类型描述输入/输出
ViDevVI_DEVVI 设备号。取值范围：[0,VI_MAX_DEV_NUM]输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

  • 如果 VI 设备未启用，则返回未启用的 VI 错误码。
  • 禁用 VI 设备会禁用设备下所有 VI 通道。如果只有关闭一个通道，调用关闭通道函数即可。

ZH_MPI_VI_SetDevBindPipe​

描述

设置 VI 设备与 PIPE 的绑定关系。

语法

ZH_S32 ZH_MPI_VI_SetDevBindPipe(VI_DEV ViDev, const VI_DEV_BIND_PIPE_S *pstDevBindPipe);

参数

参数名数据类型描述输入/输出
ViDevVI_DEVVI 设备号。取值范围：[0,VI_MAX_DEV_NUM)。输入
pstDevBindPipeconst VI_DEV_BIND_PIPE_S*绑定到 Dev 的 PIPE 信息的结构体指针。静态属性。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

  • 必须先使能 VI 设备后才能绑定 PIPE。
  • 不支持动态绑定。

ZH_MPI_VI_GetDevBindPipe​

描述

获取 VI 设备与 PIPE 的绑定关系。

语法

ZH_S32 ZH_MPI_VI_GetDevBindPipe(VI_DEV ViDev, VI_DEV_BIND_PIPE_S *pstDevBindPipe);

参数

参数名数据类型描述输入/输出
ViDevVI_DEVVI 设备号。取值范围：[0,VI_MAX_DEV_NUM)。输入
pstDevBindPipeVI_DEV_BIND_PIPE_S*绑定到 Dev 的 PIPE 信息的结构体指针。输出

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

使用本接口前，需先配置 DEV 属性，使能设备并绑定设备跟 PIPE，否则返回失败。

ZH_MPI_VI_GetDevIsEnable​

描述

获取设备是否使能。

语法

ZH_S32 ZH_MPI_VI_GetDevIsEnable(VI_DEV ViDev);

参数

参数名数据类型描述输入/输出
ViDevVI_DEVVI 设备号。取值范围：[0,VI_MAX_DEV_NUM)。输入

返回值

返回值描述
0已经使能。
非 0未使能。

ZH_MPI_VI_SetChnAttr​

描述

设置 VI 通道属性。

语法

ZH_S32 ZH_MPI_VI_SetChnAttr(VI_PIPE ViPipe, VI_CHN ViChn, const VI_CHN_ATTR_S *pstChnAttr);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstChnAttrconst VI_CHN_ATTR_S*VI 通道属性结构体指针。静态属性。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

通道属性的各项配置限制如下：

配置限制
目标图像大小 stSize必须配置，且大小需要在 VI 支持的范围内且不超过 VI 的缩放倍数限制。
通道 buff 类型 enBufType
  • 当采集数据类型为外部申请的内存时，配置为 VI_ALLOC_BUF_TYPE_INTERNAL。
  • 内部申请内存时配置为 VI_ALLOC_BUF_TYPE_INTERNAL。
采集数据选项 stIspOpt当采集的数据为 ISP 输入或者直通时，需要配置：
  • aEntityName：当数据类型为 ISP 直通型时，需要配置。例如：/dev/video0。
  • stMaxSize：必须配置，ISP 采集数据 bypass 通路的分辨率支持。
PIPEPIPE 必须已绑定到设备，否则会返回失败。

ZH_MPI_VI_GetChnAttr​

描述

获取 VI 通道属性。

语法

ZH_S32 ZH_MPI_VI_GetChnAttr(VI_PIPE ViPipe, VI_CHN ViChn, VI_CHN_ATTR_S *pstChnAttr);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstChnAttrVI_CHN_ATTR_S*VI 通道属性结构体指针。静态属性。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

  • 启用 VI 通道前，必须先启用其所属的 VI 设备，否则返回设备未启动的 VI 错误码。
  • 通道属性需先设置后才可获取。

ZH_MPI_VI_EnableChn​

描述

启用 VI 通道。

语法

ZH_S32 ZH_MPI_VI_EnableChn(VI_PIPE ViPipe, VI_CHN ViChn);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

启用 VI 通道前，必须先启用其所属的 VI 设备，否则返回设备未启动的 VI 错误码。

ZH_MPI_VI_DisableChn​

描述

禁用 VI 通道。

语法

ZH_S32 ZH_MPI_VI_DisableChn(VI_PIPE ViPipe, VI_CHN VIChn);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

PIPE 必须已绑定设备，否则会返回失败。

ZH_MPI_VI_PauseChn​

描述

暂停指定 VI 通道的数据流。

语法

ZH_S32 ZH_MPI_VI_PauseChn(VI_PIPE ViPipe, VI_CHN VIChn);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

PIPE 必须已绑定设备，否则会返回失败。

ZH_MPI_VI_ResumeChn​

描述

恢复指定 VI 通道的数据流 。

语法

ZH_S32 ZH_MPI_VI_ResumeChn(VI_PIPE ViPipe, VI_CHN VIChn);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

PIPE 必须已绑定设备，否则会返回失败。

ZH_MPI_VI_GetChnFrame​

描述

从 VI 通道获取采集的图像。

语法

ZH_S32 ZH_MPI_VI_GetChnFrame(VI_PIPE ViPipe, VI_CHN ViChn, VIDEO_FRAME_INFO_S *pstFrameInfo, ZH_S32 s32MilliSec);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstFrameInfoVIDEO_FRAME_INFO_S*输出图像的帧信息结构指针。输入
s32MilliSecZH_S32获取数据的超时时间。
  • -1 表示阻塞模式。
  • 0 表示非阻塞模式。
  • >0 表示阻塞 s32MilliSec 毫秒，超时则报错返回。
输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

  • PIPE 必须已绑定设备，否则会返回失败。
  • s32MilliSec 的值必须大于等于 -1，等于 -1 时采用阻塞模式发送数据，等于 0 时采用非阻塞模式发送数据，大于 0 时，阻塞 s32MilliSec 毫秒后，则返回超时并报错。
  • 获取的缓存信息来自 VI 内部使用的 MediaBuffer，因此使用完之后，必须要调用 ZH_MPI_VI_ReleaseChnFrame 接口释放其内存。
  • 如果通过 ZH_MPI_SYS_Bind 将 VI 绑定到了其他设备，需要设置 VI_CHN_ATTR_S 的 u32Depth 大于0，否则此接口将获取不到数据。

ZH_MPI_VI_ReleaseChnFrame​

描述

释放一帧从 VI 通道获取的图像。

语法

ZH_S32 ZH_MPI_VI_ReleaseChnFrame(VI_PIPE ViPipe, VI_CHN ViChn, const VIDEO_FRAME_INFO_S *pstFrameInfo);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstFrameInfoconst VIDEO_FRAME_INFO_S*输出图像的帧信息结构指针。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

  • PIPE 必须已绑定设备，否则会返回失败。
  • 此接口必须与 ZH_MPI_VI_GetChnFrame 配对使用。

ZH_MPI_VI_ChnSaveFile​

描述

保存 VI 通道数据。

语法

ZH_S32 ZH_MPI_VI_ChnSaveFile(VI_PIPE ViPipe, VI_CHN ViChn, VI_SAVE_FILE_INFO_S *pstSaveFileInfo);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstSaveFileInfoVI_SAVE_FILE_INFO_S*VI 通道数据保存信息结构指针。类型：。输入

返回值

返回值描述
0成功
非 0失败，请参见 VI 错误码。

注意事项

  • PIPE 必须已绑定设备，否则会返回失败。
  • 如果通过 ZH_MPI_SYS_Bind 将 VI 绑定到了其他设备，则此接口将保存不了数据。

ZH_MPI_VI_QueryChnStatus​

描述

查询 VI 通道的状态。

语法

ZH_S32 ZH_MPI_VI_QueryChnStatus(VI_PIPE ViPipe, VI_CHN ViChn, VI_CHN_STATUS_S *pstChnStatus);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstChnStatusVI_CHN_STATUS_S*VI 通道状态的指针。输出

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

  • PIPE 必须已绑定设备，否则会返回失败。
  • 如果通过 ZH_MPI_SYS_Bind 将 VI 绑定到了其他设备，则此接口获取不到帧率数据、丢帧数等统计数据。

ZH_MPI_VI_GetChnFd​

描述

获取 VI 通道对应的设备文件句柄 。通过此接口返回值可以使用 select/poll 查询对应通道的数据状态。

语法

ZH_S32 ZH_MPI_VI_GetChnFd((VI_PIPE ViPipe, VI_CHN ViChn);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入

返回值

返回值描述
非负数成功，VI 通道的设备文件句柄。
负数失败，请参见 VI 错误码。

注意事项

  • 关闭文件句柄需要调用 ZH_MPI_VI_CloseChnFd。
  • 推荐在启用通道前进行获取 fd。
  • 不推荐在不关数据流的情况频繁开关 fd。

ZH_MPI_VI_CloseChnFd​

描述

关闭 VI 通道对应的设备文件句柄。

语法

ZH_S32 ZH_MPI_VI_CloseChnFd(VI_PIPE ViPipe, VI_CHN ViChn);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

ZH_MPI_VI_SetChnFreeze​

描述

设置 VI 通道视频输出冻结 。VI 模块输出的 YUV 画面保持不变，输出帧率等同于 sensor 输出帧率。

语法

ZH_S32 ZH_MPI_VI_SetChnFreeze(VI_PIPE ViPipe, VI_CHN ViChn, ZH_BOOL bFreeze);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
bFreezeZH_BOOL是否使能视频输出冻结功能。动态属性。
  • ZH_TRUE：使能。
  • ZH_FALSE：不使能。
输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

ZH_MPI_VI_GetChnFreeze​

描述

获取 VI 通道视频输出冻结状态。

语法

ZH_S32 ZH_MPI_VI_GetChnFreeze(VI_PIPE ViPipe, VI_CHN ViChn, ZH_BOOL *pbFreeze);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pbFreezeZH_BOOL*视频输出冻结功能使能标志指针。输出

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

ZH_MPI_VI_RegChnEventCallBack​

描述

注册 VI 通道事件回调接口。

语法

ZH_S32 ZH_MPI_VI_RegChnEventCallBack(VI_PIPE ViPipe, VI_CHN ViChn, const VI_CHN_EVENT_CB_S *pstChnEventCB);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstChnEventCBconst VI_CHN_EVENT_CB_S*VI 通道事件回调函数结构指针。输入

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

PIPE 必须已绑定设备，否则返回失败。

ZH_MPI_VI_SetSwcacConfig​

描述

设置 VI 通道的 CAC 配置信息。

语法

ZH_S32 ZH_MPI_VI_SetSwcacConfig(VI_PIPE ViPipe, VI_CHN ViChn, const SWCAC_CONFIG_S *pstSwcacConfig);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstSwcacConfigconst SWCAC_CONFIG_S*CAC 配置信息结构指针。静态属性。输入

返回值

返回值描述
0成功
非 0失败，请参见 VI 错误码。

注意事项

  • PIPE 必须已绑定设备，否则会返回失败。
  • 此接口需在设置通道属性之后，启用通道之前调用。

ZH_MPI_VI_GetSwcacConfig​

描述

获取 VI 通道的 CAC 配置信息。

语法

ZH_S32 ZH_MPI_VI_GetSwcacConfig(VI_PIPE ViPipe, VI_CHN ViChn, SWCAC_CONFIG_S *pstSwcacConfig);

参数

参数名数据类型描述输入/输出
ViPipeVI_PIPEVI PIPE 号。取值范围：[0,VI_MAX_PIPE_NUM)。输入
ViChnVI_CHNVI 通道号。取值范围：[0,VI_MAX_CHN_NUM)。输入
pstSwcacConfigSWCAC_CONFIG_S*CAC 配置信息结构指针。输出

返回值

返回值描述
0成功。
非 0失败，请参见 VI 错误码。

注意事项

PIPE 必须已绑定设备，否则会返回失败。

数据类型​

VI 模块相关数据类型定义如下：

VI_DEV​

说明

定义 VI 设备句柄。

定义

typedef ZH_S32 VI_DEV;

VI_PIPE​

说明

定义 VI PIPE。

定义

typedef ZH_S32 VI_PIPE;

VI_CHN​

说明

定义 VI 通道。

定义

typedef ZH_S32 VI_CHN;

VI_MAX_DEV_NUM​

说明

定义 VI 设备的最大个数。

定义

#define VI_MAX_DEV_NUM 4

VI_MAX_PIPE_NUM​

说明

定义 VI PIPE 的最大个数。

定义

#define VI_MAX_PIPE_NUM 4

VI_MAX_CHN_NUM​

说明

定义 VI 通道的最大个数。

定义

#define VI_MAX_CHN_NUM 3

VI_DEV_ATTR_S​

说明

定义 VI 设备属性结构体。

定义

typedef struct zhVI_DEV_ATTR_S {
    VI_INTF_MODE_E enIntfMode;
    VI_WORK_MODE_E enWorkMode;
    ZH_U32 au32ComponentMask[2];
    VI_SCAN_MODE_E enScanMode;
    ZH_S32 s32AdChnId[4];
    VI_DATA_SEQ_E enDataSeq;
    VI_VSYNC_E stSynCfg;
    VI_VSYNC_E stVsyncCfg;
    VI_DATA_TYPE_E enInputDataType;
    ZH_BOOL bDataReverse;
    SIZE_S stSize;
} VI_DEV_ATTR_S;

成员

成员名数据类型描述
enIntfModeVI_INTF_MODE_E接口模式。
enWorkModeVI_WORK_MODE_E工作模式。
au32ComponentMaskZH_U32分量掩码。
enScanModeVI_SCAN_MODE_E扫描模式。
s32AdChnIdZH_S32模拟解码通道号
enDataSeqVI_DATA_SEQ_E数据序列。
stSynCfgVI_VSYNC_E同步配置。
stVsyncCfgVI_VSYNC_E垂直同步配置。
enInputDataTypeVI_DATA_TYPE_E输入数据类型。
bDataReverseZH_BOOL数据反转使能。
stSizeSIZE_S图像大小。

VI_DEV_BIND_PIPE_S​

说明

定义 VI 设备绑 定PIPE 的结构体。

定义

typedef struct zhVI_DEV_BIND_PIPE_S {
    ZH_U32 u32Num;
    VI_PIPE PipeId[VI_MAX_PIPE_NUM];
} VI_DEV_BIND_PIPE_S;

成员

成员名数据类型描述
u32NumZH_U32绑定的 PIPE 个数。
PipeIdVI_PIPE绑定的 PIPE ID 数组。

VI_CHN_ATTR_S​

说明

定义 VI 通道属性结构体。

定义

typedef struct zhVI_CHN_ATTR_S {
    SIZE_S stSize;
    PIXEL_FORMAT_E enPixelFormat;
    COMPRESS_MODE_E enCompressMode;
    ZH_U32 u32Depth;
    VI_CHN_BUF_TYPE_E enBufType;
    VI_ISP_OPT_S stIspOpt;
} VI_CHN_ATTR_S;

成员

成员名数据类型描述
stSizeSIZE_S目标图像大小。
enPixelFormatPIXEL_FORMAT_E像素格式。
enCompressModeCOMPRESS_MODE_E压缩模式。
u32DepthZH_U32缓存深度。
enBufTypeVI_CHN_BUF_TYPE_E缓存类型。
stIspOptVI_ISP_OPT_SISP 选项。

VI_ISP_OPT_S​

说明

定义 VI ISP 选项结构体。

定义

typedef struct zhVI_ISP_OPT_S {
    ZH_CHAR aEntityName[32];
    SIZE_S stMaxSize;
} VI_ISP_OPT_S;

成员

成员名数据类型描述
aEntityNameZH_CHARISP 实体名称，如 /dev/video0。
stMaxSizeSIZE_SISP 支持的最大分辨率。

VI_CHN_BUF_TYPE_E​

说明

定义 VI 通道缓存类型枚举。

定义

typedef enum zhVI_CHN_BUF_TYPE_E {
    VI_CHN_BUF_TYPE_DMA = 0,
    VI_CHN_BUF_TYPE_MMAP,
} VI_CHN_BUF_TYPE_E;

成员

成员名描述
VI_CHN_BUF_TYPE_DMADMA 缓存类型。
VI_CHN_BUF_TYPE_MMAPMMAP 缓存类型。

VI_CHN_STATUS_S​

说明

定义 VI 通道状态结构体。

定义

typedef struct zhVI_CHN_STATUS_S {
    ZH_BOOL bEnable;
    ZH_U32 u32FrameRate;
    ZH_U32 u32LostFrame;
    ZH_U32 u32VbFail;
    SIZE_S stSize;
} VI_CHN_STATUS_S;

成员

成员名数据类型描述
bEnableZH_BOOL通道使能状态。
u32FrameRateZH_U32帧率。
u32LostFrameZH_U32丢帧数。
u32VbFailZH_U32申请缓存失败次数。
stSizeSIZE_S图像大小。

VI_SAVE_FILE_INFO_S​

说明

定义 VI 保存文件信息结构体。

定义

typedef struct zhVI_SAVE_FILE_INFO_S {
    ZH_BOOL bCfg;
    ZH_CHAR aFilePath[128];
    ZH_CHAR aFileName[128];
    ZH_U32 u32FileNum;
} VI_SAVE_FILE_INFO_S;

成员

成员名数据类型描述
bCfgZH_BOOL是否配置保存文件。
aFilePathZH_CHAR文件路径。
aFileNameZH_CHAR文件名。
u32FileNumZH_U32保存文件数。

VI_CHN_EVENT_CB_S​

说明

定义 VI 通道事件回调结构体。

定义

typedef struct zhVI_CHN_EVENT_CB_S {
    ZH_VOID *pPrivateData;
    pfnEventCallBack pfnViEventCallBack;
} VI_CHN_EVENT_CB_S;

成员

成员名数据类型描述
pPrivateDataZH_VOID*私有数据指针。
pfnViEventCallBackpfnEventCallBack事件回调函数指针。

CAC_EFFECT_ATTR_S​

说明

定义CAC的效果参数结构体。

定义

typedef struct zhCAC_EFFECT_ATTR_S {
    ZH_BOOL bEnable;
    ZH_S32 s32StrengthR;
    ZH_S32 s32StrengthB;
} CAC_EFFECT_ATTR_S;

成员

成员名数据类型描述
bEnableZH_BOOL是否使能 CAC 效果。
s32StrengthRZH_S32红色通道校正强度，取值范围：[-100,100]。
s32StrengthBZH_S32蓝色通道校正强度，取值范围：[-100,100]。

注意事项

  • 强度值为 0 表示不校正。
  • 正值表示向内校正，负值表示向外校正。

SWCAC_CONFIG_S​

说明

定义 CAC 的配置参数结构体。

定义

typedef struct zhSWCAC_CONFIG_S {
    ZH_BOOL bEnable;
    ZH_U32 u32BufNum;
    CAC_EFFECT_ATTR_S stEffectAttr;
} SWCAC_CONFIG_S;

成员

成员名数据类型描述
bEnableZH_BOOL是否使能 CAC。
u32BufNumZH_U32缓存帧数。
stEffectAttrCAC_EFFECT_ATTR_SCAC 效果属性。

注意事项

CAC 配置需在启用通道前设置。

VI_INTF_MODE_E​

说明

定义 VI 接口模式枚举。

定义

typedef enum zhVI_INTF_MODE_E {
    VI_INTF_MODE_MIPI = 0,
    VI_INTF_MODE_LVDS,
    VI_INTF_MODE_DVP,
    VI_INTF_MODE_BT656,
    VI_INTF_MODE_BT1120,
    VI_INTF_MODE_BUTT
} VI_INTF_MODE_E;

成员

成员名描述
VI_INTF_MODE_MIPIMIPI 接口模式。
VI_INTF_MODE_LVDSLVDS 接口模式。
VI_INTF_MODE_DVPDVP 接口模式。
VI_INTF_MODE_BT656BT656 接口模式。
VI_INTF_MODE_BT1120BT1120 接口模式。
VI_INTF_MODE_BUTT无效值。

VI_WORK_MODE_E​

说明

定义 VI 工作模式枚举。

定义

typedef enum zhVI_WORK_MODE_E {
    VI_WORK_MODE_1Multiplex = 0,
    VI_WORK_MODE_2Multiplex,
    VI_WORK_MODE_4Multiplex,
    VI_WORK_MODE_BUTT
} VI_WORK_MODE_E;

成员

成员名描述
VI_WORK_MODE_1Multiplex1 复用工作模式。
VI_WORK_MODE_2Multiplex2 复用工作模式。
VI_WORK_MODE_4Multiplex4 复用工作模式。
VI_WORK_MODE_BUTT无效值。

VI_SCAN_MODE_E​

说明

定义 VI 扫描模式枚举。

定义

typedef enum zhVI_SCAN_MODE_E {
    VI_SCAN_PROGRESSIVE = 0,
    VI_SCAN_INTERLACED,
    VI_SCAN_BUTT
} VI_SCAN_MODE_E;

成员

成员名描述
VI_SCAN_PROGRESSIVE逐行扫描。
VI_SCAN_INTERLACED隔行扫描。
VI_SCAN_BUTT无效值。

VI_DATA_SEQ_E​

说明

定义 VI 数据序列枚举。

定义

typedef enum zhVI_DATA_SEQ_E {
    VI_DATA_SEQ_YUYV = 0,
    VI_DATA_SEQ_YVYU,
    VI_DATA_SEQ_UYVY,
    VI_DATA_SEQ_VYUY,
    VI_DATA_SEQ_BUTT
} VI_DATA_SEQ_E;

成员

成员名描述
VI_DATA_SEQ_YUYVYUYV 数据序列。
VI_DATA_SEQ_YVYUYVYU 数据序列。
VI_DATA_SEQ_UYVYUYVY 数据序列。
VI_DATA_SEQ_VYUYVYUY 数据序列。
VI_DATA_SEQ_BUTT无效值。

VI_DATA_TYPE_E​

说明

定义 VI 输入数据类型枚举。

定义

typedef enum zhVI_DATA_TYPE_E {
    VI_DATA_TYPE_YUV = 0,
    VI_DATA_TYPE_RGB,
    VI_DATA_TYPE_RAW,
    VI_DATA_TYPE_BUTT
} VI_DATA_TYPE_E;

成员

成员名描述
VI_DATA_TYPE_YUVYUV 数据类型。
VI_DATA_TYPE_RGBRGB 数据类型。
VI_DATA_TYPE_RAWRAW 数据类型。
VI_DATA_TYPE_BUTT无效值。

VI_VSYNC_E​

说明

定义 VI 垂直同步配置枚举。

定义

typedef enum zhVI_VSYNC_E {
    VI_VSYNC_PULSE = 0,
    VI_VSYNC_FIELD,
    VI_VSYNC_BUTT
} VI_VSYNC_E;

成员

成员名描述
VI_VSYNC_PULSE脉冲同步模式。
VI_VSYNC_FIELD场同步模式。
VI_VSYNC_BUTT无效值。

SIZE_S​

说明

定义图像尺寸结构体。

定义

typedef struct zhSIZE_S {
    ZH_U32 u32Width;
    ZH_U32 u32Height;
} SIZE_S;

成员

成员名描述
u32Width图像宽度。
u32Height图像高度。

PIXEL_FORMAT_E​

说明

定义像素格式枚举。

定义

typedef enum zhPIXEL_FORMAT_E {
    PIXEL_FORMAT_YUV_SEMIPLANAR_420 = 0,
    PIXEL_FORMAT_YUV_SEMIPLANAR_422,
    PIXEL_FORMAT_YUYV_PACKED_422,
    PIXEL_FORMAT_UYVY_PACKED_422,
    PIXEL_FORMAT_RGB_888,
    PIXEL_FORMAT_BGR_888,
    PIXEL_FORMAT_ARGB_8888,
    PIXEL_FORMAT_ABGR_8888,
    PIXEL_FORMAT_FBC0,
    PIXEL_FORMAT_FBC2,
    PIXEL_FORMAT_BUTT
} PIXEL_FORMAT_E;

成员

成员名描述
PIXEL_FORMAT_YUV_SEMIPLANAR_420NV12 格式。
PIXEL_FORMAT_YUV_SEMIPLANAR_422NV16 格式。
PIXEL_FORMAT_YUYV_PACKED_422YUYV422 格式。
PIXEL_FORMAT_UYVY_PACKED_422UYVY422 格式。
PIXEL_FORMAT_RGB_888RGB888 格式。
PIXEL_FORMAT_BGR_888BGR888 格式。
PIXEL_FORMAT_ARGB_8888ARGB8888 格式。
PIXEL_FORMAT_ABGR_8888ABGR8888 格式。
PIXEL_FORMAT_FBC0FBC 压缩格式 0。
PIXEL_FORMAT_FBC2FBC 压缩格式 2。
PIXEL_FORMAT_BUTT无效值。

COMPRESS_MODE_E​

说明

定义压缩模式枚举。

定义

typedef enum zhCOMPRESS_MODE_E {
    COMPRESS_MODE_NONE = 0,
    COMPRESS_AFBC_16x16,
    COMPRESS_MODE_BUTT
} COMPRESS_MODE_E;

成员

成员名描述
COMPRESS_MODE_NONE不压缩。
COMPRESS_AFBC_16x16AFBC 16x16 压缩模式。
COMPRESS_MODE_BUTT无效值。

VIDEO_FRAME_INFO_S​

说明

定义视频帧信息结构体。

定义

typedef struct zhVIDEO_FRAME_INFO_S {
    VIDEO_FRAME_S stVFrame;
    ZH_U32 u32PoolId;
    MOD_ID_E enModId;
    MB_BLK pMbBlk;
} VIDEO_FRAME_INFO_S;

成员

成员名数据类型描述
stVFrameVIDEO_FRAME_S视频帧结构。
u32PoolIdZH_U32内存池 ID。
enModIdMOD_ID_E模块 ID。
pMbBlkMB_BLK内存块句柄。

VIDEO_FRAME_S​

说明

定义视频帧结构体。

定义

typedef struct zhVIDEO_FRAME_S {
    ZH_U32 u32Width;
    ZH_U32 u32Height;
    PIXEL_FORMAT_E enPixelFormat;
    VIDEO_FIELD_E enField;
    ZH_U32 u32Stride[3];
    ZH_U64 u64PhyAddr[3];
    ZH_VOID *pVirAddr[3];
    ZH_U64 u64PTS;
    ZH_U32 u32TimeRef;
    ZH_U32 u32PrivateData;
    COMPRESS_MODE_E enCompressMode;
} VIDEO_FRAME_S;

成员

成员名数据类型描述
u32WidthZH_U32图像宽度。
u32HeightZH_U32图像高度。
enPixelFormatPIXEL_FORMAT_E像素格式。
enFieldVIDEO_FIELD_E视频场模式。
u32StrideZH_U32跨距。
u64PhyAddrZH_U64物理地址。
pVirAddrZH_VOID*虚拟地址。
u64PTSZH_U64时间戳。
u32TimeRefZH_U32时间参考。
u32PrivateDataZH_U32私有数据。
enCompressModeCOMPRESS_MODE_E压缩模式。

VIDEO_FIELD_E​

说明

定义视频场模式枚举。

定义

typedef enum zhVIDEO_FIELD_E {
    VIDEO_FIELD_TOP = 0,
    VIDEO_FIELD_BOTTOM,
    VIDEO_FIELD_INTERLACED,
    VIDEO_FIELD_FRAME,
    VIDEO_FIELD_BUTT
} VIDEO_FIELD_E;

成员

成员名描述
VIDEO_FIELD_TOP顶场。
VIDEO_FIELD_BOTTOM底场。
VIDEO_FIELD_INTERLACED隔行。
VIDEO_FIELD_FRAME帧。
VIDEO_FIELD_BUTT无效值。

VIDEO_TYPE_E​

说明

定义视频编码类型枚举。

定义

typedef enum zhVIDEO_TYPE_E {
    VIDEO_TYPE_H264 = 0,
    VIDEO_TYPE_H265,
    VIDEO_TYPE_MJPEG,
    VIDEO_TYPE_JPEG,
    VIDEO_TYPE_BUTT
} VIDEO_TYPE_E;

成员

成员名描述
VIDEO_TYPE_H264H.264 编码。
VIDEO_TYPE_H265H.265 编码。
VIDEO_TYPE_MJPEGMJPEG 编码。
VIDEO_TYPE_JPEGJPEG 编码。
VIDEO_TYPE_BUTT无效值。

MB_BLK​

说明

定义媒体缓存块句柄。

定义

typedef ZH_VOID *MB_BLK;

注意事项

媒体缓存块句柄用于管理视频帧的内存，通过 ZH_MPI_MB_* 系列接口进行操作。

VI 错误码​

视频输入 API VI 错误码如下所示。

错误代码宏定义描述
0xA0088001ZH_ERR_VI_INVALID_DEVIDVI 设备号无效。
0xA0088002ZH_ERR_VI_INVALID_CHNIDVI 通道号无效。
0xA0088003ZH_ERR_VI_INVALID_PARAVI 参数设置无效。
0xA0088004ZH_ERR_VI_EXISTVI 通道已存在。
0xA0088005ZH_ERR_VI_UNEXIST不存在通道对象。
0xA0088006ZH_ERR_VI_INVALID_NULL_PTRVI 空指针错误。
0xA0088007ZH_ERR_VI_NOT_CONFIGVI 参数未配置。
0xA0088008ZH_ERR_VI_NOT_SUPPORT操作不允许。
0xA0088009ZH_ERR_VI_NOT_PERM无权限操作。
0xA008800AZH_ERR_VI_INVALID_PIPEIDVI PIPE 号无效。
0xA008800CZH_ERR_VI_NOMEM无内存。
0xA008800EZH_ERR_VI_BUF_EMPTYVI 输入缓冲为空。
0xA008800FZH_ERR_VI_BUF_FULLVI 输入缓存为满。
0xA0088010ZH_ERR_VI_SYS_NOTREADY系统未准备好。
0xA0088012ZH_ERR_VI_BUSYVI 设备忙。