版本：2.9.0

视频处理子系统 (VPSS)

概述

VPSS（Video Process Sub-System）是视频处理子系统，支持的具体图像处理功能包括CROP、Scale、像素格式转换、固定角度旋转、Cover/Coverex、 Mirror/Flip、压缩解压等。

功能描述

基本概念

功能	描述
GROUP	VPSS 对用户提供组（GROUP）的概念。最大个数请参见 VPSS_MAX_GRP_NUM 定义，各 GROUP 分时复用硬件设备，硬件依次处理各个组提交的任务。
CHANNEL	VPSS 组的通道。提供多个通道，每个通道具有缩放、裁剪等功能。把图像裁剪、缩放成用户设置的目标分辨率输出。
CROP	裁剪，分为 2 种：组裁剪、通道裁剪。组裁剪，VPSS 对输入图像进行裁剪。通道裁剪，VPSS 利用硬件设备对各个通道的输出图像进行裁剪。
像素格式转换	支持输入输出图像的数据格式转换，例如 NV12->RGB888P 等。
Scale	缩放，对图像进行缩小或放大处理。
Mirror/Flip	Mirror 即水平镜像，Flip 即垂直翻转。可使用 Mirror + Flip 实现 180° 旋转。
FRC（帧率控制）	帧率控制分为两种：组帧率控制和通道帧率控制。组帧率控制：用于控制各 Group 对输入图像的接收。通道帧率控制：用于控制各个通道图像的处理。
Cover	视频遮挡区域，调用 VGS 对 VPSS 通道的输出图像填充纯色块。
Overlay	视频叠加区域，调用 VGS 对 VPSS 通道的输出图像叠加位图。
Mosaic	马赛克，调用 VGS 对 VPSS 通道的输出图像填充马赛克块。
RGN 通道配置	VPSS Group 和通道均支持 Overlay/Cover/Mosaic/Line 等功能。使用 RGN AttachChn 时 MPP_CHN_S->s32ChnId 参数如果设置为 [0, VPSS_MAX_CHN_NUM)，则表示贴图至指定通道上。如果设置为 VPSS_MAX_CHN_NUM，则表示贴图至 Group 上。
固定角度旋转	支持 0°、90°、180°、270° 固定角度旋转。
通道工作模式	VPSS 通道工作模式主要分为两种，通过改变 VPSS_CHN_MODE_E 切换模式： USER 模式 (VPSS_CHN_MODE_USER)：用户需手动获取通道处理输出图像时会带来性能开销。 PAST 模式 (VPSS_CHN_MODE_PASSTHROUGH)：绑定 VO 时使用，将处理工作转移至 VO 中一并处理，不带来额外开销。预览、回放时建议设置为此模式。

像素格式排布

PIXEL_FORMAT_E 枚举按⼤端模式定义，即枚举定义代表的数据存储排布是按⼤端模式排布，以RGB888/ARGB8888格式的图像存储为例：

RGB888格式的图像存储⽰意图（⼤端模式）如下所示。

RGB888格式的图像存储⽰意图（⼤端模式）

ARGB8888格式的图像存储⽰意图（⼤端模式）如下所示。

ARGB8888格式的图像存储⽰意图（⼤端模式）

注意

PIXEL_FORMAT_E 枚举按⼤端模式定义，但 ARGB1555、RGB565 两种格式处理特殊，现做统⼀约束，要求输⼊图像为 ARGB1555/RGB565 格式时，图像数据在内存中排列统⼀按⼩端存放，对应的 PIXEL_FORMAT_E 枚举值如下：

枚举存储说明
ZH_FMT_RGB565 图像数据在内存中排布为 BGR565 小端，R 在低位。
ZH_FMT_BGR565 图像数据在内存中排布为 RGB565 小端，R 在高位。
ZH_FMT_ARGB1555 图像数据在内存中排布为 BGRA551 小端，A 在低位。
ZH_FMT_BGRA5551 图像数据在内存中排布为 ARGB1555 小端，A 在高位。

其他 RGB 格式建议按⼤端排布，若待处理图像数据是按⼩端排布，则对应的 PIXEL_FORMAT_E 枚举值也需按照反向配置。如待处理图像为 ARGB8888 ⼩端存储（ A 在⾼位），枚举值要配置为 ZH_FMT_BGRA8888。

枚举	存储说明
ZH_FMT_RGB565	图像数据在内存中排布为 BGR565 小端，R 在低位。
ZH_FMT_BGR565	图像数据在内存中排布为 RGB565 小端，R 在高位。
ZH_FMT_ARGB1555	图像数据在内存中排布为 BGRA551 小端，A 在低位。
ZH_FMT_BGRA5551	图像数据在内存中排布为 ARGB1555 小端，A 在高位。

应用方式

VPSS 在系统中的定位如下图所示。

VPSS上下文关系

通过调用 SYS 模块的绑定接⼝，可与 VDEC/VI 和 VO/VENC/SVP 等模块进行绑定，其中前者为 VPSS 的输入源，后者为 VPSS 的接收者。

用户可通过 VPSS MPI 接⼝对 Group 进行管理。每个 Group 仅可与—个输入源绑定。

Group 的通道有两种工作模式：USER 和 PASSTHOUGH，两种模式间可动态切换。两种模式下各通道均可与多个接收者绑定。

USER 模式下主要用于⾮绑定模式下，从通道手动取帧，用于 AI 算法、用户数据分析处理等场景。
PASSTHOUGH 模式主要用于预览和回放场景下做播放控制，如电子放大。

芯片处理流程

VPSS USER 模式数据流图如下所示。

VPSS USER模式数据流图

VPSS PAST 模式数据流图如下所示。

VPSS PAST模式数据流图

VPSS 通道工作于 PAST 模式下，大部分数据处理（如上图虚线框内）是 VPSS 将处理参数透传给 VO 模块，由 VO 模块来—次性完成实际处理，进⽽节省硬件资源占用。

注意

在 PAST 模式时，如果当前为绑定状态时（自动送帧给下级时），RGN Attach 到通道的贴图无效。

输入输出特性

输出图像格式及对齐方式

VPSS对齐方式均采用像素对齐。各芯片支持详情见下表：

数据格式	宽度对齐像素	高度对齐像素	像素字节宽度（bit）
ZH_FMT_YUV420SP ZH_FMT_YUV420SP_VU	16	1	8

