GpiSetDefaultViewMatrix

Syntax

GpiSetDefaultViewMatrix(hps, lCount, pmatlfArray, lOptions);

Parameters

hps (HPS) - input

Presentation-space handle.

lCount (LONG) - input

Number of elements.

The number of elements supplied in pmatlfArray, that are 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. Specifying lCount = 0 means that 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 parameter should be used to modify the existing default viewing transform.

Possible values are:

TRANSFORM_REPLACE

The previous default viewing transform is discarded and replaced by the specified transform.

TRANSFORM_ADD

The specified transform is combined with the existing default viewing 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 default viewing transform, in the order (1) new transform, (2) existing transform.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE

Successful completion

FALSE

Error occurred.

Remarks

The transform matrix specified is used to update any previous default viewing transform, depending upon the value of lOptions. The transform is specified as a one-dimensional array of lCount elements, being the first n 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)$$

The initial value of the default viewing transform is the identity matrix, as shown below:

Matrix             Array
┌     ┐
│ 1 0 0 │
│ 0 1 0 │         (1,0,0,0,1,0,0,0,1)
│ 0 0 1 │
└     ┘

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.

This function must not be issued in a path or area bracket.

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.

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_TRANSFORM_TYPE (0x20D0)

An invalid options parameter was specified with a transform matrix function.

PMERR_INV_MATRIX_ELEMENT (0x209B)

An invalid transformation matrix element was specified.

Example Code

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

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

rc = GpiSetDefaultViewMatrix(hps, lCount,
       pmatlfarray, lOptions);

This example uses the GpiSetDefaultViewMatrix function to replace the existing default viewing transformation. The new transformation translates drawing to the right by 100 units.

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

BOOL fSuccess; /* success indicator */
HPS hps; /* Presentation-space handle */

/* transform matrix */
MATRIXLF matlf = {MAKEFIXED(1,0), 0, 0, 0, MAKEFIXED(1,0), 0, 100};

fSuccess = GpiSetDefaultViewMatrix(hps, 7L, &matlf, TRANSFORM_REPLACE);

Related Functions

• GpiQueryDefaultViewMatrix
• GpiSetViewingTransformMatrix