View source for 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.

<pre>
#define INCL_GPITRANSFORMS /* GPI Transform functions */
#define INCL_GPIPRIMITIVES /* GPI primitive functions */
#include &lt;os2.h&gt;

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);
</pre>


==Related Functions==
* [[GpiCreatePS]]
* [[GpiSetDefaultViewMatrix]]
* [[GpiSetModelTransformMatrix]]
* [[GpiSetPageViewport]]
* [[GpiSetSegmentTransformMatrix]]
* [[GpiSetViewingTransformMatrix]]

[[Category:Gpi]]