GpiPathToRegion

This function converts a path to a region.

Syntax

GpiPathToRegion(GpiH, lPath, lOptions);

Parameters

GpiH (HPS) - input

Presentation-space handle.

lPath (LONG) - input

Identifier of path to be converted; it must be 1.

lOptions (LONG) - input

Fill options.

This parameter can have one of the following values:

FPATH_ALTERNATE: Fills the path using the alternate rule; see GpiBeginArea. This is the default value.

FPATH_WINDING: Fills the path using the winding rule; see GpiBeginArea. This value must be selected if the path has been modified using GpiModifyPath.

Returns

hrgn (HRGN) - returns

Region handle.

<>0 - Region handle

RGN_ERROR - Error.

Possible returns from WinGetLastError

PMERR_INV_HPS (0x207F)

An invalid presentation-space handle was specified.

PMERR_PS_BUSY (0x20F4)

An attempt was made to access the presentation space from more than one thread simultaneously.

PMERR_INV_PATH_ID (0x20AE)

An invalid path identifier parameter was specified.

PMERR_PATH_UNKNOWN (0x20EE)

An attempt was made to perform a path function on a path that did not exist.

Calling Sequence

#define INCL_GPIPATHS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS     GpiH;      /*  Presentation-space handle. */
LONG    lPath;     /*  Identifier of path to be converted; it must be 1. */
LONG    lOptions;  /*  Fill options. */
HRGN    hrgn;      /*  Region handle. */

hrgn = GpiPathToRegion(GpiH, lPath, lOptions);

Example Source Code

This example uses GpiPathToRegion to convert a path (a triangle) to a region using the winding rule to fill the region.

#define INCL_GPIPATHS           /* Path functions               */
#include <os2.h>

HRGN   hrgn;            /* handle for region                    */
HPS    hps;             /* Presentation-space handle            */
POINTL ptlStart = { 0, 0 }; /* first vertex                     */
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices  */

GpiBeginPath(hps, 1L);                 /* start the path bracket */
GpiMove(hps, &ptlStart);               /* move to starting point */
GpiPolyLine(hps, 2L, ptlTriangle);     /* draw the three sides   */
GpiCloseFigure(hps);                   /* close the triangle     */
GpiEndPath(hps);                       /* end the path bracket   */

hrgn = GpiPathToRegion(hps, 1L, FPATH_WINDING);

Remarks

This function converts a path (originally defined by a series of GPI drawing calls) to a region. The new region can be operated on by the GPI region calls; in particular GpiCombineRegion can be used to combine it with another region.

This function should not be used in retain or draw-and-retain modes because it does not cause graphics orders to be added to the current segment.

Any open figures within the path are closed automatically.

The boundaries of the area defined by the path are considered to be part of the interior, so that a point on the boundary is included in the new region.

After a path is converted to a region, it no longer exists as a path. The path cannot be reused for any other purpose.

Related Functions

• GpiBeginPath
• GpiCombineRegion
• GpiEndPath
• GpiFillPath
• GpiModifyPath
• GpiOutlinePath
• GpiSetClipPath
• GpiStrokePath