GpiSetViewingTransformMatrix

This function sets the viewing transform that is to apply to any subsequently opened segments.

Syntax

GpiSetViewingTransformMatrix(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 option.

Specifies how the specified transform is to be used to modify the existing viewing transform. This must be:

TRANSFORM_REPLACE: New and replace. The previous viewing transform is discarded and replaced by the specified 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_MICROPS_FUNCTION (0x20A1)

An attempt was made to issue a function that is invalid in a micro presentation space.

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.

PMERR_INV_IN_SEG (0x208D)

An attempt was made to issue a function invalid inside a segment bracket.

PMERR_NOT_IN_RETAIN_MODE (0x20E2)

An attempt was made to issue a segment editing element function that is invalid when the actual drawing mode is not set to retain.

Remarks

This function is only valid outside segments. The viewing transform that is set applies to all subsequently opened (new) segments (it has no effect on primitives outside segments). All graphics primitives in a segment must have the same viewing transform. When it has been set for a particular segment, the viewing transform for that segment cannot be changed.

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 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 ³
ÀÄ       ÄÙ

The viewing transform must be set (or defaulted) to the unity transform, before any segment that is to be called is first opened.

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.

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 option. */
BOOL         rc;           /*  Success indicator. */

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

In this example, the GpiSetViewingTransformMatrix is used to replace the existing viewing transformation. The new transformation will then double the width and height of drawing.

define INCL_GPITRANSFORMS
include <OS2.H>

HPS hps; /* Presentation space handle. */ LONG lCount; /* maximum number of elements */ MATRIXLF matlf = { MAKEFIXED(2,0), /* scale x coordinates by a */

                                   /* factor of 2.             */
                  0, 0, 0,         /* no rotation.             */
                  MAKEFIXED(2,0),  /* scale y coordinates by a */
                                   /* factor of 2.             */
                  0, 0, 0, 1};     /* no rotation.             */

GpiSetViewingTransformMatrix(hps,

                            9L,    /* number of elements.      */
                            &matlf,
                            TRANSFORM_REPLACE);

Related Functions