示例代码

    ZH_S32 s32Ret = ZH_SUCCESS;
    VPSS_GRP VpssGrp = 0;
    VPSS_CHN VpssChn[VPSS_MAX_CHN_NUM] = { VPSS_CHN0, VPSS_CHN1, VPSS_CHN2, VPSS_CHN3 };
    VPSS_GRP_ATTR_S stGrpVpssAttr;    VPSS_CHN_ATTR_S stVpssChnAttr;
    stGrpVpssAttr.u32MaxW = SRC_WIDTH;
    stGrpVpssAttr.u32MaxH = SRC_HEIGHT;
    stGrpVpssAttr.enPixelFormat = ZH_FMT_YUV420SP;
    stGrpVpssAttr.enCompressMode = COMPRESS_AFBC_16x16;
    stGrpVpssAttr.stFrameRate.s32SrcFrameRate = -1;
    stGrpVpssAttr.stFrameRate.s32DstFrameRate = -1;
    s32Ret = ZH_MPI_VPSS_CreateGrp(VpssGrp, &stGrpVpssAttr);
    if (s32Ret != ZH_SUCCESS) {
        return s32Ret;
    }
    stCropInfo.bEnable = ZH_TRUE;
    stCropInfo.enCropCoordinate = VPSS_CROP_ABS_COOR;
    stCropInfo.stCropRect.s32X = 640;
    stCropInfo.stCropRect.s32Y = 360;
    stCropInfo.stCropRect.u32Width = 640;
    stCropInfo.stCropRect.u32Height = 360;
    s32Ret = ZH_MPI_VPSS_SetGrpCrop(VpssGrp, &stCropInfo);
    if (s32Ret != ZH_SUCCESS) {
        return s32Ret;
    }
    s32Ret = ZH_MPI_VPSS_GetGrpCrop(VpssGrp, &stCropInfo);
    if (s32Ret != ZH_SUCCESS) {
        return s32Ret;
    }
    memset(&stVpssChnAttr, 0, sizeof(VPSS_CHN_ATTR_S));
    stVpssChnAttr.enChnMode = VPSS_CHN_MODE_USER;
    stVpssChnAttr.enCompressMode = COMPRESS_MODE_NONE;
    stVpssChnAttr.enDynamicRange = DYNAMIC_RANGE_SDR8;
    stVpssChnAttr.enPixelFormat = ZH_FMT_YUV420SP;
    stVpssChnAttr.stFrameRate.s32SrcFrameRate = -1;
    stVpssChnAttr.stFrameRate.s32DstFrameRate = -1;
    stChnCropInfo.bEnable = ZH_TRUE;
    stChnCropInfo.enCropCoordinate = VPSS_CROP_RATIO_COOR;
    stChnCropInfo.stCropRect.s32X = 500;
    stChnCropInfo.stCropRect.s32Y = 500;
    stChnCropInfo.stCropRect.u32Width = 500;
    stChnCropInfo.stCropRect.u32Height = 500;
    for (ZH_S32 i = 0; i < VPSS_MAX_CHN_NUM; i++) {
        stVpssChnAttr.u32Width = SRC_WIDTH / VPSS_MAX_CHN_NUM * (i + 1);
        stVpssChnAttr.u32Height = SRC_HEIGHT / VPSS_MAX_CHN_NUM * (i + 1);
        s32Ret = ZH_MPI_VPSS_SetChnAttr(VpssGrp, VpssChn[i], &stVpssChnAttr);
        if (s32Ret != ZH_SUCCESS) {
            return s32Ret;
        }
        s32Ret = ZH_MPI_VPSS_GetChnAttr(VpssGrp, VpssChn[i], &stVpssChnAttr);
        if (s32Ret != ZH_SUCCESS) {
            return s32Ret;
        }
        s32Ret = ZH_MPI_VPSS_SetChnCrop(VpssGrp, VpssChn[i], &stChnCropInfo);
        if (s32Ret != ZH_SUCCESS) {
            return s32Ret;
        }
        s32Ret = ZH_MPI_VPSS_GetChnCrop(VpssGrp, VpssChn[i], &stChnCropInfo);
        if (s32Ret != ZH_SUCCESS) {
            return s32Ret;
        }
        s32Ret = ZH_MPI_VPSS_EnableChn(VpssGrp, VpssChn[i]);
        if (s32Ret != ZH_SUCCESS) {
            return s32Ret;
        }
    }
    s32Ret = ZH_MPI_VPSS_StartGrp(VpssGrp);
    if (s32Ret != ZH_SUCCESS) {
        return s32Ret;
    }
    
    s32Ret = ZH_MPI_VPSS_StopGrp(VpssGrp);
    if (s32Ret != ZH_SUCCESS) {
        return s32Ret;
    }
    for (ZH_S32 i = 0; i < VPSS_MAX_CHN_NUM; i++) {
        s32Ret = ZH_MPI_VPSS_DisableChn(VpssGrp, VpssChn[i]);
        if (s32Ret != ZH_SUCCESS) {
            return s32Ret;
        }
    }
    s32Ret = ZH_MPI_VPSS_DestroyGrp(VpssGrp);
    if (s32Ret != ZH_SUCCESS) {
        return s32Ret;
    }

API 参考

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

ZH_MPI_VPSS_CreateGrp：创建一个 VPSS GROUP。
ZH_MPI_VPSS_DestroyGrp：销毁一个 VPSS GROUP。
ZH_MPI_VPSS_StartGrp：启用 VPSS GROUP。
ZH_MPI_VPSS_StopGrp：禁用 VPSS GROUP。
ZH_MPI_VPSS_ResetGrp：重置一个 VPSS GROUP。
ZH_MPI_VPSS_GetGrpAttr：获取 VPSS GROUP 属性。
ZH_MPI_VPSS_SetGrpAttr：设置VPSS GROUP 属性。
ZH_MPI_VPSS_SetGrpCrop：设置 VPSS GROUP CROP 功能属性。
ZH_MPI_VPSS_GetGrpCrop：获取 VPSS GROUP CROP 功能属性。
ZH_MPI_VPSS_SetGrpRotation：设置 VPSS GROUP 图像固定角度旋转属性。
ZH_MPI_VPSS_GetGrpRotation：获取 VPSS GROUP 图像固定角度旋转属性。
ZH_MPI_VPSS_SendFrame：用户向 VPSS GROUP 发送数据。
ZH_MPI_VPSS_GetGrpFrame：用户从 VPSS GROUP 获取一帧原始图像。
ZH_MPI_VPSS_ReleaseGrpFrame：用户释放一帧原始图像。
ZH_MPI_VPSS_EnableBackupFrame：使能 VPSS GROUP backup 帧。
ZH_MPI_VPSS_DisableBackupFrame：不使能 VPSS GROUP backup 帧。
ZH_MPI_VPSS_SetChnAttr：设置 VPSS 通道属性。
ZH_MPI_VPSS_GetChnAttr：获取 VPSS 通道属性。
ZH_MPI_VPSS_EnableChn：启用 VPSS 通道。
ZH_MPI_VPSS_DisableChn：禁用 VPSS 通道。
ZH_MPI_VPSS_SetChnCrop：设置 VPSS 通道裁剪功能属性。
ZH_MPI_VPSS_GetChnCrop：获取 VPSS 通道裁剪功能属性。
ZH_MPI_VPSS_SetChnRotation：设置 VPSS 通道图像固定角度旋转属性。
ZH_MPI_VPSS_GetChnRotation：获取 VPSS 通道图像固定角度旋转属性。
ZH_MPI_VPSS_SetChnRotationEx：设置 VPSS 通道的任意角度旋转属性。
ZH_MPI_VPSS_GetChnRotationEx：获取 VPSS 通道的任意角度旋转属性。
ZH_MPI_VPSS_GetChnFrame：用户获取一帧通道图像。
ZH_MPI_VPSS_ReleaseChnFrame：用户释放一帧通道图像。
ZH_MPI_VPSS_AttachMbPool：将 VPSS 通道绑定到某个视频缓存 MB 池中。
ZH_MPI_VPSS_DetachMbPool：将 VPSS 通道从某个视频缓存 MB 池中解绑定。
ZH_MPI_VPSS_GetChnFd：获取 VPSS 通道对应的设备文件句柄。
ZH_MPI_VPSS_CloseFd：关闭设备和通道的文件描述符。
ZH_MPI_VPSS_SetModParam：设置 VPSS 的模块参数。
ZH_MPI_VPSS_GetModParam：获取 VPSS 的模块参数。

