GpiTranslate

This function applies a translation to a transform matrix.

Syntax

GpiTranslate (hps, pmatlfArray, lOptions, pptlTranslation)

Parameters

hps (HPS) - input

Presentation-space handle.

pmatlfArray (PMATRIXLF) - in/out

Transform matrix.

The elements of the transform, in row order. The first, second, fourth, and fifth elements are of type FIXED, and have an assumed binary point between the second and third bytes. Thus a value of 1.0 is represented by 65 536. Other elements are normal signed integers. The third, sixth, and ninth elements must be 0, 0, and 1, respectively.

lOptions (LONG) - input

Transform options.

Specifies how the transform defined by the specified translation should be used to modify the previous transform specified by the pmatlfArray parameter. Possible values are:

TRANSFORM_REPLACE - The previous transform is discarded and replaced by the transform describing the specified translation.

TRANSFORM_ADD - The previous transform is combined with a transform representing the specified translation in the order (1) previous transform, (2) translational transform. This option is most useful for incremental updates to transforms.

pptlTranslation (PPOINTL) - input

Translation.

The coordinates of a point, relative to the origin, which defines the required translation.

Return Code

rc (BOOL) - returns

Success indicator.

TRUE Successful completion

FALSE Error occurred.

Errors

Possible returns from WinGetLastError:

PMERR_INV_TRANSFORM_TYPE (0x20D0) : An invalid options parameter was specified with a transform matrix function.

Remarks

This function is a helper function which either applies a specified translational component to an existing transform matrix, or replaces the matrix with one that represents the specified translation alone. The transform is specified as a one-dimensional array of 9 elements that are the elements of a 3-row by 3-column matrix ordered by rows.

The order of the elements are as follows:

Matrix      Array
a b 0
c d 0       (a,b,0,c,d,0,e,f,1)
e f 1

Transforms act on the coordinates of primitives, so that a point with coordinates (x,y) is transformed to the point:

(a*x + c*y + e, b*x + d*y + f)

The transform can be used in any call following:

• GpiSetModelTransformMatrix
• GpiSetSegmentTransformMatrix
• GpiSetViewingTransformMatrix
• GpiSetDefaultViewMatrix.

Other similar helper functions are:

• GpiScale to apply a scaling component
• GpiRotate to apply a rotation component.

Example Code

This example translates the center of the picture back to the center of the page.

#define INCL_GPITRANSFORMS
#define INCL_WINSYS
#include <OS2.H>

HPS hps;                 /* Presentation space handle. */
MATRIXLF matlf;          /* Current viewing transformation */
POINTL ptlPictCenter;

/* determine the center of the page */
ptlPictCenter.x = WinQuerySysValue(HWND_DESKTOP, SV_CXFULLSCREEN)/2 - ptlPictCenter.x;
ptlPictCenter.y = WinQuerySysValue(HWND_DESKTOP, SV_CYFULLSCREEN)/2 - ptlPictCenter.y;

GpiQueryViewingTransformMatrix(hps,
                               9L,
/* Translate the center of the picture back to the center of the page */
                               &matlf);

GpiTranslate(hps, &matlf, TRANSFORM_ADD, &ptlPictCenter);

Related Functions

• GpiRotate
• GpiScale
• GpiSetDefaultViewMatrix
• GpiSetModelTransformMatrix
• GpiSetSegmentTransformMatrix
• GpiSetViewingTransformMatrix