Data Structures
struct	_CLIPRECT

struct	_CLIPRGN

Macros
#define	InitFreeClipRectList(heap, size) InitBlockDataHeap (heap, sizeof (CLIPRECT), size)
	Initializes the private block data heap used to allocate clipping rectangles. More...

#define	ClipRectAlloc(heap) BlockDataAlloc (heap)
	Allocates a clipping rectangles from the private block data heap. More...

#define	FreeClipRect(heap, cr) BlockDataFree (heap, cr);
	Frees a clipping rectangle which is allocated from the private block data heap. More...

#define	DestroyFreeClipRectList(heap) DestroyBlockDataHeap (heap);
	Destroys the private block data heap used to allocate clipping rectangles. More...

#define	UnionRectWithRegion AddClipRect
	Is an alias of AddClipRect. More...

#define	CopyRegion ClipRgnCopy
	Is an alias of ClipRgnCopy. More...

#define	IntersectRegion ClipRgnIntersect
	Is an alias of ClipRgnIntersect. More...

Typedefs
typedef struct _CLIPRECT	CLIPRECT

typedef struct _CLIPRGN	CLIPRGN

typedef CLIPRGN *	PCLIPRGN
	Data type of the pointer to a CLIPRGN. More...

Functions
MG_EXPORT void GUIAPI	InitClipRgn (PCLIPRGN pRgn, PBLOCKHEAP pFreeList)
	Initializes a clipping region. More...

MG_EXPORT void GUIAPI	EmptyClipRgn (PCLIPRGN pRgn)
	Empties a clipping region. More...

MG_EXPORT PCLIPRGN GUIAPI	CreateClipRgn (void)
	Creates a clipping region. More...

MG_EXPORT void GUIAPI	DestroyClipRgn (PCLIPRGN pRgn)
	Empties and destroys a clipping region. More...

MG_EXPORT BOOL GUIAPI	ClipRgnCopy (PCLIPRGN pDstRgn, const CLIPRGN *pSrcRgn)
	Copies one region to another. More...

MG_EXPORT BOOL GUIAPI	ClipRgnIntersect (PCLIPRGN pRstRgn, const CLIPRGN pRgn1, const CLIPRGN pRgn2)
	Intersects two region. More...

MG_EXPORT void GUIAPI	GetClipRgnBoundRect (PCLIPRGN pRgn, PRECT pRect)
	Gets the bounding rectangle of a region. More...

MG_EXPORT BOOL GUIAPI	SetClipRgn (PCLIPRGN pRgn, const RECT *pRect)
	Sets a region to contain only one rect. More...

MG_EXPORT BOOL GUIAPI	IsEmptyClipRgn (const CLIPRGN *pRgn)
	Determines whether a region is an empty region. More...

MG_EXPORT BOOL GUIAPI	AddClipRect (PCLIPRGN pRgn, const RECT *pRect)
	Unions one rectangle to a region. More...

MG_EXPORT BOOL GUIAPI	IntersectClipRect (PCLIPRGN pRgn, const RECT *pRect)
	Intersects a rectangle with a region. More...

MG_EXPORT BOOL GUIAPI	SubtractClipRect (PCLIPRGN pRgn, const RECT *pRect)
	Subtracts a rectangle from a region. More...

MG_EXPORT BOOL GUIAPI	PtInRegion (PCLIPRGN region, int x, int y)
	Determines whether a point is in a region. More...

MG_EXPORT BOOL GUIAPI	RectInRegion (PCLIPRGN region, const RECT *rect)
	Determines whether a rectangle is intersected with a region. More...

MG_EXPORT void GUIAPI	OffsetRegionEx (PCLIPRGN region, const RECT rcClient, const RECT rcScroll, int x, int y)
	Offsets the region in the specified window's scroll area. More...

MG_EXPORT void GUIAPI	OffsetRegion (PCLIPRGN region, int x, int y)
	Offsets the region. More...

MG_EXPORT BOOL GUIAPI	UnionRegion (PCLIPRGN dst, const CLIPRGN src1, const CLIPRGN src2)
	Unions two regions. More...

MG_EXPORT BOOL GUIAPI	SubtractRegion (CLIPRGN rgnD, const CLIPRGN rgnM, const CLIPRGN *rgnS)
	Substrcts a region from another. More...

