GpiSetModelTransformMatrix

This function sets the model transform matrix for subsequent primitives.

Syntax

 GpiSetModelTransformMatrix(hps, lCount, pmatlfArray, lOptions)

Parameters

hps (HPS) - input: Presentation-space handle.

lCount (LONG) - input: Number of elements in matrix.; The number of elements of pmatlfArray to be examined, starting from the beginning of the structure. If lCount is less than 9, remaining elements default to the corresponding elements of the identity matrix. If lCount = 0, the identity matrix is used.

pmatlfArray (PMATRIXLF) - input: Transformation 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. If the presentation space coordinate format is GPIF_SHORT (see GpiCreatePS), these elements must be within the range -1 through +1.; The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively.

lOptions (LONG) - input: Transform options.; Specifies how the transform defined by the pmatlfArray should be used to modify the existing current model transform (the existing transform is the concatenation, in the current call context, of the instance, segment and model transforms, from the root segment downwards). Possible values are:

TRANSFORM_REPLACE: The previous model transform is discarded and replaced by the specified transform.
TRANSFORM_ADD: The specified transform is combined with the existing model transform, in the order (1) existing transform, (2) new transform. This option is most useful for incremental updates to transforms. :;TRANSFORM_PREEMPT; The specified transform is combined with the existing model transform, in the order (1) new transform, (2) existing transform.

Return Code

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion
FALSE: Error occurred.

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_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
PMERR_INV_MATRIX_ELEMENT (0x209B): An invalid transformation matrix element was specified.
PMERR_INV_TRANSFORM_TYPE (0x20D0): An invalid options parameter was specified with a transform matrix function.

Remarks

The matrix is used to update the previous current model transform, depending upon the value of lOptions.

The transform is specified as a one-dimensional array of lCount elements, being the first 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 ³
ÀÄÄ     ÄÄÙ

The transform acts on the coordinates of the primitives in a segment, so that a point with coordinates (x,y) is transformed to the point:

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

If scaling values greater than unity are given (which only applies if the presentation space coordinate format as set by the GpiCreatePS function is GPIF_LONG) it is possible for the combined effect of this, and any other relevant transforms, to exceed fixed-point implementation limits. This causes an error.

The attribute mode (see GpiSetAttrMode) determines whether the current value of the model transform is preserved.

Model transforms can apply to primitives either inside or outside segments.

Example Code

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

HPS          hps;          /*  Presentation-space handle. */
LONG         lCount;       /*  Number of elements in matrix. */
PMATRIXLF    pmatlfArray;  /*  Transformation matrix. */
LONG         lOptions;     /*  Transform options. */
BOOL         rc;           /*  Success indicator. */

rc = GpiSetModelTransformMatrix(hps, lCount,
       pmatlfArray, lOptions);

This function sets the model transformation matrix as one which scales everything by a factor of 2.

#define INCL_GPITRANSFORMS
#include <OS2.H>

HPS hps;         /*   Presentation-space */
                 /*   handle.            */
MATRIXLF matlf = { MAKEFIXED(2,0),  /* see pmgpi.h for a */
                                    /* definition of the */
                                    /* MAKEFIXED macro.  */
                   0, 0, 0,
                   MAKEFIXED(2,0),
                   0, 0, 0, 1};


GpiSetModelTransformMatrix(hps,
                           1L,
                           &matlf,
                           TRANSFORM_REPLACE);

Graphic Elements and Orders

Element Type: OCODE_GSTM

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE.

Order: Set Model Transform

Element Type: OCODE_GPSTM

This element type is generated if the attribute mode is set to AM_PRESERVE.

Order: Push and Set Model Transform

Related Functions