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 GpiSetModelTransformMatrix(hps, cElements, pmatlf, flType)
HPS hps;             /* presentation-space handle                       */
LONG cElements;      /* number of elements                              */
PMATRIXLF pmatlf;    /* address of structure with transformation matrix */
LONG flType;         /* transformation types                            */
 
The GpiSetModelTransformMatrix function sets the model transformation. The
model transformation applies to all primitives used inside and outside of
segments. 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 GpiSetModelTransformMatrix function requires a nine-element matrix to
set the model 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.
 
If the attribute mode is AM_PRESERVE, the function saves the previous model
transformation on the attribute stack when it sets the new transformation.
The previous model transformation can be retrieved using the GpiPop
function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
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 model
                              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 model
                              transformation, in the order of the new
                              transformation first, the existing
                              transformation second.
 
           TRANSFORM_REPLACE  New/replace. The previous model 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
the following:
 
     PMERR_INV_HPS
     PMERR_INV_LENGTH_OR_COUNT
     PMERR_INV_MATRIX_ELEMENT
     PMERR_INV_TRANSFORM_TYPE
     PMERR_PS_BUSY
 
See Also
 
GpiQueryModelTransformMatrix, GpiSetAttrMode, WinGetLastError, MATRIXLF
 
                                      ♦