区域管理 (RGN)
概述
用户一般都需要在视频中叠加 OSD 用于显示一些特定的信息（如：通道号、时间戳等），必要时还会填充色块。这些叠加在视频上的 OSD 和遮挡在视频上的色块统称为区域。REGION 模块，用于统一管理这些区域资源。
区域管理可以实现区域的创建，并叠加到视频中或对视频进行遮挡。例如，实际应用中，用户通过创建一个区域，通过 ZH_MPI_RGN_AttachToChn，将该区域叠加到某个通道（如 VENC 通道）中。在通道进行调度时，则会将 OSD 叠加在视频中。一个区域支持通过设置通道显示属性接口指定到多个通道中（如：多个 VENC 通道，多个 VI 通道，甚至多个 VENC 和 VI 通道），且支持 在每个通道的显示属性（如位置、层次、透明度等）都不同。
基本概念
-
区域类型
-
OVERLAY: 视频叠加区域，其中区域支持位图的加载、图层叠加等功能。效果图如下所示。
-
COVER：视频遮挡区域，其中区域支持纯色块遮挡。效果图如下所示。
-
MOSAIC：马赛克遮挡区域，支持精度调节。效果图如下所示。
-
-
区域层次
区域层次表示区域的叠加级别，层次值越大，表示区域的显示级别越高。当发生重叠时，层次值大的将会覆盖层次值小的。
-
位图填充（针对 OVERLAY 有效）
位图填充是指将位图的内存值填充到区域内存空间中，位图将会从区域的左上角开始填充。当位图小于区域时，只能填充一部分内存，剩余部分保持原有值；位图大小等于区域时，将刚好全部填充；当位图大于区域时，位图只能将自身和区域一样大小的内存信息填充到区域中。
-
区域公共属性（RGN_ATTR_S）
用户创建一个区域时，需要设置该属性信息，它包含公共的资源信息。例如，OVERLAY 包含像素格式，大小。
-
通道显示属性（RGN_CHN_ATTR_S）
通道显示属性表明区域在某通道的显示特征。例如，OVERLAY 的通道显示属性包含显示位置，层次，前景 Alpha，背景 Alpha 等。
当通道显示属性中的区域是否显示(is_show)为 TRUE 时，表示显示在该通道中；反之，表示在该通道中存在，但处于隐藏状态。
region 支持的模块信息
| 类型 | 支持模块 | 设备号取值范围 | 通道号取值范围 |
|---|---|---|---|
| OVERLAY | VENC | 0 | [0,VENC_MAX_CHN_NUM - 1] |
| VO | [0, VO_MAX_LAYER_NUM - 1] | [0,VO_MAX_CHN_NUM - 1] | |
| VPSS | [0, VPSS_MAX_GRP_NUM - 1] | [0,VPSS_MAX_CHN_NUM - 1] | |
| COVER | VENC | 0 | [0,VENC_MAX_CHN_NUM - 1] |
| VO | [0, VO_MAX_LAYER_NUM - 1] | [0,VO_MAX_CHN_NUM - 1] | |
| VPSS | [0, VPSS_MAX_GRP_NUM - 1] | [0,VPSS_MAX_CHN_NUM - 1] | |
| MOSAIC | VPSS | [0, VPSS_MAX_GRP_NUM - 1] | [0,VPSS_MAX_CHN_NUM - 1] |
| VO | [0, VO_MAX_LAYER_NUM - 1] | [0,VO_MAX_CHN_NUM - 1] |
region 支持的功能
| 支持的功能 | OVERLAY | COVER | MOSAIC | LINE | |||||
|---|---|---|---|---|---|---|---|---|---|
| 支持的模块 | VO | VENC | VPSS | VO | VENC | VPSS | VO | VPSS | VPSS |
| 像素格式 | BGRA8888、NV12 | BGRA8888、NV12 | BGRA8888、NV12 | RGBA8888 | RGBA8888 | RGBA8888 | N/A | N/A | RGBA8888 |
| 叠加层次 | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | N/A |
| 位图填充 | 支持 | 支持 | 支持 | N/A | N/A | N/A | N/A | N/A | N/A |
| 叠加透明度 | 支持 | 支持 | 支持 | N/A | N/A | N/A | N/A | N/A | N/A |
| 前景alpha范围 | 不支持 | 不支持 | 不支持 | N/A | N/A | N/A | N/A | N/A | N/A |
| 背景alpha范围 | 不支持 | 不支持 | 不支持 | N/A | N/A | N/A | N/A | N/A | N/A |
| 反色 | 不支持 | 不支持 | 不支持 | N/A | N/A | N/A | N/A | N/A | N/A |
| QP保护 | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A |
使用步骤介绍
OVERLAY使用步骤
使用过程包含以下步骤：
- 调用 ZH_MPI_RGN_Create 填充区域属性并创建区域。
- 调用 ZH_MPI_RGN_AttachToChn 将画布绑定到通道特定区域上。
- 调用 ZH_MPI_RGN_GetCanvasInfo 获取画布信息。
- 将位图数据写入画布信息中。
- 调用 ZH_MPI_RGN_UpdateCanvas 更新画布。
- 更新画布信息时重复步骤 3 ~ 步骤 5。
- 不用时调用 ZH_MPI_RGN_DetachFromChn 将画布从绑定通道中解绑。
- 调用 ZH_MPI_RGN_Destroy 销毁区域。
COVER使用步骤
使用过程包含以下步骤：
- 调用 ZH_MPI_RGN_Create 填充遮挡区域相关属性并创建区域。
- 调用 ZH_MPI_RGN_AttachToChn 将画布绑定到通道特定区域上。
- 调用 ZH_MPI_RGN_GetDisplayAttr 获取遮挡区域信息。
- 修改需要改变的参数（例如位置信息），调用 ZH_MPI_RGN_SetDisplayAttr 更新信息。
- 更新遮挡区域信息时重复步骤 3 ~ 步骤 4。
- 不用时调用 ZH_MPI_RGN_DetachFromChn 将画布从绑定通道中解绑。
- 调用 ZH_MPI_RGN_Destroy 销毁区域。
示例代码
coverHandle = 0;
stCoverAttr.enType = COVER_RGN;
s32Ret = ZH_MPI_RGN_Create(coverHandle, &stCoverAttr);
if (ZH_SUCCESS != s32Ret) {
ZH_LOGE("failed with %#x!", s32Ret);
return ZH_FAILURE;
}
stCoverChn.enModId = ZH_ID_VENC;
stCoverChn.s32ChnId = 0;
stCoverChn.s32DevId = vencChn;
stCoverChnAttr.bShow = ZH_TRUE;
stCoverChnAttr.enType = COVER_RGN;
stCoverChnAttr.unChnAttr.stCoverChn.enCoverType = AREA_RECT;
stCoverChnAttr.unChnAttr.stCoverChn.stRect.s32X = pstRgnCtx->stRegion.s32X;
stCoverChnAttr.unChnAttr.stCoverChn.stRect.s32Y = pstRgnCtx->stRegion.s32Y;
stCoverChnAttr.unChnAttr.stCoverChn.stRect.u32Width = pstRgnCtx->stRegion.u32Width;
stCoverChnAttr.unChnAttr.stCoverChn.stRect.u32Height = pstRgnCtx->stRegion.u32Height;
stCoverChnAttr.unChnAttr.stCoverChn.u32Color = 0xffffffff;
stCoverChnAttr.unChnAttr.stCoverChn.u32Layer = 0;
s32Ret = ZH_MPI_RGN_AttachToChn(coverHandle, &stCoverChn, &stCoverChnAttr);
if (ZH_SUCCESS != s32Ret) {
ZH_LOGE("failed with %#x!", s32Ret);
goto AttachCover_failed;
}
stCoverChnAttr.unChnAttr.stCoverChn.stRect.s32X = 64;
stCoverChnAttr.unChnAttr.stCoverChn.stRect.s32Y = 64;
stCoverChnAttr.unChnAttr.stCoverChn.stRect.u32Width = 256;
stCoverChnAttr.unChnAttr.stCoverChn.stRect.u32Height = 256;
stCoverChnAttr.unChnAttr.stCoverChn.u32Color = 0x00f800;
stCoverChnAttr.unChnAttr.stCoverChn.u32Layer = 1;
s32Ret = ZH_MPI_RGN_SetDisplayAttr(coverHandle, &stCoverChn, &stCoverChnAttr);
if (ZH_SUCCESS != s32Ret) {
ZH_LOGE("failed with %#x!", s32Ret);
goto exit;
}
ZH_MPI_RGN_DetachFromChn(coverHandle, &stCoverChn);
ZH_MPI_RGN_Destroy(coverHandle);
API参考
区域管理模块主要提供区域资源的控制管理功能，包括区域的创建、销毁，获取与设置区域属性，获取与设置区域的通道显示属性等。 该功能模块为用户提供以下API:
- ZH_MPI_RGN_Create：创建区域。
- ZH_MPI_RGN_Destroy：销毁区域。
- ZH_MPI_RGN_GetAttr：获取区域属性。
- ZH_MPI_RGN_SetAttr：设置区域属性。
- ZH_MPI_RGN_SetBitMap：设置区域位图。
- ZH_MPI_RGN_AttachToChn：将区域叠加到通道上。
- ZH_MPI_RGN_DetachFromChn：将区域从通道中撤出。
- ZH_MPI_RGN_SetDisplayAttr：设置区域的通道显示属性。
- ZH_MPI_RGN_GetDisplayAttr：获取区域的通道显示属性。
- ZH_MPI_RGN_GetCanvasInfo：获取区域的显示画布信息。
- ZH_MPI_RGN_UpdateCanvas：更新区域的显示画布信息。
ZH_MPI_RGN_Create
描述
创建区域。
语法
ZH_S32 ZH_MPI_RGN_Create(RGN_HANDLE Handle, const RGN_ATTR_S *pstRegion)
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, RGN_MAX_HANDLE_NUM)。 | 输入 |
| pstRgion | const RGN_ATTR_S | 区域属性指针。 | 输⼊ |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 该句柄由用户指定，意义等同于 ID 号。
- 不支持重复创建。
- 区域属性必须合法，具体约束参见 RGN_ATTR_S。
- 区域属性指针不能为空。
- 创建 COVER、MOSAIC时，只需指定区域类型即可。其它的属性，如区域位置，层次等信息在调用 ZH_MPI_RGN_AttachToChn 接口时指定。
- 创建区域时，本接口只进行基本的参数的检查，譬如：最小宽高，最大宽高等；当区域 attach 到通道上时，根据各通道 模块支持类型的约束条件进行更加有针对性的参数检查，譬如支持的像素格式等。
相关主题
ZH_MPI_RGN_Destroy
描述
销毁区域。
语法
ZH_S32 ZH_MPI_RGN_Destroy(RGN_HANDLE Handle);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, RGN_MAX_HANDLE_NUM)。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 调用该接口的过程中，不允许同时调用 ZH_MPI_RGN_SetAttr/ ZH_MPI_RGN_SetBitMap。
ZH_MPI_RGN_GetAttr
描述
获取区域属性。
语法
ZH_S32 ZH_MPI_RGN_GetAttr(RGN_HANDLE Handle, RGN_ATTR_S *pstRegion)
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
| pstRgion | RGN_ATTR_S* | 区域属性指针。 | 输出 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 区域属性指针不能为空。
ZH_MPI_RGN_SetAttr
描述
设置区域属性。
语法
ZH_S32 ZH_MPI_RGN_SetAttr(RGN_HANDLE Handle, const RGN_ATTR_S *pstRegion);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
| pstRgion | const RGN_ATTR_S* | 区域属性指针。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 区域属性指针不能为空。
- 调用该接口的过程中，不允许同时调用 ZH_MPI_RGN_Destroy。
- 当调用 ZH_MPI_RGN_SetBitMap 后调用该接口，如果设置新的区域小于原有区域，原有区域将会被销毁，需要重新调用 ZH_MPI_RGN_SetBitMap 设置位图。
ZH_MPI_RGN_SetBitMap
描述
设置区域位图，即对区域进行位图填充。
语法
ZH_S32 ZH_MPI_RGN_SetBitMap(RGN_HANDLE Handle, const BITMAP_S *pstBitmap);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
| pstBitmap | const BITMAP_S* | 位图属性指针。具体描述参见 系统控制。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 支持位图的大小和区域的大小不一致。
- 位图从区域的 (0,0) 点开始加载。当位图比区域大时，将会自动将图像剪裁成区域大小。
- 位图属性指针不能为空。
- 支持多次调用。
- 此接口只对 OVERLAY 有效。
- 调用该接口的过程中，不允许同时调用 ZH_MPI_RGN_Destroy。
ZH_MPI_RGN_AttachToChn
描述
将区域叠加到通道上。
语法
ZH_S32 ZH_MPI_RGN_AttachToChn(RGN_HANDLE Handle, const MPP_CHN_S *pstChn, const
RGN_CHN_ATTR_S *pstChnAttr);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
| pstChn | const MPP_CHN_S* | 通道结构体指针。 具体描述参见 系统控制。 | 输入 |
| pstChnAttr | const RGN_CHN_ATTR_S* | 区域通道显示属性指针。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 通道结构体指针不能为空。
- 区域通道显示属性指针不能为空。
- 不支持多次叠加。
ZH_MPI_RGN_DetachFromChn
描述
将区域从通道中撤出。
语法
ZH_S32 ZH_MPI_RGN_DetachFromChn(RGN_HANDLE Handle, const MPP_CHN_S *pstChn);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
| pstChn | const MPP_CHN_S* | 通道结构体指针。具体描述参见 系统控制。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 通道结构体指针不能为空。
- 不支持多次调用。
ZH_MPI_RGN_SetDisplayAttr
描述
设置区域的通道显示属性。
语法
ZH_S32 ZH_MPI_RGN_SetDisplayAttr(RGN_HANDLE Handle, const MPP_CHN_S *pstChn, const RGN_CHN_ATTR_S *pstChnAttr);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
| pstChn | const MPP_CHN_S* | 通道结构体指针。具体描述参见 系统控制。 | 输入 |
| pstChnAttr | const RGN_CHN_ATTR_S* | 区域通道显示属性指针。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 建议先获取属性，再设置。
- 通道结构体指针不能为空。
- 区域通道显示属性指针不能为空。
- 区域必须先叠加到通道上。
ZH_MPI_RGN_GetDisplayAttr
描述
设置区域的通道显 示属性。
语法
ZH_S32 ZH_MPI_RGN_GetDisplayAttr(RGN_HANDLE Handle, const MPP_CHN_S *pstChn, RGN_CHN_ATTR_S *pstChnAttr);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
| pstChn | const MPP_CHN_S* | 通道结构体指针。具体描述参见 系统控制。 | 输入 |
| pstChnAttr | RGN_CHN_ATTR_S* | 区域通道显示属性指针。 | 输出 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 通道结构体指针不能为空。
- 区域通道显示属性指针不能为空。
ZH_MPI_RGN_GetCanvasInfo
描述
获取区域的显示画布信息。
语法
ZH_S32 ZH_MPI_RGN_GetCanvasInfo(RGN_HANDLE Handle, RGN_CANVAS_INFO_S *pstCanvasInfo);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
| pstCanvasInfo | RGN_CANVAS_INFO_S* | 区域显示画布信息。 | 输出 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，请参见 RGN 错误码。 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 本接口与 ZH_MPI_RGN_SetBitMap 功能类似，主要用于实现 overlay 的位图数据导入，相对于 ZH_MPI_RGN_SetBitMap 接口，该接口直接写入更新画布数据，节省内存拷贝，故更推荐使用这种方式。
- 本接口与 ZH_MPI_RGN_UpdateCanvas 接口配套使用，写入画布数据后，调用 ZH_MPI_RGN_UpdateCanvas 接口将画布真正更新到 Attach 的模块中去。
- 接口可以与 ZH_MPI_RGN_SetBitMap 混用，但不推荐混用。
ZH_MPI_RGN_UpdateCanvas
描述
更新区 域的显示画布数据。
语法
ZH_S32 ZH_MPI_RGN_UpdateCanvas(RGN_HANDLE Handle);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| Handle | RGN_HANDLE | 区域句柄号。 必须是未使用的 handle 号。 取值范围：[0, [RGN_MAX_HANDLE_NUM])。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，请参见 RGN 错误码 |
需求
头文件： zh_comm_rgn.h，zh_mpi_rgn.h。
注意事项
- 区域必须已创建。
- 本接口配合 ZH_MPI_RGN_GetCanvasInfo使用。主要用于画布内存数据更新之后，进行画布切换显示。
- 每次调用本接口前，都必须先获取画布信息，然后在调用本接口进行更新，否则不生效。本接口仅支持 OVERLAY 类型的区域。
- 和ZH_MPI_RGN_GetCanvasInfo配合使用时，需要注意更新画布需要线程同步，既调用ZH_MPI_RGN_GetCanvasInfo后调用该接口，严格按照这一顺序，否则更新画布不成功。
数据类型
区域管理相关数据类型、数据结构定义如下：
- RGN_MIN_WIDTH：定义区域最小宽度。
- RGN_MIN_HEIGHT：定义区域最小高度。
- RGN_COVER_MIN_X：定义遮挡区域最小水平 X。
- RGN_COVER_MIN_Y：定义遮挡区域最小垂直 Y。
- RGN_COVER_MAX_X：定义遮挡区域最大水平 X。
- RGN_COVER_MAX_Y：定义遮挡区域最大垂直 Y。
- RGN_COVER_MAX_WIDTH：定义遮挡区域最大宽度。
- RGN_COVER_MAX_HEIGHT：定义遮挡区域最大高度。
- RGN_OVERLAY_MIN_X：定义 OVERLAY 区域起始位置 X 坐标最小值。
- RGN_OVERLAY_MIN_Y：定义 OVERLAY 区域起始位置 Y 坐标最小值。
- RGN_OVERLAY_MAX_X：定义 OVERLAY 区域起始位置 X 坐标最大值。
- RGN_OVERLAY_MAX_Y：定义 OVERLAY 区域起始位置 Y 坐标最大值。
- RGN_OVERLAY_MAX_WIDTH：定义 OVERLAY 区域最大宽度。
- RGN_OVERLAY_MAX_HEIGHT：定义 OVERLAY 区域最大高度。
- RGN_MOSAIC_MIN_X：定义马赛克区域起始位置 X 坐标最小值。
- RGN_MOSAIC_MIN_Y：定义马赛克区域起始位置 Y 坐标最小值。
- RGN_MOSAIC_MAX_X：定义马赛克区域起始位置 X 坐标最大值。
- RGN_MOSAIC_MAX_Y：定义马赛克区域起始位置 Y 坐标最大值。
- RGN_MOSAIC_MIN_WIDTH：定义马赛克区域最小宽度。
- RGN_MOSAIC_MIN_HEIGHT：定义马赛克区域最小高度。
- RGN_MOSAIC_MAX_WIDTH：定义马赛克区域最大宽度。
- RGN_MOSAIC_MAX_HEIGHT：定义马赛克区域最大高度。
- RGN_LINE_MIN_X：定义画线的最小水平坐标。
- RGN_LINE_MIN_Y：定义画线的最小垂直坐标。
- RGN_LINE_MAX_X：定义画线的最大水平坐标。
- RGN_LINE_MAX_Y：定义画线的最大垂直坐标。
- RGN_LINE_MIN_THICK：定义画线的最小线宽。
- RGN_LINE_MAX_THICK：定义画线的最大线宽。
- RGN_ALIGN：定义区域对齐方式。
- RGN_MAX_HANDLE_NUM：定义最大的 RGN 句柄个数。
- RGN_MAX_BUF_NUM：定义最大的 RGN 画布数量。
- RGN_HANDLE：定义区域句柄。
- RGN_TYPE_E：定义区域类型。
- RGN_COORDINATE_E：定义坐标类型。
- OVERLAY_ATTR_S：定义通道叠加区域属性结构体。
- OVERLAY_CHN_ATTR_S：定义通道叠加区域的通道显示属性。
- RGN_AREA_TYPE_E：定义 cover 类型和 mosaic 类型的区域类型。
- COVER_CHN_ATTR_S：定义遮挡区域的通道显示属性。
- MOSAIC_BLK_SIZE_E：定义 mosaic 类型的块大小。
- MOSAIC_CHN_ATTR_S：定义马赛克区域的通道显示属性。
- RGN_ATTR_U：定义区域属性联合体。
- RGN_CHN_ATTR_U：定义区域通道显示属性联合体。
- RGN_ATTR_S：定义区域属性结构体。
- RGN_CHN_ATTR_S：定义马赛克区域的通道显示属性。
- RGN_CANVAS_INFO_S：定义画布信息。
RGN_MIN_WIDTH
说明
定义区域最小宽度。
定义
#define RGN_MIN_WIDTH 16
RGN_MIN_HEIGHT
说明
定义区域最小高度。
定义
#define RGN_MIN_HEIGHT 16
RGN_COVER_MIN_X
说明
定义遮挡区域最小水平 X。
定义
#define RGN_COVER_MIN_X 0
RGN_COVER_MIN_Y
说明
定义遮挡区域最小垂直 Y。
定义
#define RGN_COVER_MIN_Y 0
RGN_COVER_MAX_X
说明
定义遮挡区域最大水平 X。
定义
#define RGN_COVER_MAX_X 8192
RGN_COVER_MAX_Y
说明
定义遮挡区 域最大垂直Y。
定义
#define RGN_COVER_MAX_Y 8192
RGN_COVER_MAX_WIDTH
说明
定义遮挡区域最大宽度。
定义
#define RGN_COVER_MAX_WIDTH 8192
RGN_COVER_MAX_HEIGHT
说明
定义遮挡区域最大高度。
定义
#define RGN_COVER_MAX_HEIGHT 8192
RGN_OVERLAY_MIN_X
说明
定义 OVERLAY 区域起始位置 X 坐标最小值。
定义
#define RGN_OVERLAY_MIN_X 0
RGN_OVERLAY_MIN_Y
说明
定义 OVERLAY 区域起始位置 Y 坐标最小值。
定义
#define RGN_OVERLAY_MIN_Y 0
RGN_OVERLAY_MAX_X
说明
定义 OVERLAY 区域起始位置 X 坐标最大值。
定义
#define RGN_OVERLAY_MAX_X 8192
RGN_OVERLAY_MAX_Y
说明
定义 OVERLAY 区域起始位置 Y 坐标最大值。
定义
#define RGN_OVERLAY_MAX_Y 8192
RGN_OVERLAY_MAX_WIDTH
说明
定义 OVERLAY 区域最大宽度。
定义
#define RGN_OVERLAY_MAX_WIDTH 8192
RGN_OVERLAY_MAX_HEIGHT
说明
定义 OVERLAY 区域最大高度。
定义
#define RGN_OVERLAY_MAX_HEIGHT 8192
RGN_MOSAIC_MIN_X
说明
定义马赛克区域起始位置 X 坐标最小值。
定义
#define RGN_MOSAIC_MIN_X 0
RGN_MOSAIC_MIN_Y
说明
定义马赛克区域起始位置 Y 坐标最小值。
定义
#define RGN_MOSAIC_MIN_Y 0
RGN_MOSAIC_MAX_X
说明
定义马赛克区域起始位置 X 坐标最大值。
定义
#define RGN_MOSAIC_MAX_X 8192
RGN_MOSAIC_MAX_Y
说明
定义马赛克区域起始位置 Y 坐标最大值。
定义
#define RGN_MOSAIC_MAX_Y 8192
RGN_MOSAIC_MIN_WIDTH
说明
定义马赛克区域最小宽度。
定义
#define RGN_MOSAIC_MIN_WIDTH 32
RGN_MOSAIC_MIN_HEIGHT
说明
定义马赛克区域最小高度。
定义
#define RGN_MOSAIC_MIN_HEIGHT 32
RGN_MOSAIC_MAX_WIDTH
说明
定义马赛克区域最大宽度。
定义
#define RGN_MOSAIC_MAX_WIDTH 8192
RGN_MOSAIC_MAX_HEIGHT
说明
定义马赛克区域最大高度。
定义
#define RGN_MOSAIC_MAX_HEIGHT 8192
RGN_LINE_MIN_X
说明
定义画线的最小水平坐标。
定义
#define RGN_LINE_MIN_X 0
RGN_LINE_MIN_Y
说明
定义画线的最小垂直坐标。
定义
#define RGN_LINE_MIN_Y 0
RGN_LINE_MAX_X
说明
定义画线的最大水平坐标。
定义
#define RGN_LINE_MAX_X 8192
RGN_LINE_MAX_Y
说明
定义画线的最大垂直坐标。
定义
#define RGN_LINE_MAX_Y 8192
RGN_LINE_MIN_THICK
说明
定义画线的最小线宽。
定义
#define RGN_LINE_MIN_THICK 1
RGN_LINE_MAX_THICK
说明
定义画线的最大线宽。
定义
#define RGN_LINE_MAX_THICK 32
RGN_ALIGN
说明
定义区域对齐方式。
定义
#define RGN_ALIGN 16
RGN_MAX_HANDLE_NUM
说明
定义最大的 RGN 句柄个数。
定义
#define RGN_MAX_HANDLE_NUM 128
RGN_MAX_BUF_NUM
说明
定义最大的 RGN 画布数量。
定义
#define RGN_MAX_BUF_NUM 2
RGN_HANDLE
说明
定义区域句柄。
定义
typedef ZH_U32 RGN_HANDLE;
RGN_TYPE_E
说明
定义区域类型。
定义
typedef enum zhRGN_TYPE_E {
OVERLAY_RGN = 0,
OVERLAY_EX_RGN,
COVER_RGN,
MOSAIC_RGN,
LINE_RGN,
RGN_BUTT
} RGN_TYPE_E;
成员
| 成员名称 | 描述 |
|---|---|
| OVERLAY_RGN | 视频叠加区域。 |
| OVERLAY_EX_RGN | 不支持。 |
| COVER_RGN | 视频遮挡区域。 |
| MOSAIC_RGN | MOSAIC 视频区域。 |
| LINE_RGN | 视频画线区域。(不支持) |
RGN_COORDINATE_E
说明
定义坐标类型。
定义
typedef enum zhRGN_COORDINATE_E {
RGN_ABS_COOR = 0,
RGN_RATIO_COOR
} RGN_COORDINATE_E;
成员
| 成员名称 | 描述 |
|---|---|
| RGN_ABS_COOR | 坐标类型为绝对坐标。 |
| RGN_RATIO_COOR | 不支持 |
注意事项
默认类型为绝对坐标。
OVERLAY_ATTR_S
说明
定义通道叠加区域属性结构体。
定义
typedef struct zhOVERLAY_ATTR_S {
PIXEL_FORMAT_E enPixelFmt;
SIZE_S stSize;
ZH_U32 u32CanvasNum;
ZH_U32 u32ClutNum;
ZH_U32 u32Clut[RGN_CLUT_NUM];
VIDEO_PROC_DEV_TYPE_E enVProcDev;
} OVERLAY_ATTR_S;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| enPixelFmt | PIXEL_FORMAT_E | 像素格式。具体描述参见 系统控制。 取值范围：参照 region 支持的功能。 |
| stSize | SIZE_S | 区域的高宽。 取值范围：当 overlay 绑定到 VENC 通道时，支持：
|
| u32CanvasNum | ZH_U32 | 区域的可用画布数量 取值范围：[1, RGN_MAX_BUF_NUM]。 静态属性。 |
| u32ClutNum | ZH_U32 | 不支持。 |
| u32Clut | ZH_U32 | 不支持。 |
| enVProcDev | VIDEO_PROC_DEV_TYPE_E | 不支持。 |
注意事项
- u32CanvasNum 如果设置小于 1，将会强制被设置为 2。
- u32CanvasNum 如果大于 RGN_MAX_BUF_NUM ，将会被设置为 RGN_MAX_BUF_NUM。
- u32CanvasNum 推荐为 2，为 1 时，在更新画布内容时可能画布换行行为贴图，会造成数据不同步。
- u32CanvasNum 在第一次设置属性时被确定，之后不可更改。
OVERLAY_CHN_ATTR_S
说明
定义通道叠加区域的通道显示属性。
定义
typedef struct zhOVERLAY_CHN_ATTR_S {
POINT_S stPoint;
ZH_U32 u32FgAlpha;
ZH_U32 u32BgAlpha;
ZH_U32 u32Layer;
OVERLAY_QP_INFO_S stQpInfo;
} OVERLAY_CHN_ATTR_S;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| stPoint | POINT_S | 区域位置。 取值范围：
|
| u32FgAlpha | ZH_U32 | Alpha 位为 1 的像素点的透明度。也称前景 Alpha。 取值范围：[0, 255]。 取值越小，越透明。图像亮度。 |
| u32BgAlpha | ZH_U32 | Alpha 位为 0 的像素点的透明度。也称背景 Alpha。 取值范围：[0, 255]。 取值越小，越透明。图像亮度。 |
| u32Layer | ZH_U32 | 区域层次。取值范围：[0, 7]。值越大，层次越高。 |
| stQpInfo | OVERLAY_QP_INFO_S | 不支持。 |
注意事项
- 0 表示全透明。
- 255 表示不透明。
RGN_AREA_TYPE_E
说明
定义 cover 类型和 mosaic 类型的区域类型。
定义
typedef enum zhRGN_AREA_TYPE_E {
AREA_RECT = 0,
AREA_QUAD_RANGLE,
AREA_BUTT
} RGN_AREA_TYPE_E;
成员
| 成员名称 | 描述 |
|---|---|
| AREA_RECT | 矩形区域。 |
| AREA_QUAD_RANGLE | 不支持。 |
COVER_CHN_ATTR_S
说明
定义遮挡区域的通道显示属性。
定义
typedef struct zhCOVER_CHN_ATTR_S {
RECT_S stRect;
ZH_U32 u32Color;
ZH_U32 u32Layer;
RGN_COORDINATE_E enCoordinate;
} COVER_CHN_ATTR_S;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| stRect | RECT_S | 区域位置、宽高。 位置取值范围：
宽高取值范围：
|
| u32Color | ZH_U32 | 区域颜色。以 ARGB888 定义颜色值。 |
| u32Layer | ZH_U32 | 区域层次。取值范围：[0, 7]。 动态属性。 |
| enCoordinate | RGN_COORDINATE_E | 不支持。 |
MOSAIC_BLK_SIZE_E
说明
定义 mosaic 类型的块大小。
定义
typedef enum zhMOSAIC_BLK_SIZE_E {
MOSAIC_BLK_SIZE_8 = 0,
MOSAIC_BLK_SIZE_16,
MOSAIC_BLK_SIZE_32,
MOSAIC_BLK_SIZE_64,
MOSAIC_BLK_SIZE_BUTT
} MOSAIC_BLK_SIZE_E;
成员
| 成员名称 | 描述 |
|---|---|
| MOSAIC_BLK_SIZE_8 | 8×8 大小。 |
| MOSAIC_BLK_SIZE_16 | 16×16 大小。 |
| MOSAIC_BLK_SIZE_32 | 32×32 大小。 |
| MOSAIC_BLK_SIZE_64 | 64×64 大小。 |
MOSAIC_CHN_ATTR_S
说明
定义马赛克区域的通道显示属性。
定义
typedef struct zhMOSAIC_CHN_ATTR_S {
RGN_AREA_TYPE_E enMosaicType;
union {
RECT_S stRect;
RGN_QUADRANGLE_S stQuadRangle;
};
MOSAIC_BLK_SIZE_E enBlkSize;
ZH_U32 u32Layer;
} MOSAIC_CHN_ATTR_S;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| enMosaicType | RGN_AREA_TYPE_E | 不支持。 |
| stRect | RECT_S | 马赛克矩形区域位置。 |
| stQuadRangle | RGN_QUADRANGLE_S | 不支持。 |
| enBlkSize | MOSAIC_BLK_SIZE_E | 马赛克显示类型。 |
| u32Layer | ZH_U32 | 区域层次。 |
RGN_ATTR_U
说明
定义区域属性联合体。
定义
typedef union zhRGN_ATTR_U {
OVERLAY_ATTR_S stOverlay;
} RGN_ATTR_U;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| stOverlay | OVERLAY_ATTR_S | 通道叠加区域属性。 |
RGN_CHN_ATTR_U
说明
定义区域通道显示属性联合体。
定义
typedef union zhRGN_CHN_ATTR_U {
OVERLAY_CHN_ATTR_S stOverlayChn;
COVER_CHN_ATTR_S stCoverChn;
MOSAIC_CHN_ATTR_S stMosaicChn;
LINE_CHN_ATTR_S stLineChn;
} RGN_CHN_ATTR_U;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| stOverlayChn | OVERLAY_CHN_ATTR_S | 通道叠加区域通道显示属性。 |
| stCoverChn | COVER_CHN_ATTR_S | 遮挡区域通道显示属性。 |
| stMosaicChn | MOSAIC_CHN_ATTR_S | 马赛克显示属性。 |
| stLineChn | LINE_CHN_ATTR_S | 不支持。 |
RGN_ATTR_S
说明
定义区域属性结构体。
定义
typedef struct zhRGN_ATTR_S {
RGN_TYPE_E enType;
RGN_ATTR_U unAttr;
} RGN_ATTR_S;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| enType | RGN_TYPE_E | 区域类型。 |
| unAttr | RGN_ATTR_U | 区域属性。 |
RGN_CHN_ATTR_S
说明
定义马赛克区域的通道显示属性。
定义
typedef struct zhRGN_CHN_ATTR_S {
ZH_BOOL bShow;
RGN_TYPE_E enType;
RGN_CHN_ATTR_U unChnAttr;
} RGN_CHN_ATTR_S;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| bShow | ZH_BOOL | 区域是否显示。 取值范围：ZH_TRUE，ZH_FALSE。 动态属性。 |
| enType | RGN_TYPE_E | 区域类型。 静态属性。 |
| unChnAttr | RGN_CHN_ATTR_U | 区域通道显示属性。 |
RGN_CANVAS_INFO_S
说明
定义画布信息。
定义
typedef struct zhRGN_CANVAS_INFO_S {
MB_BLK canvasBlk;
ZH_U64 u64VirAddr;
SIZE_S stSize;
ZH_U32 u32VirWidth;
ZH_U32 u32VirHeight;
PIXEL_FORMAT_E enPixelFmt;
} RGN_CANVAS_INFO_S;
成员
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| canvasBlk | MB_BLK | 画布数据的 MB 内存。 |
| u64VirAddr | ZH_U64 | 画布数据的虚地址。 |
| stSize | SIZE_S | 画布的大小。 |
| u32VirWidth | ZH_U32 | 画布的虚宽。 |
| u32VirHeight | ZH_U32 | 画布的虚高。 |
| enPixelFmt | PIXEL_FORMAT_E | 画布的像素格式。 |
RGN 错误码
区域管理 API RGN 错误码如下表所示。
| 错误代码 | 宏定义 | 描述 |
|---|---|---|
| 0xA0038001 | ZH_ERR_RGN_INVALID_DEVID | 设备 ID 超出合法范围。 |
| 0xA0038002 | ZH_ERR_RGN_INVALID_CHNID | 通道组号错误或无效区域 句柄。 |
| 0xA0038003 | ZH_ERR_RGN_ILLEGAL_PARAM | 参数超出合法范围。 |
| 0xA0038004 | ZH_ERR_RGN_EXIST | 重复创建已存在的设备、通道或资源。 |
| 0xA0038005 | ZH_ERR_RGN_UNEXIST | 试图使用或者销毁不存在的设备、通道或者资源。 |
| 0xA0038006 | ZH_ERR_RGN_NULL_PTR | 函数参数中有空指针。 |
| 0xA0038007 | ZH_ERR_RGN_NOT_CONFIG | 模块没有配置。 |
| 0xA0038008 | ZH_ERR_RGN_NOT_SUPPORT | 不支持的参数或者功能。 |
| 0xA0038009 | ZH_ERR_RGN_NOT_PERM | 该操作不允许，如试图修改静态配置参数。 |
| 0xA003800C | ZH_ERR_RGN_NOMEM | 分配内存失败，如系统内存不足。 |
| 0xA003800D | ZH_ERR_RGN_NOBUF | 分配缓存失败，如申请的数据缓冲区太大。 |
| 0xA003800E | ZH_ERR_RGN_BUF_EMPTY | 缓冲区中无数据。 |
| 0xA003800F | ZH_ERR_RGN_BUF_FULL | 缓冲区中数据满。 |
| 0xA0038010 | ZH_ERR_RGN_NOTREADY | 系统没有初始化或没有加载相应模块。 |
| 0xA0038011 | ZH_ERR_RGN_BADADDR | 地址非法。 |
| 0xA0038012 | ZH_ERR_RGN_BUSY | 系统忙。 |