GpiSetSegmentTransformMatrix

This function sets the segment transform that normally applies to all of the primitives in the specified segment.

Syntax

GpiSetSegmentTransformMatrix(hps, lSegid, lCount, pmatlfarray, lOptions)

Parameters

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

lSegid (LONG) - input: Segment identifier.; This must be greater than 0.

lCount (LONG) - input: Number of elements.; The number of elements to be used in the pmatlfarray parameter. If lCount is less than 9, the elements omitted default to the corresponding elements of the identity matrix (see below). Specifying lCount=0 denotes 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 existing segment transform is to be modified by the transform defined by the pmatlfarray parameter. The new segment transform is computed, and the result stored back in the segment, replacing the existing value. When the segment is drawn, the stored segment transform is used to update the segment transform that is currently in effect, in an additive manner. Possible values are:

TRANSFORM_REPLACE: The previous default segment transform is discarded and replaced by the specified transform.
TRANSFORM_ADD: The specified transform is combined with the existing default segment 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 segment 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_SEG_NAME (0x20C8): An invalid segment identifier was specified.
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_SEG_NOT_FOUND (0x2100): The specified segment identifier did not exist.
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 segment transform of a retained segment, according to the value of the lOptions parameter.

The segment transform is actually a model transform that applies at the start of the segment. It can be overridden later in the segment with a GpiSetModelTransformMatrix function.

This function specifies the transform as a one-dimensional array of lCount elements, being the first lCount elements of a 3-row by 3-column matrix ordered in 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 transform of a segment 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.

Segment transforms do not apply to primitives outside segments.

Example Code

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

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

rc = GpiSetSegmentTransformMatrix(hps, lSegid,
       lCount, pmatlfarray, lOptions);

This example sets the transformation matrix of the highest priority segment to scale everything by a factor of 2.

#define INCL_GPISEGMENTS
#include <OS2.H>

HPS hps;         /*   Presentation-space */
                 /*   handle.            */
LONG lSegid;     /*   Segment identifier. */

MATRIXLF matlfArray = {MAKEFIXED(2,0),
                       0,0,0,MAKEFIXED(2,0),
                       0,0,0,1};

                              /* array of Transform matrix  */
                              /* structures.                */

lSegid = GpiQuerySegmentPriority(hps,
                /* find the segment with the highest */
                /* priority.                     */
                                  0,
                                  HIGHER_PRI);



GpiSetSegmentTransformMatrix(hps,
                             lSegid,
                             9L,
                             &matlfArray);

Related Functions