ZH_MPI_VPSS_CreateGrp

描述

创建一个 VPSS GROUP。

语法

ZH_S32 ZH_MPI_VPSS_CreateGrp(VPSS_GRP VpssGrp, const VPSS_GRP_ATTR_S *pstGrpAttr); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0, VPSS_MAX_GRP_NUM)。	输入
pstGrpAttr	const VPSS_GRP_ATTR_S*	VPSS GROUP 属性指针。	输入

返回值

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

注意事项

不支持重复创建。重复创建返回 ZH_ERR_VPSS_NOT_PERM 错误。

ZH_MPI_VPSS_DestroyGrp

描述

销毁一个 VPSS GROUP。

语法

ZH_S32 ZH_MPI_VPSS_DestroyGrp(VPSS_GRP VpssGrp); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入

返回值

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

注意事项

GROUP 必须已创建。
不支持重复销毁，重复销毁返回 ZH_ERR_VPSS_UNEXIST 错误。
调用此接⼝之前，必须先调用 ZH_MPI_VPSS_StopGrp 禁用此 GROUP。
调用此接⼝时，会—直等待此 GROUP 当前任务处理结束才会真正销毁。

ZH_MPI_VPSS_StartGrp

描述

启用 VPSS GROUP。

语法

ZH_S32 ZH_MPI_VPSS_StartGrp(VPSS_GRP VpssGrp); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入

返回值

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

注意事项

GROUP 必须已创建。
同组调用该函数仅第一次调用成功，重复调用返回失败。

ZH_MPI_VPSS_StopGrp

描述

禁用 VPSS GROUP。

语法

ZH_S32 ZH_MPI_VPSS_StopGrp(VPSS_GRP VpssGrp); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入

返回值

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

注意事项

GROUP 必须已创建。
同组调用该函数仅第一次调用成功，重复调用返回失败。

ZH_MPI_VPSS_ResetGrp

描述

复位 VPSS GROUP。

语法

ZH_S32 ZH_MPI_VPSS_ResetGrp(VPSS_GRP VpssGrp); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入

返回值

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

注意事项

GROUP 必须已创建。
组及通道中待处理或待消耗的数据将会被释放。

ZH_MPI_VPSS_GetGrpAttr

描述

获取 VPSS GROUP 属性。

语法

ZH_S32 ZH_MPI_VPSS_GetGrpAttr(VPSS_GRP VpssGrp, VPSS_GRP_ATTR_S *pstGrpAttr); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
pstGrpAttr	VPSS_GRP_ATTR_S*	VPSS GROUP 属性指针。	输出

返回值

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

注意事项

GROUP 必须已创建。
GROUP 属性必须合法，其中部分静态属性不可动态设置。

ZH_MPI_VPSS_SetGrpAttr

描述

设置 VPSS GROUP 属性。

语法

ZH_S32 ZH_MPI_VPSS_SetGrpAttr(VPSS_GRP VpssGrp, const VPSS_GRP_ATTR_S *pstGrpAttr); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
pstGrpAttr	const VPSS_GRP_ATTR_S*	VPSS GROUP 属性指针。	输入

返回值

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

注意事项

GROUP 必须已创建。
GROUP 属性必须合法，其中部分静态属性不可动态设置。

ZH_MPI_VPSS_SetGrpCrop

描述

设置 VPSS CROP 功能属性。

语法

ZH_S32 ZH_MPI_VPSS_SetGrpCrop(VPSS_GRP VpssGrp, const VPSS_CROP_INFO_S *pstCropInfo); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
pstCropInfo	const VPSS_CROP_INFO_S*	CROP 功能参数。	输入

返回值

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

注意事项

GROUP 必须已创建。
相对模式裁剪时，裁剪区域坐标取值范围为 [0, 999]，裁剪区域宽高取值范围为 [1,1000]。
CROP 区域的尺⼨不能小于 VPSS 最小尺⼨，不能超过 VPSS 支持的最大输入分辨率；裁剪区域起始点不支持负坐标，裁剪区域右边界不能超出 VPSS 支持的最大输入宽度，裁剪区域下边界不能超出 VPSS 支持的最大输入高度。
如果裁剪区域超出图像范围，则裁剪坐标向原点方向移动，优先保证裁剪出的宽高与所设置的参数相同。
如果裁剪宽度大于输入图像宽度，则裁剪输出宽度调整为输入图像宽度。
如果裁剪高度大于输入图像高度，则裁剪输出高度调整为输入图像高度。
在有绑定 VO 时，不推荐使用此接⼝做电子放大，建议通道模式设置为 PAST 模式，并使用 ZH_MPI_VPSS_SetChnCrop 做电子放大功能。
通道设置为 PAST 时，只有在绑定了 VO 的情况下才生效。

ZH_MPI_VPSS_GetGrpCrop

描述

获取 VPSS CROP 功能属性。

语法

ZH_S32 ZH_MPI_VPSS_GetGrpCrop(VPSS_GRP VpssGrp, VPSS_CROP_INFO_S *pstCropInfo); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
pstCropInfo	VPSS_CROP_INFO_S*	CROP 功能参数。	输出

返回值

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

注意事项

GROUP 必须已创建。

ZH_MPI_VPSS_SetGrpRotation

描述

设置 VPSS GROUP 图像固定角度旋转属性。

语法

ZH_S32 ZH_MPI_VPSS_SetGrpRotation(VPSS_GRP VpssGrp, ROTATION_E enRotation); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
enRotation	ROTATION_E	旋转属性。	输入

返回值

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

注意事项

GROUP 必须已创建。
仅支持 0 度、90 度、180 度、270 度的旋转，不支持任意角度旋转。

ZH_MPI_VPSS_GetGrpRotation

描述

获取 VPSS GROUP 图像固定角度旋转属性。

语法

ZH_S32 ZH_MPI_VPSS_GetGrpRotation(VPSS_GRP VpssGrp, ROTATION_E *penRotation); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
penRotation	ROTATION_E*	旋转属性。	输出