MG_EXPORT BOOL GUIAPI	XorRegion (CLIPRGN dst, const CLIPRGN src1, const CLIPRGN *src2)
	Does the XOR operation between two regions. More...

MG_EXPORT BOOL GUIAPI	InitCircleRegion (PCLIPRGN dst, int x, int y, int r)
	Initializes a region to be an enclosed circle. More...

MG_EXPORT BOOL GUIAPI	InitEllipseRegion (PCLIPRGN dst, int x, int y, int rx, int ry)
	Initializes a region to be an enclosed ellipse. More...

MG_EXPORT BOOL GUIAPI	InitPolygonRegion (PCLIPRGN dst, const POINT *pts, int vertices)
	Initializes a region to be an enclosed polygon. More...

Detailed Description

A Region is simply an area, as the name implies, and is implemented as a "y-x-banded" array of rectangles. To explain: Each Region is made up of a certain number of rectangles sorted by y coordinate first, and then by x coordinate.

Furthermore, the rectangles are banded such that every rectangle with a given upper-left y coordinate (y1) will have the same lower-right y coordinate (y2) and vice versa. If a rectangle has scanlines in a band, it will span the entire vertical distance of the band. This means that some areas that could be merged into a taller rectangle will be represented as several shorter rectangles to account for shorter rectangles to its left or right but within its "vertical scope".

An added constraint on the rectangles is that they must cover as much horizontal area as possible. E.g. no two rectangles in a band are allowed to touch.

Whenever possible, bands will be merged together to cover a greater vertical distance (and thus reduce the number of rectangles). Two bands can be merged only if the bottom of one touches the top of the other and they have rectangles in the same places (of the same width, of course). This maintains the y-x-banding that's so nice to have...

Example:

#ifdef _USE_NEWGAL
static BLOCKHEAP my_cliprc_heap;
static BOOL ch_inited = FALSE;
static void GDIDemo_Region (HWND hWnd, HDC hdc)
{
    CLIPRGN my_cliprgn1;
    CLIPRGN my_cliprgn2;
    if (!ch_inited) {
        /* Init the heap used by our region. */
        InitFreeClipRectList (&my_cliprc_heap, 100);
        ch_inited = TRUE;
    }
    InitClipRgn (&my_cliprgn1, &my_cliprc_heap);
    InitClipRgn (&my_cliprgn2, &my_cliprc_heap);
    /* Create one circle region. */
    InitCircleRegion (&my_cliprgn1, 100, 100, 60);
    /* Create one ellipse region. */
    InitEllipseRegion (&my_cliprgn2, 100, 100, 50, 70);
    /* Fill a box to earase the background. */
    SetBrushColor (hdc, PIXEL_blue);
    FillBox (hdc, 0, 0, DEFAULT_WIDTH, 200);
    /* Get the difference between two regions. */
    SubtractRegion (&my_cliprgn1, &my_cliprgn1, &my_cliprgn2);
    /* Select the difference region as the current visible region of DC. */
    SelectClipRegion (hdc, &my_cliprgn1);
    /* Fill a box, but you will only see red color in the different region. */
    SetBrushColor (hdc, PIXEL_red);
    FillBox (hdc, 0, 0, 180, 200);
    /* Do more with XorRegion. */
    InitCircleRegion (&my_cliprgn1, 300, 100, 60);
    OffsetRegion (&my_cliprgn2, 200, 0);
    XorRegion (&my_cliprgn1, &my_cliprgn1, &my_cliprgn2);
    SelectClipRegion (hdc, &my_cliprgn1);
    FillBox (hdc, 200, 0, 180, 200);
    /* Do more with IntersectRegion. */
    InitCircleRegion (&my_cliprgn1, 500, 100, 60);
    OffsetRegion (&my_cliprgn2, 200, 0);
    IntersectRegion (&my_cliprgn1, &my_cliprgn1, &my_cliprgn2);
    SelectClipRegion (hdc, &my_cliprgn1);
    FillBox (hdc, 400, 0, 180, 200);
    /* 
     * Empty two clipping region to free the clipping rectangles used 
     * by them.
     */
    EmptyClipRgn (&my_cliprgn1);
    EmptyClipRgn (&my_cliprgn2);
    /* 
     * You should not forget to destroy the FreeClipRectList in your 
     * applications.
     * Here we do not destroy the heap because we will use it in next call.
     *
     * DestroyFreeClipRectList (&my_cliprc_heap);
     * ch_inited = FALSE;
     *
     */
}
#endif /* _USE_NEWGAL */

