GDI Region Functions

This section provides information on the functions used to create, manipulate, and query GDI regions. Regions are a powerful graphics primitive that define an arbitrary area on the screen. They can be used for clipping, hit testing, and complex drawing operations.

What is a Region?

A GDI region is an object that represents a specific area. This area can be composed of rectangles, paths, or a combination of both. Regions are defined by a set of boundaries and can be used to:

Clipping: Restrict drawing operations to a specific area.
Hit Testing: Determine if a point or rectangle intersects with a defined area.
Area Manipulation: Combine, subtract, or intersect regions to create complex shapes.
Filling: Fill the defined area with a specified brush or pattern.

Region Data Structures

The primary structure associated with regions is the RGNDATA structure, which contains information about the region's bounding rectangle and the data defining its shape.

Common Region Functions

The following table lists some of the most commonly used GDI region functions:

Function	Description
`CreateRectRgn`	Creates a GDI region that consists of a rectangle.
`CreatePolygonRgn`	Creates a GDI region that consists of a polygon.
`CreatePathRgn`	Creates a GDI region from the current path.
`CombineRgn`	Combines two regions into a third region.
`GetRegionData`	Retrieves the region data.
`PtInRegion`	Determines whether a point is within a region.
`RectInRegion`	Determines whether a rectangle intersects with a region.
`DeleteObject`	Deletes a GDI region object.

`CreateRectRgn`

Creates a GDI region that consists of a rectangle.

Parameters

(int x1, int y1, int x2, int y2): Specifies the coordinates of the upper-left and lower-right corners of the rectangle, in logical units.

Return Value

A handle (HRGN) to the newly created region.
NULL if an error occurs.

Remarks

The coordinates (x1, y1) define the upper-left corner, and (x2, y2) define the lower-right corner of the rectangle.
The region created is independent of the GDI mapping modes.
Always delete region objects when you are finished with them by calling DeleteObject.

Note: The coordinates are inclusive of the bounding rectangle.

`CreatePolygonRgn`

Creates a GDI region that consists of a polygon defined by an array of points.

Parameters

(LPPOINT lpPoints, int nCount, int fnFillMode):
- lpPoints: Pointer to an array of POINT structures that specify the vertices of the polygon.
- nCount: The number of points in the array.
- fnFillMode: The fill mode for the polygon. Can be ALTERNATE or WINDING.

Return Value

A handle (HRGN) to the newly created region.
NULL if an error occurs.

Remarks

The fnFillMode parameter determines how the interior of the polygon is determined.
The polygon is implicitly closed by connecting the last point to the first point.

`CreatePathRgn`

Creates a GDI region from the current path constructed using the path-drawing functions.

Parameters

(int nMode): Specifies how the path data is to be converted into a region. Can be RGN_FORMAT (not recommended) or RGN_COPY. Use RGN_COPY to create a copy of the path.

Return Value

A handle (HRGN) to the newly created region.
NULL if an error occurs.

Remarks

This function should be called after constructing a path using functions like BeginPath, MoveToEx, LineTo, PolylineTo, ArcTo, etc., and before calling EndPath.

`CombineRgn`

Combines two regions into a third region. The operation can be an intersection, union, difference, or symmetrical difference.

Parameters

(HRGN hRgnDest, HRGN hRgnSrc1, HRGN hRgnSrc2, int fnCombine):
- hRgnDest: Handle to the destination region. This region will be modified to contain the result of the combination.
- hRgnSrc1: Handle to the first source region.
- hRgnSrc2: Handle to the second source region.
- fnCombine: Specifies the operation to be performed. Common values include:
  - RGN_AND (Intersection)
  - RGN_OR (Union)
  - RGN_XOR (Symmetrical Difference)
  - RGN_DIFF (Difference: Region 1 - Region 2)
  - RGN_MIN (Minimum rectangle)
  - RGN_MAX (Maximum rectangle)

Return Value

Specifies the combined region's complexity. Can be NULLREGION, SIMPLEREGION, or COMPLEXREGION.
0 if an error occurs.

`GetRegionData`

Retrieves the dimensions and structure of a region. This function returns the region's data in a buffer.

Parameters

(HRGN hRgn, DWORD dwCount, LPRGNDATA lpRgnData):
- hRgn: Handle to the region.
- dwCount: The size, in bytes, of the buffer pointed to by lpRgnData.
- lpRgnData: Pointer to a RGNDATA structure that receives the region data. If this parameter is NULL, the function returns the required buffer size.

Return Value

If lpRgnData is not NULL, the return value is the number of bytes copied to the buffer, or 0 if an error occurs.
If lpRgnData is NULL, the return value is the number of bytes required for the buffer, or 0 if an error occurs.

`PtInRegion`

Determines whether a specified point lies within a region.

Parameters

(HRGN hRgn, int x, int y):
- hRgn: Handle to the region.
- x: The x-coordinate of the point.
- y: The y-coordinate of the point.

Return Value

Nonzero if the point is in the region; otherwise, 0.

`RectInRegion`

Determines whether any part of a specified rectangle lies within a region.

Parameters

(HRGN hRgn, const RECT *lprc):
- hRgn: Handle to the region.
- lprc: Pointer to a RECT structure that specifies the rectangle's coordinates.

Return Value

Nonzero if any part of the rectangle is within the region; otherwise, 0.

`DeleteObject`

Deletes a specified logical pen, brush, font, bitmap, region, or color palette. After the object is deleted, the handle to it is no longer valid.

Parameters

(HGDIOBJ hObject): Handle to the GDI object to be deleted.

Return Value

Nonzero if the object was successfully deleted; otherwise, 0.

Remarks

You must delete GDI objects created by your application when they are no longer needed to free system resources.
For regions, this function should be called with an HRGN handle.