9.3. API参考

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

9.3.1. CVI_RGN_Create

【描述】

创建一个区域

【语法】

CVI_S32 CVI_RGN_Create(RGN_HANDLE Handle, const RGN_ATTR_S *pstRegion);

【参数】

参数名称

描述

输入/输出

Handle
区域号。
必须是未使用过的Handle号
取值范围:[0, 0xFFFFFFFF]。

输入

pstRegion

区域属性指针。

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • Handle由用户指定，必须为单一不可重复。

  • 不支持重复创建

  • 创建Overlay/OverLayEx以外的区域时，只需指定区域类型即可。其他信息，是在调用 CVI_RGN_AttachToChn 时指定。

【举例】

 CVI_S32 s32Ret;
RGN_HANDLE Handle = 0;
RGN_ATTR_S stRegion;
RGN_ATTR_S stRgnAttr;

stRegion.enType = OVERLAYEX_RGN;
stRegion.unAttr.stOverlayEx.enPixelFormat = PIXEL_FORMAT_ARGB_1555;
stRegion.unAttr.stOverlayEx.stSize.u32Height = 200;
stRegion.unAttr.stOverlayEx.stSize.u32Width = 300;
stRegion.unAttr.stOverlayEx.u32BgColor = 0x00000000; // ARGB1555 transparent
stRegion.unAttr.stOverlayEx.u32CanvasNum = 2;
s32Ret = CVI_RGN_Create(Handle, &stRegion);
if (s32Ret != CVI_SUCCESS) {
  return CVI_FAILURE;
}
s32Ret = CVI_RGN_GetAttr (Handle, &stRgnAttr);
if (s32Ret != CVI_SUCCESS) {
  return CVI_FAILURE;
}
stRgnAttr.unAttr.stOverlay.u32BgColor = 0x0000801f; // ARGB1555 blue
s32Ret = CVI_RGN_SetAttr (Handle, &stRgnAttr);
if (s32Ret != CVI_SUCCESS) {
  return CVI_FAILURE;
}
s32Ret = CVI_RGN_Destory (Handle);
if (s32Ret != CVI_SUCCESS) {
  return CVI_FAILURE;
}

【相关主题】

CVI_RGN_Destroy

9.3.2. CVI_RGN_Destroy

【描述】

销毁一个区域

【语法】

CVI_S32 CVI_RGN_Destroy(RGN_HANDLE Handle);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

【举例】

参见 CVI_RGN_Create 举例

【相关主题】

CVI_RGN_Create

9.3.3. CVI_RGN_GetAttr

【描述】

获取区域属性

【语法】

CVI_S32 CVI_RGN_GetAttr(RGN_HANDLE Handle, RGN_ATTR_S *pstRegion);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstRegion

区域属性指针

输出

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

【举例】

参见 CVI_RGN_Create 举例

【相关主题】

CVI_RGN_SetAttr

9.3.4. CVI_RGN_SetAttr

【描述】

设置区域属性

【语法】

CVI_S32 CVI_RGN_SetAttr(RGN_HANDLE Handle, const RGN_ATTR_S *pstRegion);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstRegion

区域属性指针

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

  • 仅Overlay/OverlayEx支援此接口

【举例】

参见 CVI_RGN_Create 举例

【相关主题】

CVI_RGN_GetAttr

9.3.5. CVI_RGN_SetBitMap

【描述】

设置区域位图，将Bitmap填充到区域中。

【语法】

CVI_S32 CVI_RGN_SetBitMap(RGN_HANDLE Handle, const BITMAP_S *pstBitmap);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstBitmap

Bitmap属性指针可参考”系统控制”章节的 BITMAP_S

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

  • Bitmap必须小于等于区域的大小

  • Bitmap和区域的像素格式必须一致

  • 可多次调用

  • 只支援Overlay/OverlayEx

【举例】

无。

【相关主题】

无。

9.3.6. CVI_RGN_AttachToChn

【描述】

将区域叠加到通道上

【语法】

CVI_S32 CVI_RGN_AttachToChn(RGN_HANDLE Handle, const MMF_CHN_S *pstChn, const RGN_CHN_ATTR_S *pstChnAttr);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstChn

