GpiRotate
This function applies a rotation to a transform matrix.
Syntax
#define INCL_GPITRANSFORMS /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ PMATRIXLF pmatlfArray; /* Transform matrix. */ LONG lOptions; /* Transform options. */ FIXED fxAngle; /* Rotation angle. */ PPOINTL pptlCenter; /* Center of rotation. */ BOOL rc; /* Success indicator. */ rc = GpiRotate(hps, pmatlfArray, lOptions, fxAngle, pptlCenter);
Parameters
- hps (HPS) - input
- Presentation-space handle.
- pmatlfArray (PMATRIXLF) - in/out
- Transform 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. The third, sixth, and ninth elements must be 0, 0, and 1, respectively.
- lOptions (LONG) - input
- Transform options.
Specifies how the transform defined by the specified rotation should be used to modify the previous transform specified by the
pmatlfArray parameter. Possible values are:
- TRANSFORM_REPLACE
The previous transform is discarded and replaced by the transform describing the specified rotation.
- TRANSFORM_ADD
The previous transform is combined with a transform representing the specified rotation in the order (1) previous transform, (2) rotational transform. This option is most useful for incremental updates to transforms.
- fxAngle (FIXED) - input
- Rotation angle.
The angle describing the rotation, measured counterclockwise from the x-axis in degrees.
- pptlCenter (PPOINTL) - input
- Center of rotation.
The point about which the rotation occurs.
Return Code
- rc (BOOL) - returns
- Success indicator.
- TRUE Successful completion
- FALSE Error occurred.
Errors
Possible returns from WinGetLastError
- PMERR_INV_TRANSFORM_TYPE (0x20D0)
- An invalid options parameter was specified with a transform matrix function
Remarks
This function is a helper function that either applies a specified rotational component to an existing transform matrix, or replaces the matrix with one that represents the specified rotation alone.
The transform is specified as a one-dimensional array of 9 elements that are the elements of a 3-row by 3-column matrix ordered by rows.
The order of the elements is as follows:
Matrix Array a b 0 c d 0 (a,b,0,c,d,0,e,f,1) e f 1
Transforms act on the coordinates of primitives, so that a point with coordinates (x,y) is transformed to the point:
(a*x + c*y + e, b*x + d*y + f)
The transform can be used in any call following:
- GpiSetModelTransformMatrix
- GpiSetSegmentTransformMatrix
- GpiSetViewingTransformMatrix
- GpiSetDefaultViewMatrix.
Other similar helper functions are:
- GpiTranslate to apply a translation component
- GpiScale to apply a scaling component.
Example Code
In this example, the viewing transform matrix is rotated 10 degrees counterclockwise from the x-axis. Hence, everything will appear rotated.
#define INCL_GPITRANSFORMS
#include <OS2.H>
HPS hps; /* presentation space handle */
MATRIXLF matlf; /* transform matrix. */
POINTL ptlCenter; /* center of rotation. */
GpiQueryViewingTransformMatrix(hps, 1L, matlf);
ptlCenter.x = 50L;
ptlCenter.y = 50L;
GpiRotate(hps,
&matlf,
TRANSFORM_REPLACE,
MAKEFIXED(10,0), /* rotate 10 degrees left. the angle */
/* must be passed in fixed format. */
/* see the pmgpi.h file for a */
/* description of the MAKEFIXED macro. */
&ptlCenter);