Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPITRANSFORMS
 
BOOL GpiSetSegmentTransformMatrix(hps, idSegment, cElements, pmatlf,
    flType)
HPS hps;             /* presentation-space handle                       */
LONG idSegment;      /* segment identifier                              */
LONG cElements;      /* number of elements                              */
PMATRIXLF pmatlf;    /* address of structure with transformation matrix */
LONG flType;         /* type of transformation                          */
 
The GpiSetSegmentTransformMatrix function sets the segment transformation
for the specified segment. The segment transformation applies to all
primitives in the segment. The function sets the transformation by adding or
replacing the existing transformation matrix with the matrix pointed to by
the pmatlf parameter. The function adds, preempts, or replaces the existing
transformation matrix as specified by the flType parameter.
 
The GpiSetSegmentTransformMatrix function requires a nine-element matrix to
set the segment transformation. If the specified matrix does not contain
nine elements, the function uses the corresponding elements of the identity
matrix for each unspecified element. The cElements parameter specifies the
number of elements in the matrix. If this parameter equals zero, the
identity matrix is used. If scaling values greater than one are given, care
must be taken that the combined effect of this and any other relevant
transformations do not exceed the limit for fixed-point numbers.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
idSegment  Specifies the segment identifier; it must be greater than zero.
           The segment transformation does not affect primitives outside the
           specified segment.
 
cElements  Specifies the number of elements in the matrix to set. It can be
           any integer in the range 0 through 9.
 
pmatlf     Points to a MATRIXLF structure that contains the transformation
           matrix.
 
flType     Specifies how a specified matrix should be used to modify the
           segment transformation. It can be one of the following values:
 
           Value              Meaning
           ─────────────────────────────────────────────────────────────────
           TRANSFORM_ADD      Additive. The specified transformation matrix
                              is combined with the existing segment
                              transformation, in the order of the existing
                              transformation first, the new transformation
                              second. This option is useful for incremental
                              updates to transformations.
 
           TRANSFORM_PREEMPT  Preemptive. The specified transformation
                              matrix is combined with the existing segment
                              transformation, in the order of the new
                              transformation first, the existing
                              transformation second.
 
           TRANSFORM_REPLACE  New/replace. The previous segment
                              transformation is discarded and replaced by
                              the specified transformation matrix.
 
Return Value
 
The return value is GPI_OK if the function is successful or GPI_ERROR if an
error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_INV_HPS
     PMERR_INV_LENGTH_OR_COUNT
     PMERR_INV_MATRIX_ELEMENT
     PMERR_INV_MICROPS_FUNCTION
     PMERR_INV_SEG_NAME
     PMERR_INV_TRANSFORM_TYPE
     PMERR_PS_BUSY
     PMERR_SEG_NOT_FOUND
 
Comments
 
The system applies a segment transformation to the primitives in the given
segment after applying the model transformation and any instance and segment
transformations from calling segments.
 
See Also
 
GpiQueryDefaultViewMatrix, GpiQuerySegmentTransformMatrix, WinGetLastError,
MATRIXLF
 
                                      ♦