返回值

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

注意事项

GROUP 必须已创建。

ZH_MPI_VPSS_SendFrame

描述

用户向 VPSS 发送数据。

语法

ZH_S32 ZH_MPI_VPSS_SendFrame(VPSS_GRP VpssGrp, VPSS_GRP_PIPE VpssGrpPipe, const VIDEO_FRAME_INFO_S *pstVideoFrame, ZH_S32 s32MilliSec);

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssGrpPipe	VPSS_GRP_PIPE	VPSS 组的管道号。取值只能为 0。	输入
pstVideoFrame	const VIDEO_FRAME_INFO_S]*	待发送的图像信息。	输入
s32MilliSec	ZH_S32	超时参数。设为 -1 时，为阻塞接⼝。 0 时为⾮阻塞接⼝。大于 0 时为超时等待时间，超时时间的单位为毫秒（ms）。	输入

返回值

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

注意事项

GROUP 必须已创建。
用户使用此接⼝时，可以自行进行帧率控制。
VPSS 通道设置为 PAST 模式时使用此接⼝前，VPSS 应正常启动，推荐与 VO 绑定，否则用户通过获取图像接⼝获取的图像将会使用 VGS 处理。
VPSS 通道设置为 USER 模式，用户通过获取图像接⼝获取图像。

ZH_MPI_VPSS_GetGrpFrame

描述

用户从 GROUP 获取一帧原始图像。主要应用场景：高清设备解码回放，要求暂停、步进时，PIP 层和普通视频层上的两个通道显示同一帧图像。

通过本接⼝和 ZH_MPI_VPSS_SendFrame 等接⼝的配合使用，可实现该功能。

语法

ZH_S32 ZH_MPI_VPSS_GetGrpFrame(VPSS_GRP VpssGrp, VPSS_GRP_PIPE VpssGrpPipe, VIDEO_FRAME_INFO_S *pstVideoFrame);

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssGrpPipe	VPSS_GRP_PIPE	VPSS 组的管道号。取值只能为 0。	输入
pstVideoFrame	VIDEO_FRAME_INFO_S*	图像信息。	输出

返回值

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

注意事项

GROUP 必须已创建。
获取的图像要及时释放，否则将造成MB不够或解码回放时停⽌，建议与 ZH_MPI_VPSS_ReleaseGrpFrame 接⼝配对使用。
使用 ZH_MPI_VPSS_EnableBackupFrame 使能了 backup 帧时才能获取。

ZH_MPI_VPSS_ReleaseGrpFrame

描述

用户释放一帧源图像。

语法

ZH_S32 ZH_MPI_VPSS_ReleaseGrpFrame(VPSS_GRP VpssGrp, VPSS_GRP_PIPE VpssGrpPipe, const VIDEO_FRAME_INFO_S *pstVideoFrame);

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssGrpPipe	VPSS_GRP_PIPE	VPSS 组的管道号。取值只能为 0。	输入
pstVideoFrame	const VIDEO_FRAME_INFO_S*	图像信息。	输入

返回值

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

注意事项

实际上此接⼝的 VpssGrp 参数并无实际用途，可在取值范围内任意设置。注意 PIPE 号取值只能为 0。
此接⼝需与 ZH_MPI_VPSS_GetGrpFrame 配对使用。

ZH_MPI_VPSS_EnableBackupFrame

描述

使能 Backup 帧。

语法

ZH_S32 ZH_MPI_VPSS_EnableBackupFrame(VPSS_GRP VpssGrp); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入

返回值

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

注意事项

GROUP 必须已创建。

ZH_MPI_VPSS_DisableBackupFrame

描述

不使能 Backup 帧。

语法

ZH_S32 ZH_MPI_VPSS_DisableBackupFrame(VPSS_GRP VpssGrp);

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入

返回值

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

注意事项

GROUP 必须已创建。

ZH_MPI_VPSS_SetChnAttr

描述

设置 VPSS 通道属性。

语法

ZH_S32 ZH_MPI_VPSS_SetChnAttr(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, const VPSS_CHN_ATTR_S *pstChnAttr); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0, VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
pstChnAttr	const VPSS_CHN_ATTR_S*	VPSS 通道属性。	输入

返回值

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

注意事项

GROUP 必须已创建。
具体成员取值及功能限制参见 VPSS_CHN_ATTR_S 结构体说明。

ZH_MPI_VPSS_GetChnAttr

描述

获取 VPSS 通道属性。

语法

ZH_S32 ZH_MPI_VPSS_GetChnAttr(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, VPSS_CHN_ATTR_S *pstChnAttr); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0, VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
pstChnAttr	VPSS_CHN_ATTR_S*	VPSS 通道属性。	输出

返回值

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

注意事项

GROUP 必须已创建。

ZH_MPI_VPSS_EnableChn

描述

启用 VPSS 通道。

语法

ZH_S32 ZH_MPI_VPSS_EnableChn(VPSS_GRP VpssGrp, VPSS_CHN VpssChn); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0, VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入

返回值

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

注意事项

多次使能仅第一次返回成功，后续调用返回失败。
GROUP 必须已创建。

ZH_MPI_VPSS_DisableChn

描述

禁用 VPSS 通道。

语法

ZH_S32 ZH_MPI_VPSS_DisableChn(VPSS_GRP VpssGrp, VPSS_CHN VpssChn); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0, VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入

返回值

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

注意事项

多次禁用仅第一次返回成功，后续调用返回失败。
GROUP 必须已创建。

ZH_MPI_VPSS_SetChnCrop

描述

设置 VPSS 通道裁剪功能属性。

语法

ZH_S32 ZH_MPI_VPSS_SetChnCrop(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, const VPSS_CROP_INFO_S *pstCropInfo); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0, VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
pstCropInfo	const VPSS_CROP_INFO_S*	CROP 功能参数。	输入

返回值

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

注意事项

GROUP 必须已创建。
如果裁剪区域超出图像范围，裁剪坐标向原点方向移动，优先保证裁剪出的宽高与所设置的参数相同。
如果裁剪宽度大于输入图像宽度，则裁剪输出宽度调整为输入图像宽度。
如果裁剪高度大于输入图像高度，则裁剪输出高度调整为输入图像高度。
其他限制与 ZH_MPI_VPSS_SetGrpCrop 相同。

ZH_MPI_VPSS_GetChnCrop

描述

获取 VPSS 通道裁剪功能属性。

语法

ZH_S32 ZH_MPI_VPSS_GetChnCrop(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, VPSS_CROP_INFO_S *pstCropInfo); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
pstCropInfo	VPSS_CROP_INFO_S*	CROP 功能参数。	输出

返回值

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

注意事项

GROUP 必须已创建。

ZH_MPI_VPSS_SetChnRotation

描述

设置 VPSS 通道图像固定角度旋转属性。

语法

