Region operations
[GDI functions]

Data Structures

Defines

Typedefs

Functions

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 */

Define 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 639 of file gdi.h.

#define CopyRegion   ClipRgnCopy

Is an alias of ClipRgnCopy.

See also:
ClipRgnCopy

Definition at line 992 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 666 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 653 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 626 of file gdi.h.

#define IntersectRegion   ClipRgnIntersect

Is an alias of ClipRgnIntersect.

See also:
ClipRgnIntersect

Definition at line 999 of file gdi.h.

#define UnionRectWithRegion   AddClipRect

Is an alias of AddClipRect.

See also:
AddClipRect

Definition at line 985 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 611 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
Generated on Thu Apr 7 16:01:47 2011 for MiniGUI V3.0.12 API Reference by  doxygen 1.6.3