GpiConvert

This function converts an array of coordinate pairs from one coordinate space to another.

Syntax

GpiConvert(hps, lSrc, lTarg, lCount, aptlPoints)

Parameters

hps (HPS) - input

Presentation-space handle.

lSrc (LONG) - input

Source coordinate space.

CVTC_WORLD - World coordinates

CVTC_MODEL - Model space

CVTC_DEFAULTPAGE - Page space before default viewing transform

CVTC_PAGE - Page space after default viewing transform

CVTC_DEVICE - Device space.

lTarg (LONG) - input

Target coordinate space.

CVTC_WORLD - World coordinates

CVTC_MODEL - Model space

CVTC_DEFAULTPAGE - Page space before default viewing transform

CVTC_PAGE - Page space after default viewing transform

CVTC_DEVICE - Device space.

lCount (LONG) - input

Number of coordinate pairs in aptlPoints. Must be greater or equal to 0.

aptlPoints (PPOINTL) - in/out

Array of coordinate pair structures.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE - Successful completion

FALSE - Error occurred.

Remarks

This function replaces each coordinate pair in aptlPoints with the converted values. Conversions involving either world coordinates or model space should not be performed if the drawing mode (see GpiSetDrawingMode) is retain.

Errors

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_COORDINATE (0x205B)

An invalid coordinate value was specified.

PMERR_INV_LENGTH_OR_COUNT (0x2092)

An invalid length or count parameter was specified.

PMERR_INV_COORD_SPACE (0x205A)

An invalid source or target coordinate space parameter was specified with GpiConvert.

PMERR_COORDINATE_OVERFLOW (0x2014)

An internal coordinate overflow error occurred. This can occur if coordinates or matrix transformation elements (or both) are invalid or too large.

Example Code

This example uses the GpiConvert function to convert the coordinates of the mouse pointer to the corresponding coordinates in world space. The system passes mouse coordinates to a window procedure in the WM_MOUSEMOVE message. The coordinates are device coordinates. After the coordinates are converted, the GpiMove uses them to move to a new location in world space.

#define INCL_GPITRANSFORMS /* GPI Transform functions */
#define INCL_GPIPRIMITIVES /* GPI primitive functions */
#include <os2.h>

MPARAM mp1;
HPS hps;
POINTL ptl;

case WM_MOUSEMOVE:
  ptl.x = (LONG) SHORT1FROMMP(mp1);
  ptl.y = (LONG) SHORT2FROMMP(mp1);
  GpiConvert(hps, CVTC_DEVICE, CVTC_WORLD, 1L, &ptl);
  GpiMove(hps, &ptl);

Related Functions

• GpiCreatePS
• GpiSetDefaultViewMatrix
• GpiSetModelTransformMatrix
• GpiSetPageViewport
• GpiSetSegmentTransformMatrix
• GpiSetViewingTransformMatrix