CreatePolyPolygonRgn

3.0

HRGN CreatePolyPolygonRgn(lppt, lpnPolyCount, cIntegers, fnPolyFillMode)
const POINT FAR* lppt;	/* address of structure of points	*/
const int FAR* lpnPolyCount;	/* address of array of vertex data	*/
int cIntegers;	/* number of integers in array	*/
int fnPolyFillMode;	/* polygon-filling mode	*/

The CreatePolyPolygonRgn function creates a region consisting of a series of closed polygons. The polygons may be disjoint, or they may overlap.

Parameters

lppt

Points to an array of POINT structures that define the vertices of the polygons. Each polygon must be explicitly closed, because the system does not close them automatically. The polygons are specified consecutively. The POINT structure has the following form:

typedef struct tagPOINT {   /* pt */
   int x;
   int y;
} POINT;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

lpnPolyCount

Points to an array of integers. The first integer specifies the number of vertices in the first polygon in the array pointed to by the lppt parameter, the second integer specifies the number of vertices in the second polygon, and so on.

cIntegers

Specifies the total number of integers in the array pointed to by the lpnPolyCount parameter.

fnPolyFillMode

Specifies the polygon-filling mode. This value may be either ALTERNATE or WINDING.

Return Value

The return value is the handle of the region if the function is successful. Otherwise, it is NULL.

Comments

The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.

When the polygon-filling mode is ALTERNATE, the system fills the area between odd-numbered and even-numbered polygon sides on each scan line. That is, the system fills the area between the first and second side, between the third and fourth side, and so on.

When the polygon-filling mode is WINDING, the system uses the direction in which a figure was drawn to determine whether to fill an area. Each line segment in a polygon is drawn in either a clockwise or a counterclockwise direction. Whenever an imaginary line drawn from an enclosed area to the outside of a figure passes through a clockwise line segment, the system increments a count (increases it by one); when the line passes through a counterclockwise line segment, the system decrements the count. The area is filled if the count is nonzero when the line reaches the outside of the figure.

When it has finished using a region created by CreatePolyPolygonRgn, an application should remove the region by using the DeleteObject function.

Example

The following example fills an array of POINT structures with the coordinates of a five-pointed star and a rectangle, uses this array in a call to the CreatePolyPolygonRgn function, selects the region into a device context, and then uses the PaintRgn function to display the region:

HDC hdc;
HRGN hrgn;
int aVertices[2] = { 6, 5 };
POINT apts[11] = {{ 200, 10  },
                  { 300, 200 },
                  { 100, 100 }, /* Star figure, manually closed */
                  { 300, 100 },
                  { 100, 200 },
                  { 200, 10  },

                  {  10, 150 },
                  { 350, 150 },
                  { 350, 170 }, /* Rectangle, manually closed */
                  {  10, 170 },
                  {  10, 150 }};

hrgn = CreatePolyPolygonRgn(apts,    /* array of points          */
    aVertices,                       /* array of vertices        */
    sizeof(aVertices) / sizeof(int), /* integers in vertex array */
    ALTERNATE);                      /* alternate mode           */
SelectObject(hdc, hrgn);
PaintRgn(hdc, hrgn);