GpiConvertWithMatrix

This function converts an array of (x,y) coordinate pairs from one coordinate space to another, using the supplied transform matrix.

Syntax

GpiConvertWithMatrix(hps, lCountp, aptlPoints, lCount, pmatlfArray);

Parameters

hps (HPS) - input

Presentation-space handle.

lCountp (LONG) - input

Point count.

Number of coordinate pairs in aptlPoints.

aptlPoints (PPOINTL) - in/out

Array of (x,y) coordinate pair structures.

lCount (LONG) - input

Number of elements.

The number of elements of pmatlfArray to be examined, starting from the beginning of the structure. If lCount is less or equal to 9, remaining elements default to the corresponding elements of the identity matrix. If lCount = 0, the identity matrix is used.

pmatlfArray (PMATRIXLF) - input

Instance transform matrix.

The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE

Successful completion

FALSE

Error occurred.

Remarks

The array contains x1, y1, x2, y2,.... The input coordinates are replaced by the converted coordinates. Only the supplied transform matrix is used, all other current transforms are ignored by this function. The transform is specified as a one-dimensional array of elements, being the first lCount elements of a 3-row by 3-column matrix ordered by rows. The order of the elements is:

Matrix             Array
┌       ┐
│ a b 0 │
│ c d 0 │         (a,b,0,c,d,0,e,f,1)
│ e f 1 │
└       ┘

A point with coordinates (x,y) is transformed to the point $$(a*x + c*y + e, b*x + d*y + f)$$

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_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

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

HPS          hps;          /*  Presentation-space handle. */
LONG         lCountp;      /*  Point count. */
PPOINTL      aptlPoints;   /*  Array of (x,y) coordinate pair structures. */
LONG         lCount;       /*  Number of elements. */
PMATRIXLF    pmatlfArray;  /*  Instance transform matrix. */
BOOL         rc;           /*  Success indicator. */

rc = GpiConvertWithMatrix(hps, lCountp, aptlPoints,
       lCount, pmatlfArray);

This example uses GpiConvertWithMatrix to convert two coordinate pairs to another coordinate space defined by the supplied matrix, which has only the first transform element defined.

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

BOOL  fSuccess;         /* success indicator                    */
HPS  hps;               /* Presentation-space handle            */
LONG  lCountp;          /* Point count                          */
POINTL  aptlPoints[2] = {{0L,0L},{1L,1L}};
                        /* Array of (x,y) coordinate pair
                           structures                           */
LONG  lCount;           /* Number of elements                   */
MATRIXLF  pmatlfArray;  /* Instance transform matrix            */

lCount = 1; /* examine only first element of transform matrix */

pmatlfArray.fxM11 = 2; /* set first element of transform matrix */

fSuccess = GpiConvertWithMatrix(hps, lCountp, aptlPoints,
                                lCount, &pmatlfArray);