ZH_S32 ZH_MPI_VPSS_SetChnRotation(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, ROTATION_E enRotation); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
enRotation	ROTATION_E	旋转属性。	输入

返回值

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

注意事项

GROUP 必须已创建。
通道属性必须已设置。
仅支持 0 度、90 度、180 度、270 度的旋转，不支持任意角度旋转。
通道为 PAST 模式时不生效。

ZH_MPI_VPSS_GetChnRotation

描述

获取 VPSS 通道图像固定角度旋转属性。

语法

ZH_S32 ZH_MPI_VPSS_GetChnRotation(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, ROTATION_E *penRotation); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
penRotation	ROTATION_E*	旋转属性。	输出

返回值

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

注意事项

GROUP 必须已创建。

ZH_MPI_VPSS_SetChnRotationEx

描述

设置 VPSS 通道的任意角度旋转属性。

语法

ZH_S32 ZH_MPI_VPSS_SetChnRotationEx(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, const VPSS_ROTATION_EX_ATTR_S* pstRotationExAttr);

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
pstRotationExAttr	const VPSS_ROTATION_EX_ATTR_S*	任意角度旋转属性结构体指针。	输入

返回值

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

注意事项

暂不支持。

ZH_MPI_VPSS_GetChnRotationEx

描述

获取VPSS的任意角度旋转属性。

语法

ZH_S32 ZH_MPI_VPSS_GetChnRotationEx(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, VPSS_ROTATION_EX_ATTR_S* pstRotationExAttr);

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
pstRotationExAttr	VPSS_ROTATION_EX_ATTR_S*	任意角度旋转属性结构体指针。	输出

返回值

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

注意事项

GROUP 必须已创建。

ZH_MPI_VPSS_GetChnFrame

描述

用户从通道获取—帧处理完成的图像。

语法

ZH_S32 ZH_MPI_VPSS_GetChnFrame(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, VIDEO_FRAME_INFO_S *pstVideoFrame, ZH_S32 s32MilliSec);

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
pstVideoFrame	VIDEO_FRAME_INFO_S*	处理完成的图像信息。	输出
s32MilliSec	ZH_S32	超时参数。 s32MilliSec 设为 -1 时，为阻塞接⼝。 0 时为⾮阻塞接⼝。大于 0 时为超时等待时间，超时时间的单位为毫秒（ms）。	输入

返回值

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

注意事项

GROUP 必须已创建。
队列深度不为 0，才能获取到图像。
调用该接口获取图像，不会对后端绑定的模块有影响。如后端绑定 VO 显示，可以在显示过程中获取图像，VO 仍正常显示，不会受到影响。
超时参数。
- 当 s32MilliSec 设为 -1 时，表示阻塞模式，程序一直等待，直到获取到图像才返回。
- 如果 s32MilliSec 等于 0 时，表示⾮阻塞模式。
- 如果 s32MilliSec 大于 0 时，表示超时等待模式，参数的单位是毫秒，指超时时间，在此时间内如果没有获取到图像，则超时返回。
通道为 PAST 模式时，调用该接⼝时会使用 VGS 进行图像处理。
默认在私有 MB 模式下，通道为 USER 模式时，最大输出帧个数限制到 3 个。
默认在私有 MB 模式下，通道为 PAST 模式时，不限制最大输出帧个数。

ZH_MPI_VPSS_ReleaseChnFrame

描述

用户释放一帧通道图像。

语法