Macro Definition Documentation

#define ClipRectAlloc ( heap ) BlockDataAlloc (heap)

Allocates a clipping rectangles from the private block data heap.

Parameters

heap	The pointer to the initialized BLOCKHEAP structure.

Note: This macro is defined to call BlockDataAlloc function.

See also: BlockDataAlloc

Definition at line 660 of file gdi.h.

#define CopyRegion ClipRgnCopy

Is an alias of ClipRgnCopy.

See also: ClipRgnCopy

Definition at line 1013 of file gdi.h.

#define DestroyFreeClipRectList ( heap ) DestroyBlockDataHeap (heap);

Destroys the private block data heap used to allocate clipping rectangles.

Parameters

heap	The pointer to the BLOCKHEAP structure.

Note: This macro is defined to call DestroyBlockDataHeap function.

See also: DestroyBlockDataHeap

Definition at line 687 of file gdi.h.

#define FreeClipRect	(	heap,
		cr
	)	BlockDataFree (heap, cr);

Frees a clipping rectangle which is allocated from the private block data heap.

Parameters

heap	The pointer to the initialized BLOCKHEAP structure.
cr	The pointer to the clipping rectangle to be freed.

Note: This macro is defined to call BlockDataFree function.

See also: BlockDataFree

Definition at line 674 of file gdi.h.

#define InitFreeClipRectList	(	heap,
		size
	)	InitBlockDataHeap (heap, sizeof (CLIPRECT), size)

Initializes the private block data heap used to allocate clipping rectangles.

Parameters

heap	The pointer to a BLOCKHEAP structure.
size	The size of the heap.

Note: This macro is defined to call InitBlockDataHeap function with bd_size set to sizeof(CLIPRECT).

See also: InitBlockDataHeap

Definition at line 647 of file gdi.h.

#define IntersectRegion ClipRgnIntersect

Is an alias of ClipRgnIntersect.

See also: ClipRgnIntersect

Definition at line 1020 of file gdi.h.

#define UnionRectWithRegion AddClipRect

Is an alias of AddClipRect.

See also: AddClipRect

Definition at line 1006 of file gdi.h.

Typedef Documentation

typedef struct _CLIPRECT CLIPRECT

Clipping rectangle structure.

typedef struct _CLIPRGN CLIPRGN

Clipping region structure, alos used for general regions.

typedef CLIPRGN * PCLIPRGN

Data type of the pointer to a CLIPRGN.

See also: CLIPRGN

Definition at line 632 of file gdi.h.

Function Documentation

BOOL GUIAPI AddClipRect	(	PCLIPRGN	pRgn,
		const RECT *	pRect
	)

Unions one rectangle to a region.

This function unions a rectangle to the region pointed to by pRgn.

Parameters

pRgn	The pointer to the region.
pRect	The pointer to the rectangle.

Returns: TRUE on success, otherwise FALSE.

See also: IntersectClipRect, SubtractClipRect

BOOL GUIAPI ClipRgnCopy	(	PCLIPRGN	pDstRgn,
		const CLIPRGN *	pSrcRgn
	)

Copies one region to another.

This function copies the region pointed to by pSrcRgn to the region pointed to by pDstRgn.

Parameters

pDstRgn	The destination region.
pSrcRgn	The source region.

Returns: TRUE on success, otherwise FALSE.

Note: This function will empty the region pDstRgn first.

See also: EmptyClipRgn, ClipRgnIntersect, UnionRegion, SubtractRegion, XorRegion

BOOL GUIAPI ClipRgnIntersect	(	PCLIPRGN	pRstRgn,
		const CLIPRGN *	pRgn1,
		const CLIPRGN *	pRgn2
	)

Intersects two region.

This function gets the intersection of two regions pointed to by pRgn1 and pRgn2 respectively and puts the result to the region pointed to by pRstRgn.

Parameters

pRstRgn	The intersected result region.
pRgn1	The first region.
pRgn2	The second region.

