GpiPathToRegion
This function converts a path to a region.
Contents
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