ZH_S32 ZH_MPI_VPSS_ReleaseChnFrame(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, const VIDEO_FRAME_INFO_S *pstVideoFrame);

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS通道号。取值范围：[0, VPSS_MAX_CHN_NUM。	输入
pstVideoFrame	const VIDEO_FRAME_INFO_S*	图像信息。	输入

返回值

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

注意事项

此接⼝需与 ZH_MPI_VPSS_GetChnFrame 配对使用。
接⼝调用同 ZH_MPI_VPSS_GetChnFrame 调用次数一一对应，不允许同一帧多次调用。
通过 ZH_MPI_VPSS_GetChnFrame 获取的帧，需要及时调用该接⼝释放，否则达到最大输出帧个数后无法获取新的帧。

ZH_MPI_VPSS_AttachMbPool

描述

将 VPSS 的通道绑定到某个视频缓存 MB 池中。

语法

ZH_S32 ZH_MPI_VPSS_AttachMbPool(VPSS_GRP VpssGrp, VPSS_CHN VpssChn, MB_POOL hMbPool); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入
hMbPool	MB_POOL	视频缓存 MB 池信息。	输入

返回值

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

注意事项

必须保证组已创建。
仅在通道为 USER 模式时生效，通道为 PAST 时不受影响。
用户必须调用接⼝ ZH_MPI_MB_CreatePool 创建一个视频缓存MB池，再通过调用接⼝ ZH_MPI_VPSS_AttachMbPool 把当前组的通道绑定到固定 PoolId 的 MB 池中。支持多个组的多个通道绑定到同一个 MB 池中。
当要切换当前组绑定的MB池时，只需再调一次接⼝ ZH_MPI_VPSS_AttachMbPool 正确配置需要绑定到的MB池即可。
hMbPool 必须保证是已创建 MB 池的有效 PoolId。
在调用 ZH_MPI_VPSS_DetachMbPool 后，销毁创建的 MB 之前，需要保证 MB 没有被 VPSS 后端绑定的模块使用，可以通过 sleep 或清除后端模块通道缓存的方式先把 MB 都释放，再销毁缓存 MB 池。
绑定后，通道申请的 MB 均是从此 MB 池中获取。

ZH_MPI_VPSS_DetachMbPool

描述

将 VPSS 的通道从某个视频缓存 MB 池中解绑定。

语法

ZH_S32 ZH_MPI_VPSS_DetachMbPool(VPSS_GRP VpssGrp, VPSS_CHN VpssChn); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入

返回值

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

注意事项

必须保证组已创建。

ZH_MPI_VPSS_GetChnFd

描述

获取 VPSS 通道对应的设备文件句柄。

语法

ZH_S32 ZH_MPI_VPSS_GetChnFd(VPSS_GRP VpssGrp, VPSS_CHN VpssChn); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROU P号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入

返回值

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

注意事项

必须保证组已创建。

ZH_MPI_VPSS_CloseFd

描述

关闭设备和通道的文件描述符。

语法

ZH_S32 ZH_MPI_VPSS_CloseFd(VPSS_GRP VpssGrp, VPSS_CHN VpssChn); 

参数

参数名	数据类型	描述	输入/输出
VpssGrp	VPSS_GRP	VPSS GROUP 号。取值范围：[0,VPSS_MAX_GRP_NUM)。	输入
VpssChn	VPSS_CHN	VPSS 通道号。取值范围：[0, VPSS_MAX_CHN_NUM)。	输入

返回值

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

注意事项

必须保证组已创建。
允许重复调用，均返回成功。

ZH_MPI_VPSS_SetModParam

描述

设置 VPSS 的模块参数。

语法

ZH_S32 ZH_MPI_VPSS_SetModParam(const VPSS_MOD_PARAM_S *pstModParam); 

参数

参数名	数据类型	描述	输入/输出
pstModParam	VPSS_MOD_PARAM_S	模块参数。	输入

返回值

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

注意事项

通常在所有 VPSS 组未被创建前调用。
允许 VPSS 组已创建后调用，但正在运行的组不会立即生效，重新释放和申请该组后生效。

ZH_MPI_VPSS_GetModParam

描述

获取 VPSS 的模块参数。

语法

ZH_S32 ZH_MPI_VPSS_GetModParam(VPSS_MOD_PARAM_S *pstModParam); 

参数

参数名	数据类型	描述	输入/输出
pstModParam	VPSS_MOD_PARAM_S	模块参数。	输出

返回值

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

数据类型

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

VPSS_MAX_GRP_NUM：定义 VPSS GROUP 的最大个数。
VPSS_MAX_GRP_PIPE_NUM：定义 VPSS GROUP 上最大的 PIPE 个数。
VPSS_MAX_CHN_NUM：定义 VPSS 通道的最大个数。
VPSS_MIN_IMAGE_WIDTH：定义 VPSS 图像的最小宽度。
VPSS_MIN_IMAGE_HEIGHT：定义 VPSS 图像的最小高度。
VPSS_MAX_IMAGE_WIDTH：定义 VPSS 图像的最大宽度。
VPSS_MAX_IMAGE_HEIGHT：定义 VPSS 图像的最大高度。
VPSS_GRP：定义 VPSS 组号。
VPSS_GRP_PIPE：定义 VPSS 组的管道号。
VPSS_CHN：定义 VPSS 通道号。
VPSS_CROP_COORDINATE_E：定义 CROP 起点坐标的模式。
VPSS_CROP_INFO_S：定义 CROP 功能所需信息。
VPSS_ROTATION_EX_ATTR_S：定义 VPSS 的任意角度旋转属性。
VPSS_MOD_PARAM_S：定义设置模块参数。
VPSS_GRP_ATTR_S：定义 VPSS GROU P属性。
VPSS_CHN_ATTR_S：定义 VPSS 通道属性。
VPSS_CHN_MODE_E：定义 VPSS CHN 工作模式。

VPSS_MAX_GRP_NUM

说明

定义 VPSS GROUP 的最大个数。

定义

#define VPSS_MAX_GRP_NUM 256

注意事项

芯片不同，可能有所差异，具体指参数值定义请看 zh_defines.h。

VPSS_MAX_GRP_PIPE_NUM

说明

定义 VPSS GROUP 的最大个数。

定义

#define VPSS_MAX_GRP_PIPE_NUM 1

注意事项

只能设置为 0 。

VPSS_MAX_CHN_NUM

说明

定义 VPSS 通道的最大个数。

定义

#define VPSS_MAX_CHN_NUM 4

注意事项

芯片不同，可能有所差异，具体指参数值定义请看 zh_defines.h。

VPSS_MIN_IMAGE_WIDTH

说明

定义 VPSS 图像的最小宽度。

定义

#define VPSS_MIN_IMAGE_WIDTH 64

注意事项

芯片不同，可能有所差异，具体指参数值定义请看 zh_defines.h。

VPSS_MIN_IMAGE_HEIGHT

说明

定义 VPSS 图像的最小高度。

定义

#define VPSS_MIN_IMAGE_HEIGHT 64

注意事项

芯片不同，可能有所差异，具体指参数值定义请看 zh_defines.h。

VPSS_MAX_IMAGE_WIDTH

说明

定义 VPSS 图像的最大宽度。

定义

#define VPSS_MAX_IMAGE_WIDTH 8192

注意事项

芯片不同，可能有所差异，具体指参数值定义请看 zh_defines.h。

VPSS_MAX_IMAGE_HEIGHT

说明

定义 VPSS 图像的最大高度。

定义

#define VPSS_MAX_IMAGE_HEIGHT 8192

注意事项

芯片不同，可能有所差异，具体指参数值定义请看 zh_defines.h。

VPSS_GRP

说明

定义 VPSS 组号。

定义

typedef ZH_S32 VPSS_GRP;

VPSS_GRP_PIPE

说明

定义VPSS组的管道号。

定义

typedef ZH_S32 VPSS_GRP_PIPE;

注意事项

VPSS_GRP_PIPE 取值只能为 0。

VPSS_CHN

说明

定义 VPSS 通道号。

定义

typedef ZH_S32 VPSS_CHN;

VPSS_CROP_COORDINATE_E

说明

定义 CROP 起点坐标的模式。

定义

typedef enum zhVPSS_CROP_COORDINATE_E {
    VPSS_CROP_RATIO_COOR = 0,
    VPSS_CROP_ABS_COOR
} VPSS_CROP_COORDINATE_E;

成员

成员名称	描述
VPSS_CROP_RATIO_COOR	相对坐标。
VPSS_CROP_ABS_COOR	绝对坐标。

注意事项

相对坐标，即起始点的坐标值是以与当前图像宽高的比率来表示，使用时需做转换，具体请参见 VPSS_CROP_INFO_S。

VPSS_CROP_INFO_S

说明

定义 CROP 功能所需信息。

定义

typedef struct zhVPSS_CROP_INFO_S {
    ZH_BOOL                 bEnable;
    VPSS_CROP_COORDINATE_E  enCropCoordinate;
    RECT_S                  stCropRect;
} VPSS_CROP_INFO_S;

成员

成员名称	数据类型	描述
bEnable	ZH_BOOL	CROP 使能开关。
enCropCoordinate	VPSS_CROP_COORDINATE_E	CROP 起始点坐标模式。
stCropRect	RECT_S	CROP 的矩形区域。

注意事项

若 enCropCoordinate 为 VPSS_CROP_RATIO_COOR（相对坐标模式），使用 stCropRect 的成员时应做转换，计算公式为：
- s32X = 起始点坐标 x 原始图像宽度/1000，合法取值范围：[0, 999] ，计算完成后会进行取整操作和对齐操作。公式同样适用于纵坐标计算。
- u32Width = 区域宽度 x 实际图像宽度/1000 ，区域宽度取值范围：[1, 1000]。计算完成后会进行取整操作和对齐操作。公式同样适用于区域高度计算。
坐标和宽高要求 2 像素对齐。

VPSS_ROTATION_EX_ATTR_S

说明

定义 VPSS 的任意角度旋转属性。

定义

typedef struct zhVPSS_ROTATION_EX_ATTR_S {
    ZH_BOOL       bEnable;
    ROTATION_EX_S stRotationEx;
} VPSS_ROTATION_EX_ATTR_S;

成员

成员名称	数据类型	描述
bEnable	ZH_BOOL	Enable/Disable 任意角度旋转功能。
stRotationEx	ROTATION_EX_S	任意角度旋转的详细属性。具体描述请参考系统控制章节。

注意事项

暂不支持任意角旋转。

VPSS_MOD_PARAM_S

说明

定义设置模块参数。

定义

typedef struct zhVPSS_MOD_PARAM_S {
    MB_SOURCE_E enVpssMBSource;
} VPSS_MOD_PARAM_S;

成员

成员名称	数据类型	描述
enVpssMBSource	MB_SOURCE_E	视频缓存池类型。默认为私有缓冲池。 0：公共缓冲池。 1：模块缓冲池。保留，暂不支持。 2：私有缓冲池。 3：用户缓冲池。

VPSS_GRP_ATTR_S

说明

定义 VPSS GROUP 属性。

定义

typedef struct zhVPSS_GRP_ATTR_S {
    ZH_U32                     u32MaxW;
    ZH_U32                     u32MaxH;
    PIXEL_FORMAT_E             enPixelFormat;
    DYNAMIC_RANGE_E            enDynamicRange;
    FRAME_RATE_CTRL_S          stFrameRate;
    COMPRESS_MODE_E            enCompressMode;
    ZH_U32                     u32MaxQueue;
} VPSS_GRP_ATTR_S;

成员

成员名称	数据类型	描述
u32MaxW	ZH_U32	输入图像的最大宽度。静态属性，创建 Group 时设定，不可更改，暂未被使用。
u32MaxH	ZH_U32	输入图像的最大高度。静态属性，创建 Group 时设定，不可更改，暂未被使用。
enPixelFormat	PIXEL_FORMAT_E	输入图像像素格式。静态属性，创建 Group 时设定，不可更改，暂未被使用。
enDynamicRange	DYNAMIC_RANGE_E	输入图像动态范围。静态属性，创建 Group 时设定，不可更改，暂未被使用。
stFrameRate	FRAME_RATE_CTRL_S	组帧率控制。动态属性，立即生效。
enCompressMode	COMPRESS_MODE_E	group 取的图像的压缩方式。静态属性，创建 Group 时设定，不可更改。
u32MaxQueue	ZH_U32	group 最大队列数。静态属性，创建 Group 时设定，不可更改，暂未被使用。

注意事项

无效参数无需设置，不做异常参数检查。
若要开启帧率控制，源帧率必须大于 0，目标帧率可以为 0，此时会根据源帧率进行阻塞式的帧率控制，并将所有输入帧丢弃。

VPSS_CHN_ATTR_S

说明

定义 VPSS 通道的属性。

定义

typedef struct zhVPSS_CHN_ATTR_S {
    VPSS_CHN_MODE_E     enChnMode;
    ZH_U32              u32Width;
    ZH_U32              u32Height;
    VIDEO_FORMAT_E      enVideoFormat;
    PIXEL_FORMAT_E      enPixelFormat;
    DYNAMIC_RANGE_E     enDynamicRange;
    COMPRESS_MODE_E     enCompressMode;
    FRAME_RATE_CTRL_S   stFrameRate;
    ZH_BOOL             bMirror;
    ZH_BOOL             bFlip;
    ZH_U32              u32Depth;
    ASPECT_RATIO_S      stAspectRatio;
    ZH_U32              u32FrameBufCnt;
} VPSS_CHN_ATTR_S;

成员

成员名称	数据类型	描述
enChnMode	VPSS_CHN_MODE_E	通道工作模式。动态属性。
u32Width	ZH_U32	目标图像宽度。动态属性。
u32Height	ZH_U32	目标图像高度。动态属性。
enVideoFormat	VIDEO_FORMAT_E	目标图像视频格式。动态属性。
enPixelFormat	PIXEL_FORMAT_E	目标图像像素格式。动态属性。
enDynamicRange	DYNAMIC_RANGE_E	目标图像动态范围。动态属性，暂未被使用。
enCompressMode	COMPRESS_MODE_E	目标图像压缩模式。动态属性。
stFrameRate	FRAME_RATE_CTRL_S	帧率控制信息。动态属性，立即生效。
bMirror	ZH_BOOL	水平镜像使能。动态属性。
bFlip	ZH_BOOL	垂直翻转使能。动态属性。
u32Depth	ZH_U32	用户获取通道图像的队列长度。取值范围：[0, 8]。动态属性。
stAspectRatio	ASPECT_RATIO_S	幅形比参数。动态属性。
u32FrameBufCnt	ZH_U32	最大目标图像缓冲个数仅在通道缓存模式为 private 模式时生效。静态属性。

注意事项

源帧率与目标帧率都为 -1，则不进行帧率控制。
若要开启帧率控制，源帧率必须大于 0，目标帧率可以为 0，此时会将所有通道待处理图像丢弃。
u32Depth 深度为 0 时，表示不保留通道图像，全部丢弃。
u32FrameBufCnt 和 u32Depth 同时配置为 1 时，用户无获取通道输出图像的行为发生则该通道输出卡顿。
bMirror 与 bFlip 可同时生效，并与通道旋转角度参数（固定旋转角度或任意旋转角度）共同决定通道图像的输出效果，具体详见：ZH_MPI_VPSS_SetChnRotation。
动态属性，如做不特殊说明，均延后一帧生效。
u32FrameBufCnt 最大目标图像缓冲个数设置小于 VPSS 最小目标图像缓存个数时，内部强制为 VPSS 最小目标图像缓存个数，以保证 VPSS 输出满足最小可用缓存。
u32FrameBufCnt 最大目标图像缓冲个数仅在通道缓存模式为 private 模式（MB_SOURCE_PRIVATE）时生效, 具体详见：ZH_MPI_VPSS_SetModParam。

相关数据类型及接口

ZH_MPI_VPSS_SetChnRotation。
ZH_MPI_VPSS_SetModParam。

VPSS_CHN_MODE_E

说明

定义 VPSS CHN 工作模式。

定义

typedef enum zhVPSS_CHN_MODE_E {
    VPSS_CHN_MODE_USER  = 0,
    VPSS_CHN_MODE_AUTO  = 1,
    VPSS_CHN_MODE_PASSTHROUGH = 2,
    VPSS_CHN_MODE_BUTT
} VPSS_CHN_MODE_E;

成员

成员名称	描述
VPSS_CHN_MODE_USER	用户设置模式。
VPSS_CHN_MODE_AUTO	自动模式。（弃用模式，不推荐使用）
VPSS_CHN_MODE_PASSTHROUGH	穿透模式。使用该模式时，VPSS硬件本身不处理数据，将传递解析数据至下级处理。

注意事项

通道工作模式推荐使用 USER 模式和 PAST 模式，AUTO 模式弃用，工作模式的工作流程详见 VPSS USER 模式数据流图/VPSS PAST 模式数据流图。
通道模式为 PAST 时，需要与 VO 绑定才可发挥模式作用。

VPSS错误码

视频处理子系统 API VPSS 错误码如下所示：

错误代码	宏定义	描述
0xA0068001	ZH_ERR_VPSS_INVALID_DEVID	VPSS GROUP 号无效。
0xA0068002	ZH_ERR_VPSS_INVALID_CHNID	VPSS 通道号无效。
0xA0068003	ZH_ERR_VPSS_ILLEGAL_PARAM	VPSS 参数设置无效。
0xA0068004	ZH_ERR_VPSS_EXIST	VPSS GROUP 已创建。
0xA0068005	ZH_ERR_VPSS_UNEXIST	VPSS GROUP 未创建。
0xA0068006	ZH_ERR_VPSS_NULL_PTR	输入参数空指针错误。
0xA0068008	ZH_ERR_VPSS_NOT_SUPPORT	操作不支持。
0xA0068009	ZH_ERR_VPSS_NOT_PERM	操作不允许。
0xA006800C	ZH_ERR_VPSS_NOMEM	分配内存失败。
0xA006800D	ZH_ERR_VPSS_NOBUF	分配 BUF 池失败。
0xA006800E	ZH_ERR_VPSS_BUF_EMPTY	图像队列为空。
0xA006800F	ZH_ERR_VPSS_BUF_FULL	图像队列已满。
0xA0068010	ZH_ERR_VPSS_NOTREADY	VPSS 系统未初始化。
0xA0068012	ZH_ERR_VPSS_BUSY	VPSS 系统忙。
0xA0068013	ZH_ERR_VPSS_SIZE_NOT_ENOUGH	MB 块大小不够。

概述​

功能描述​

基本概念​

像素格式排布​

应用方式​

芯片处理流程​

输入输出特性​

输出图像格式及对齐方式​

示例代码​

API 参考​

ZH_MPI_VPSS_CreateGrp​

ZH_MPI_VPSS_DestroyGrp​

ZH_MPI_VPSS_StartGrp​

ZH_MPI_VPSS_StopGrp​

ZH_MPI_VPSS_ResetGrp​

ZH_MPI_VPSS_GetGrpAttr​

ZH_MPI_VPSS_SetGrpAttr​

ZH_MPI_VPSS_SetGrpCrop​

ZH_MPI_VPSS_GetGrpCrop​

ZH_MPI_VPSS_SetGrpRotation​

ZH_MPI_VPSS_GetGrpRotation​

ZH_MPI_VPSS_SendFrame​

ZH_MPI_VPSS_GetGrpFrame​

ZH_MPI_VPSS_ReleaseGrpFrame​

ZH_MPI_VPSS_EnableBackupFrame​

ZH_MPI_VPSS_DisableBackupFrame​

ZH_MPI_VPSS_SetChnAttr​

ZH_MPI_VPSS_GetChnAttr​

ZH_MPI_VPSS_EnableChn​

ZH_MPI_VPSS_DisableChn​

ZH_MPI_VPSS_SetChnCrop​

ZH_MPI_VPSS_GetChnCrop​

ZH_MPI_VPSS_SetChnRotation​

ZH_MPI_VPSS_GetChnRotation​

ZH_MPI_VPSS_SetChnRotationEx​

ZH_MPI_VPSS_GetChnRotationEx​

ZH_MPI_VPSS_GetChnFrame​

ZH_MPI_VPSS_ReleaseChnFrame​

ZH_MPI_VPSS_AttachMbPool​

ZH_MPI_VPSS_DetachMbPool​

ZH_MPI_VPSS_GetChnFd​

ZH_MPI_VPSS_CloseFd​

ZH_MPI_VPSS_SetModParam​

ZH_MPI_VPSS_GetModParam​

数据类型​

VPSS_MAX_GRP_NUM​

VPSS_MAX_GRP_PIPE_NUM​

VPSS_MAX_CHN_NUM​

VPSS_MIN_IMAGE_WIDTH​

VPSS_MIN_IMAGE_HEIGHT​

VPSS_MAX_IMAGE_WIDTH​

VPSS_MAX_IMAGE_HEIGHT​

VPSS_GRP​

VPSS_GRP_PIPE​

VPSS_CHN​

VPSS_CROP_COORDINATE_E​

VPSS_CROP_INFO_S​

VPSS_ROTATION_EX_ATTR_S​

VPSS_MOD_PARAM_S​

VPSS_GRP_ATTR_S​

VPSS_CHN_ATTR_S​

VPSS_CHN_MODE_E​

VPSS错误码​

概述

功能描述

基本概念

像素格式排布

应用方式

芯片处理流程

输入输出特性

输出图像格式及对齐方式

示例代码

API 参考

ZH_MPI_VPSS_CreateGrp

ZH_MPI_VPSS_DestroyGrp

ZH_MPI_VPSS_StartGrp

ZH_MPI_VPSS_StopGrp

ZH_MPI_VPSS_ResetGrp

ZH_MPI_VPSS_GetGrpAttr

ZH_MPI_VPSS_SetGrpAttr

ZH_MPI_VPSS_SetGrpCrop

ZH_MPI_VPSS_GetGrpCrop

ZH_MPI_VPSS_SetGrpRotation

ZH_MPI_VPSS_GetGrpRotation

ZH_MPI_VPSS_SendFrame

ZH_MPI_VPSS_GetGrpFrame

ZH_MPI_VPSS_ReleaseGrpFrame

ZH_MPI_VPSS_EnableBackupFrame

ZH_MPI_VPSS_DisableBackupFrame

ZH_MPI_VPSS_SetChnAttr

ZH_MPI_VPSS_GetChnAttr

ZH_MPI_VPSS_EnableChn

ZH_MPI_VPSS_DisableChn

ZH_MPI_VPSS_SetChnCrop

ZH_MPI_VPSS_GetChnCrop

ZH_MPI_VPSS_SetChnRotation

ZH_MPI_VPSS_GetChnRotation

ZH_MPI_VPSS_SetChnRotationEx

ZH_MPI_VPSS_GetChnRotationEx

ZH_MPI_VPSS_GetChnFrame

ZH_MPI_VPSS_ReleaseChnFrame

ZH_MPI_VPSS_AttachMbPool

ZH_MPI_VPSS_DetachMbPool

ZH_MPI_VPSS_GetChnFd

ZH_MPI_VPSS_CloseFd

ZH_MPI_VPSS_SetModParam

ZH_MPI_VPSS_GetModParam

数据类型

VPSS_MAX_GRP_NUM

VPSS_MAX_GRP_PIPE_NUM

VPSS_MAX_CHN_NUM

VPSS_MIN_IMAGE_WIDTH

VPSS_MIN_IMAGE_HEIGHT

VPSS_MAX_IMAGE_WIDTH

VPSS_MAX_IMAGE_HEIGHT

VPSS_GRP

VPSS_GRP_PIPE

VPSS_CHN

VPSS_CROP_COORDINATE_E

VPSS_CROP_INFO_S

VPSS_ROTATION_EX_ATTR_S

VPSS_MOD_PARAM_S

VPSS_GRP_ATTR_S

VPSS_CHN_ATTR_S

VPSS_CHN_MODE_E

VPSS错误码