GpiScale: Difference between revisions
| (3 intermediate revisions by 2 users not shown) | |||
| Line 2: | Line 2: | ||
==Syntax== | ==Syntax== | ||
GpiScale (hps, pmatlfArray, lOptions, afxScale, pptlCenter) | |||
==Parameters== | ==Parameters== | ||
; hps (HPS) - input : Presentation-space handle. | ;hps (HPS) - input : Presentation-space handle. | ||
; pmatlfArray (PMATRIXLF) - in/out : Transform matrix. | ; 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 | :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. | ||
binary point between the second and third bytes. Thus a value of 1.0 is represented by 65 536. Other elements are normal signed | :The third, sixth, and ninth elements must be 0, 0, and 1, respectively. | ||
integers. | ;lOptions (LONG) - input : Transform options. | ||
:Specifies how the transform defined by the specified scaling should be used to modify the previous transform specified by the pmatlfArray parameter. Possible values are: | |||
The third, sixth, and ninth elements must be 0, 0, and 1, respectively. | * TRANSFORM_REPLACE - The previous transform is discarded and replaced by the transform describing the specified scaling. | ||
* TRANSFORM_ADD - The previous transform is combined with a transform representing the specified scaling in the order (1) previous transform, (2) scaling transform. This option is most useful for incremental updates to transforms. | |||
; lOptions (LONG) - input : Transform options. | ;afxScale (PFIXED) - input : Array of scale factors. | ||
:The first element of the array is the x scale factor, and the second is the y scale factor. | |||
Specifies how the transform defined by the specified scaling should be used to modify the previous transform specified by the | Scaling values outside the range -1 through +1 are not valid for subsequent use with presentation spaces that have a coordinate format (as set by the GpiCreatePS function) of GPIF_SHORT. | ||
pmatlfArray parameter. Possible values are: | ;pptlCenter (PPOINTL) - input : Center of scale. | ||
* TRANSFORM_REPLACE | :The point about which the scale occurs. | ||
The previous transform is discarded and replaced by the transform describing the specified scaling. | |||
* TRANSFORM_ADD | |||
The previous transform is combined with a transform representing the specified scaling in the order (1) previous | |||
transform, (2) scaling transform. This option is most useful for incremental updates to transforms. | |||
; afxScale (PFIXED) - input : Array of scale factors. | |||
The first element of the array is the x scale factor, and the second is the y scale factor. | |||
Scaling values outside the range -1 through +1 are not valid for subsequent use with presentation spaces that have a coordinate | |||
format (as set by the GpiCreatePS function) of GPIF_SHORT. | |||
; pptlCenter (PPOINTL) - input : Center of scale. | |||
The point about which the scale occurs. | |||
==Return Code== | ==Return Code== | ||
| Line 65: | Line 40: | ||
c d 0 (a,b,0,c,d,0,e,f,1) | c d 0 (a,b,0,c,d,0,e,f,1) | ||
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: | 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) | (a*x + c*y + e, b*x + d*y + f) | ||
The transform can be used in any call following: | The transform can be used in any call following: | ||
* GpiSetModelTransformMatrix | * GpiSetModelTransformMatrix | ||
| Line 97: | Line 70: | ||
GpiScale (hps, &matlf, TRANSFORM_REPLACE, scalars, &ptlCenter); | GpiScale (hps, &matlf, TRANSFORM_REPLACE, scalars, &ptlCenter); | ||
</PRE> | </PRE> | ||
==Related Functions== | ==Related Functions== | ||
* [[GpiRotate]] | *[[GpiRotate]] | ||
* [[GpiSetDefaultViewMatrix]] | *[[GpiSetDefaultViewMatrix]] | ||
* [[GpiSetModelTransformMatrix]] | *[[GpiSetModelTransformMatrix]] | ||
* [[GpiSetSegmentTransformMatrix]] | *[[GpiSetSegmentTransformMatrix]] | ||
* [[GpiSetViewingTransformMatrix]] | *[[GpiSetViewingTransformMatrix]] | ||
* [[GpiTranslate]] | *[[GpiTranslate]] | ||
[[Category:Gpi]] | [[Category:Gpi]] | ||
Latest revision as of 23:41, 7 April 2025
This function applies a scaling component to a transform matrix.
Syntax
GpiScale (hps, pmatlfArray, lOptions, afxScale, 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 scaling 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 scaling.
- TRANSFORM_ADD - The previous transform is combined with a transform representing the specified scaling in the order (1) previous transform, (2) scaling transform. This option is most useful for incremental updates to transforms.
- afxScale (PFIXED) - input
- Array of scale factors.
- The first element of the array is the x scale factor, and the second is the y scale factor.
Scaling values outside the range -1 through +1 are not valid for subsequent use with presentation spaces that have a coordinate format (as set by the GpiCreatePS function) of GPIF_SHORT.
- pptlCenter (PPOINTL) - input
- Center of scale.
- The point about which the scale 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 which either applies a specified scaling component to an existing transform matrix, or replaces the matrix with one that represents the specified scaling 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:
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
- GpiRotate to apply a rotation component.
Example Code
In this example, the viewing transform matrix is scaled by a factor of 2.
#define INCL_GPITRANSFORMS #include <OS2.H> HPS hps; /* presentation space handle */ MATRIXLF matlf; /* transform matrix */ POINTL ptlCenter; /* center of rotation */ FIXED scalars[2]; /* x and y scale factors */ GpiQueryViewingTransformMatrix(hps, 1L, matlf); ptlCenter.x = 50L; ptlCenter.y = 50L; scalars[0] = MAKEFIXED(2,0); /* Scale x values by 2 */ scalars[1] = MAKEFIXED(3,0); /* Scale y values by 3 */ GpiScale (hps, &matlf, TRANSFORM_REPLACE, scalars, &ptlCenter);