9.3. API Reference

This function module provides the following APIs to users:

• CVI_RGN_Create: Create a Region.

• CVI_RGN_Destroy: Destroy a Region.

• CVI_RGN_GetAttr: GetRegionAttribute.

• CVI_RGN_SetAttr: SetRegionAttribute.

• CVI_RGN_SetBitMap: SetRegionbitsFigure.

• CVI_RGN_AttachToChn: willRegionoverlaytoChannelon.

• CVI_RGN_DetachFromChn: removes the region from the channel.

• CVI_RGN_SetDisplayAttr: SetRegionChannelDisplayAttribute.

• CVI_RGN_GetDisplayAttr: GetRegionChannelDisplayAttribute.

• CVI_RGN_GetCanvasInfo: Getregion canvasInformation.

• CVI_RGN_UpdateCanvas: moreregion canvasInformation.

• CVI_RGN_SetChnPalette: SetChannelpalette information.

9.3.1. CVI_RGN_Create

Description

Create a Region

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. mustisnotUseHandlenumber Value Range:[0, 0xFFFFFFFF].	Input
pstRegion	RegionAttributePointer.	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• HandlebyUserspecified, mustissinglenotcanrepeat.

• Not supportedrepeatCreate

• CreateOverlay/OverLayExwithoutsideRegiontime, only need tospecifiedRegion typethat iscan. otherInformation, isinCall CVI_RGN_AttachToChn timespecified.

Example

 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; } 

Related Topics

CVI_RGN_Destroy

9.3.2. CVI_RGN_Destroy

Description

Destroy a Region

Syntax

CVI_S32 CVI_RGN_Destroy(RGN_HANDLE Handle); 

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

Example

See CVI_RGN_Create Example

Related Topics

CVI_RGN_Create

9.3.3. CVI_RGN_GetAttr

Description

GetRegionAttribute

Syntax

CVI_S32 CVI_RGN_GetAttr(RGN_HANDLE Handle, RGN_ATTR_S *pstRegion); 

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstRegion	RegionAttributePointer	Output

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

Example

See CVI_RGN_Create Example

Related Topics

CVI_RGN_SetAttr

9.3.4. CVI_RGN_SetAttr

Description

SetRegionAttribute

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstRegion	RegionAttributePointer	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

• onlyOverlay/OverlayExthisInterface

Example

See CVI_RGN_Create Example

Related Topics

CVI_RGN_GetAttr

9.3.5. CVI_RGN_SetBitMap

Description

SetRegionbitsFigure, willBitmapfilltoRegionMedium.

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstBitmap	BitmapAttributePointercanReference”System Control”section BITMAP_S	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

• Bitmapmustless thanetc.toRegionSize

• BitmapandRegionPixel formatmustonecause

• canmultiplesecondaryCall

• onlyOverlay/OverlayEx

Example

None.

Related Topics

None.

9.3.6. CVI_RGN_AttachToChn

Description

willRegionoverlaytoChannelon

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstChn	ChannelInformationPointer	Input
pstChnAttr	RegionChannel attributesPointer	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

• Channelmust already be created

Example

None.

Related Topics

CVI_RGN_DetachFromChn

9.3.7. CVI_RGN_DetachFromChn

Description

removes the region from the channel

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstChn	ChannelInformationPointer	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

Example

None.

Related Topics

CVI_RGN_AttachToChn

9.3.8. CVI_RGN_SetDisplayAttr

Description

SetRegionChannelDisplayAttribute

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstChn	ChannelInformationPointer	Input
pstChnAttr	RegionChannel attributesPointer	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

• The region must already be bound to the channel

Example

None.

Related Topics

CVI_RGN_GetDisplayAttr

9.3.9. CVI_RGN_GetDisplayAttr

Description

GetRegionChannelDisplayAttribute

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstChn	ChannelInformationPointer	Input
pstChnAttr	RegionChannel attributesPointer	Output

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

• The region must already be bound to the channel

Example

None.

Related Topics

CVI_RGN_SetDisplayAttr

9.3.10. CVI_RGN_GetCanvasInfo

Description

Getregion canvasInformation

Syntax

CVI_S32 CVI_RGN_GetCanvasInfo(RGN_HANDLE Handle, RGN_CANVAS_INFO_S *pstCanvasInfo); 

Parameters

Parameter Name Description	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstCanvasInfo	region canvasInformationPointer	Output

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

• Supports Overlay/OverlayEx only

• thisInterfaceFunction CVI_RGN_SetBitMap, maininto CVI_RGN_SetBitMap

  inmoreprocessin, isconnectintheBindChannelon, andwillmultipleonesecondaryMemorycopy.

  whilethisInterfacenotwillhaswithon, butneed totwoblock(double buffer)toimplement.

• thisInterfaceused to GetInformation, ofafterUsercanconnectforperformoperation, incompletemoreafter that, inCallperform CVI_RGN_UpdateCanvas more(swap buffer).

• inCallthisInterfaceafter that, notCall CVI_RGN_UpdateCanvas before, notcanCall CVI_RGN_SetBitMap.

Example

None.

Related Topics

CVI_RGN_UpdateCanvas

9.3.11. CVI_RGN_UpdateCanvas

Description

moreregion canvas

Syntax

CVI_S32 CVI_RGN_UpdateCanvas(RGN_HANDLE Handle); 

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

• thisInterfaceiswithwork with CVI_RGN_GetCanvasInfo Use.

  mainused to canvas contentmoreafter that, perform canvas switch.

  ifthiscancanvas updateprocessintime.

• canvas information must be obtained first, inforcanvas updatecompleteafter that, inCallthisInterfaceperform more.

• Supports Overlay/OverlayEx only

Example

None.

Related Topics

CVI_RGN_GetCanvasInfo

9.3.12. CVI_RGN_SetChnPalette

Description

SetChannelpalette information

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Handle	Region number. Value range: [0, 0xFFFFFFFF].	Input
pstChn	BindChannel numberInformation	Input
pstPalette	palette information	Input

Return Value

Return Value	Description
0	Success.
Non-zero	Failure; see Error Codes.

Requirements

• Header files: cvi_comm_region.h, cvi_region.h

• Library files: librgn.a

Note

• The region must already be created

• Supports Overlay/OverlayEx only

Example

None.

Related Topics

None.