通道信息指针

输入

pstChnAttr

区域通道属性指针

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

  • 通道必须已经创建

【举例】

无。

【相关主题】

CVI_RGN_DetachFromChn

9.3.7. CVI_RGN_DetachFromChn

【描述】

将区域从通道中撤出

【语法】

CVI_S32 CVI_RGN_DetachFromChn(RGN_HANDLE Handle, const MMF_CHN_S *pstChn);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstChn

通道信息指针

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

【举例】

无。

【相关主题】

CVI_RGN_AttachToChn

9.3.8. CVI_RGN_SetDisplayAttr

【描述】

设置区域的通道显示属性

【语法】

CVI_S32 CVI_RGN_SetDisplayAttr(RGN_HANDLE Handle, const MMF_CHN_S *pstChn, const RGN_CHN_ATTR_S *pstChnAttr);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstChn

通道信息指针

输入

pstChnAttr

区域通道属性指针

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

  • 区域必须已经跟通道绑定

【举例】

无。

【相关主题】

CVI_RGN_GetDisplayAttr

9.3.9. CVI_RGN_GetDisplayAttr

【描述】

获取区域的通道显示属性

【语法】

CVI_S32 CVI_RGN_GetDisplayAttr(RGN_HANDLE Handle, const MMF_CHN_S *pstChn, RGN_CHN_ATTR_S *pstChnAttr);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstChn

通道信息指针

输入

pstChnAttr

区域通道属性指针

输出

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

  • 区域必须已经跟通道绑定

【举例】

无。

【相关主题】

CVI_RGN_SetDisplayAttr

9.3.10. CVI_RGN_GetCanvasInfo

【描述】

获取区域的画布信息

【语法】

CVI_S32 CVI_RGN_GetCanvasInfo(RGN_HANDLE Handle, RGN_CANVAS_INFO_S *pstCanvasInfo);

【参数】

参数名称 描述

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstCanvasInfo

区域画布信息指针

输出

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

  • 仅支援Overlay/OverlayEx

  • 此接口功能类似 CVI_RGN_SetBitMap ，主要差异在于 CVI_RGN_SetBitMap
    在更新画布的过程中，是直接作用在所绑定的通道上，并且会多一次内存拷贝。
    而此接口不会有以上问题，但需要两块画布(double buffer)来实现。

  • 此接口用于获取画布信息，之后用户可以直接对画布做操作，在完成更新之后，在调用进行 CVI_RGN_UpdateCanvas 更新(swap buffer)。

  • 在调用了此接口之后，未调用 CVI_RGN_UpdateCanvas 之前，不可调用 CVI_RGN_SetBitMap 。

【举例】

无。

【相关主题】

CVI_RGN_UpdateCanvas

9.3.11. CVI_RGN_UpdateCanvas

【描述】

更新区域的画布

【语法】

CVI_S32 CVI_RGN_UpdateCanvas(RGN_HANDLE Handle);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

  • 此接口是用以配合 CVI_RGN_GetCanvasInfo 使用。
    主要适用于画布内容更新之后，进行画布切换。
    如此可以避免画布更新过程中的瞬时。

  • 必须先获取画布信息，在对画布更新完成之后，在调用此接口进行更新。

  • 仅支援Overlay/OverlayEx

【举例】

无。

【相关主题】

CVI_RGN_GetCanvasInfo

9.3.12. CVI_RGN_SetChnPalette

【描述】

设置通道色盘信息

【语法】

CVI_S32 CVI_RGN_SetChnPalette(RGN_HANDLE Handle, const MMF_CHN_S *pstChn, RGN_PALETTE_S *pstPalette);

【参数】

参数名称

描述

输入/输出

Handle

区域号。

取值范围: [0, 0xFFFFFFFF]。

输入

pstChn

绑定通道号的信息

输入

pstPalette

色盘信息

输入

【返回值】

返回值

描述

0

成功。

非0

失败,请参见 错误码 。

【需求】

  • 头文件：cvi_comm_region.h、cvi_region.h

  • 库文件：librgn.a

【注意】

  • 区域必须已经创建

  • 仅支援Overlay/OverlayEx

【举例】

无。

【相关主题】

无。