Returns: TRUE on success, otherwise FALSE.

Note: If pRgn1 does not intersected with pRgn2, the result region will be a emgty region.

See also: EmptyClipRgn, ClipRgnCopy, UnionRegion, SubtractRegion, XorRegion

PCLIPRGN GUIAPI CreateClipRgn ( void )

Creates a clipping region.

Returns: The pointer to the clip region.

See also: InitClipRgn, EmptyClipRgn, DestroyClipRgn.

void GUIAPI DestroyClipRgn ( PCLIPRGN pRgn )

Empties and destroys a clipping region.

This function empties and destroys a clipping region pointed to by pRgn.

Parameters

pRgn	The pointer to the region.

See also: InitClipRgn, CreateClipRgn

void GUIAPI EmptyClipRgn ( PCLIPRGN pRgn )

Empties a clipping region.

This function empties a clipping region pointed to by pRgn.

Parameters

pRgn	The pointer to the region.

See also: InitClipRgn

void GUIAPI GetClipRgnBoundRect	(	PCLIPRGN	pRgn,
		PRECT	pRect
	)

Gets the bounding rectangle of a region.

This function gets the bounding rect of the region pointed to by pRgn, and returns the rect in the rect pointed to by pRect.

Parameters

pRgn	The pointer to the region.
pRect	The pointer to the result rect.

See also: IsEmptyClipRgn

BOOL GUIAPI InitCircleRegion	(	PCLIPRGN	dst,
		int	x,
		int	y,
		int	r
	)

Initializes a region to be an enclosed circle.

Parameters

dst	The pointer to the region to be initialized.
x	x,y: The center of the circle.
y	x,y: The center of the circle.
r	The radius of the circle.

Returns: TRUE on success, otherwise FALSE.

See also: InitEllipseRegion, InitPolygonRegion

void GUIAPI InitClipRgn	(	PCLIPRGN	pRgn,
		PBLOCKHEAP	pFreeList
	)

Initializes a clipping region.

Before intializing a clipping region, you should initialize a private block data heap first. The region operations, such as UnionRegion function, will allocate/free the clipping rectangles from/to the heap. This function will set the heap field of pRgn to be pFreeList, and empty the region.

Parameters

pRgn	The pointer to the CLIPRGN structure to be initialized.
pFreeList	The pointer to the initialized private block data heap.

See also: InitFreeClipRectList, EmptyClipRgn.

Example:

static BLOCKHEAP sg_MyFreeClipRectList;
...
    CLIPRGN my_region
    InitFreeClipRectList (&sg_MyFreeClipRectList, 20);
    InitClipRgn (&my_regioni, &sg_MyFreeClipRectList);

BOOL GUIAPI InitEllipseRegion	(	PCLIPRGN	dst,
		int	x,
		int	y,
		int	rx,
		int	ry
	)

Initializes a region to be an enclosed ellipse.

Parameters

dst	The pointer to the region to be initialized.
x	x,y: The center of the ellipse.
y	x,y: The center of the ellipse.
rx	The x-radius of the ellipse.
ry	The y-radius of the ellipse.

Returns: TRUE on success, otherwise FALSE.

See also: InitCircleRegion, InitPolygonRegion

BOOL GUIAPI InitPolygonRegion	(	PCLIPRGN	dst,
		const POINT *	pts,
		int	vertices
	)

Initializes a region to be an enclosed polygon.

Parameters

dst	The pointer to the region to be initialized.
pts	The vertex array of the polygon.
vertices	The number of the vertices.

Returns: TRUE on success, otherwise FALSE.

See also: InitCircleRegion, InitEllipseRegion

BOOL GUIAPI IntersectClipRect	(	PCLIPRGN	pRgn,
		const RECT *	pRect
	)

Intersects a rectangle with a region.

This function intersects the region pointed to by pRgn with a rect pointed to by pRect.

Parameters

pRgn	The pointer to the region.
pRect	The pointer to the rectangle.

Returns: TRUE on success, otherwise FALSE.

See also: AddClipRect, SubtractClipRect

BOOL GUIAPI IsEmptyClipRgn ( const CLIPRGN * pRgn )

Determines whether a region is an empty region.

