GpiCallSegmentMatrix

This function calls a segment and applies an instance transform to it.

Syntax

GpiCallSegmentMatrix(hps, lSegment, lCount, pmatlfArray, lOptions)

Parameters

hps (HPS) - input

Presentation-space handle.

lSegment (LONG) - input

Identifier of segment to be called.

This must be greater than 0.

The segment must not be a chained segment.

lCount (LONG) - input

Number of elements.

The number of elements of pmatlfArray to be examined, starting from the beginning of the structure. If lCount is less or equal than 9, the remaining elements default to the corresponding elements of the identity matrix. If lCount = 0, the identity matrix is used.

pmatlfArray (PMATRIXLF) - input

Instance transform matrix.

The third, sixth, and ninth elements, when specified, must be 0, 0, and 1, respectively.

lOptions (LONG) - input

Transformation options.

Specify how the transform defined by the pmatlfArray parameter should be used to modify the existing current model transform for the duration of the function. The existing transform is the concatenation, in the current function context, of the instance, segment, and model transforms, from the root segment downwards.

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. The existing transform precedes the new transform. This option is most useful for incremental updates to transforms.

TRANSFORM_PREEMPT The specified transform is combined with the existing model transform. The new transform precedes the existing transform.

Returns

lHits (LONG) - returns

Correlation and error indicators.

GPI_OK Successful

GPI_HITS Correlate hits

GPI_ERROR Error

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_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_CALLED_SEG_NOT_FOUND (0x200F): An attempt was made to call a segment that did not exist.
PMERR_CALLED_SEG_IS_CHAINED (0x200D): An attempt was made to call a segment that has a chained attribute set.
PMERR_CALLED_SEG_IS_CURRENT (0x200E): An attempt was made to call a segment that is currently open.
PMERR_SEG_CALL_STACK_EMPTY (0x20FC): A call stack empty condition was detected when attempting a pop function during GpiPop or segment drawing.

Remarks

The instance transform specified is a model transform that is used to modify the current model transform, in a way that depends upon the value of the lOptions parameter, before calling the segment. This new transform applies only to the called segment. On return, it is reset to the model transform in operation before the function was called.

The transform is specified as a one-dimensional array of elements, being the first lCount 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 │
└──     ──┘

A point with coordinates (x,y) is transformed to the point

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

The called segment must have a unity transform for the viewing transform (see GpiSetViewingTransformMatrix).

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.

Example Code

This example calls the GpiCallSegmentMatrix function to draw a segment three times. Each time the segment is drawn, the instance transformation doubles in size. The result is three triangles with the last triangle twice the size of the second, and the second twice the size of the first.

#define INCL_GPITRANSFORMS      /* GPI Transform functions      */
#define INCL_GPISEGMENTS        /* Segment functions            */
#define INCL_GPIPRIMITIVES      /* GPI primitive functions      */
#include <os2.h>

HPS    hps;
USHORT i;
POINTL ptlStart = { 0, 0 }; /* first vertex                     */
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices  */
MATRIXLF matlfInstance = { MAKEFIXED(1, 0),  MAKEFIXED(0, 0), 0,
                           MAKEFIXED(0, 0),  MAKEFIXED(1, 0), 0,
                           0,                0,               1 };

GpiOpenSegment(hps, 1L);             /* opens segment               */
GpiMove(hps, &ptlStart);             /* moves to start point (0, 0) */
GpiPolyLine(hps, 3L, ptlTriangle);   /* draws triangle              */
GpiCloseSegment(hps);                /* closes segment              */

for (i = 0; i < 3; i++)
    {
    /*
     * Draw the segment after adding the matrix to the model
     * transformation.
     */

    GpiCallSegmentMatrix(hps, 1L, 9, &matlfInstance, TRANSFORM_ADD);
    matlfInstance.fxM11 *= 2;
    matlfInstance.fxM22 *= 2;
    }

Graphic Elements and Orders

Element Type: OCODE_GCALLS; Order: Push and Set Model Transform; Order: Call Segment; Order: Pop

Related Functions