This function determines whether the region pointed to by pRgn is an empty region.

Parameters

pRgn	The pointer to the region.

Returns: TRUE for empty one, else for not empty region.

See also: EmptyClipRgn

void GUIAPI OffsetRegion	(	PCLIPRGN	region,
		int	x,
		int	y
	)

Offsets the region.

This function offsets a given region pointed to by region.

Parameters

region	The pointer to the region.
x	x,y: Offsets on x and y coodinates.
y	x,y: Offsets on x and y coodinates.

void GUIAPI OffsetRegionEx	(	PCLIPRGN	region,
		const RECT *	rcClient,
		const RECT *	rcScroll,
		int	x,
		int	y
	)

Offsets the region in the specified window's scroll area.

This function offsets a given region pointed to by region in the specified window's scroll area.

Parameters

region	The pointer to the region.
rcClient	The client area which the region belongs to.
rcScroll	The rectangle of the area in which the region will be offset.
x	x,y: Offsets on x and y coodinates.
y	x,y: Offsets on x and y coodinates.

BOOL GUIAPI PtInRegion	(	PCLIPRGN	region,
		int	x,
		int	y
	)

Determines whether a point is in a region.

This function determines whether a point (x,y) is in the region pointed to by region.

Parameters

region	The pointer to the region.
x	x,y: The point.
y	x,y: The point.

Returns: TRUE for in the region, otherwise FALSE.

See also: RectInRegion

BOOL GUIAPI RectInRegion	(	PCLIPRGN	region,
		const RECT *	rect
	)

Determines whether a rectangle is intersected with a region.

This function determines whether the rect rect is intersected with the region pointed to by region.

Parameters

region	The pointer to the region.
rect	The pointer to the rect.

Returns: TRUE for in the region, otherwise FALSE.

See also: PtInRegion

BOOL GUIAPI SetClipRgn	(	PCLIPRGN	pRgn,
		const RECT *	pRect
	)

Sets a region to contain only one rect.

This function sets the region pRgn to contain only a rect pointed to by pRect.

Parameters

pRgn	The pointer to the region.
pRect	The pointer to the rect.

Returns: TRUE on success, otherwise FALSE.

Note: This function will empty the region pRgn first.

See also: EmptyClipRgn

BOOL GUIAPI SubtractClipRect	(	PCLIPRGN	pRgn,
		const RECT *	pRect
	)

Subtracts a rectangle from a region.

This function subtracts a rect pointed to by pRect from the region pointed to by pRgn.

Parameters

pRgn	The pointer to the region.
pRect	The pointer to the rect.

Returns: TRUE on success, otherwise FALSE.

See also: AddClipRect, IntersectClipRect

BOOL GUIAPI SubtractRegion	(	CLIPRGN *	rgnD,
		const CLIPRGN *	rgnM,
		const CLIPRGN *	rgnS
	)

Substrcts a region from another.

This function subtracts rgnS from rgnM and leave the result in rgnD.

Parameters

rgnD	The pointer to the difference region.
rgnM	The pointer to the minuend region.
rgnS	The pointer to the subtrahend region.

Returns: TRUE on success, otherwise FALSE.

See also: UnionRegion, XorRegion

BOOL GUIAPI UnionRegion	(	PCLIPRGN	dst,
		const CLIPRGN *	src1,
		const CLIPRGN *	src2
	)

Unions two regions.

This function unions two regions pointed to by src1 and src2 respectively and puts the result to the region pointed to by dst.

Parameters

dst	The pointer to the result region.
src1	src1,src2: Two regions will be unioned.
src2	src1,src2: Two regions will be unioned.

Returns: TRUE on success, otherwise FALSE.

See also: SubtractRegion, XorRegion

BOOL GUIAPI XorRegion	(	CLIPRGN *	dst,
		const CLIPRGN *	src1,
		const CLIPRGN *	src2
	)

Does the XOR operation between two regions.

This function does the XOR operation between two regions pointed to by src1 and src2 and puts the result to the region pointed to by dst.

Parameters

dst	The pointer to the result region.
src1	src1,src2: Two regions will be xor'ed.
src2	src1,src2: Two regions will be xor'ed.

Returns: TRUE on success, otherwise FALSE.

See also: UnionRegion, SubtractRegion

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation