Function GraScale() | Xbase++

Functions and Directives Functions and Directives

Calculates scaling transformation for a matrix.

GraScale( [<oPS>], <aMatrix>, <aScale>, ;
                   <aPoint> , [<nMode>] ) --> lSuccess

<oPS>

The argument <oPS> specifies the presentation space for whose coordinate system the scaling transformation is calculated. If the current window is an XbpCrt window, <oPS>is optional. If it is NIL, the return value of SetAppWindow():presSpace() is used. In all other cases <oPS> is not optional. It must be created either using XbpPresSpace():new() or a "Micro PS" must be requested from an Xbase Part using the method:lockPS(). After graphic output the Micro PS must be released with :unlockPS().

<aMatrix> := GraInitMatrix()

The parameter <aMatrix> is a three dimensional array which contains the transformation matrix. It must be created by GraInitMatrix().

<aScale> := { <nXScale>, <nYScale> }

<aScale> is an array of two elements which contains the scaling factors in the x and y directions. <nXScale> specifies the enlargement factor for the x axis and <nYScale> specifies the factor for the y axis. Negative factors lead to a mirror image.

<aPoint> := { <nX>, <nY> }

<aPoint> specifies coordinates for the point of reference from which the scaling occurs. This is especially important for areas like circles and boxes. If the point of reference is not the mid-point of the area, it causes the segment to be shifted as it is scaled.

<nMode>

For the optional parameter <nMode>, only the #define constants listed in the following table may be used:

Constant	Description
GRA_TRANSFORM_REPLACE	Replaces the existing <aMatrix> transformation after the transformation
GRA_TRANSFORM_ADD	Keeps the existing <aMatrix> transformation and calculates an additional transformation
The default value is GRA_TRANSFORM_REPLACE.

The return value of GraScale() is .T. (true) when the scaling transformation was calculated, otherwise it is .F. (false). If the return value equals .F., the cause of error can be determined using GraError().

The function GraScale() performs the matrix calculations required for scaling graphic segments (enlarging, reducing or creating a mirror image). A matrix must be passed to the function to hold the values resulting from the calculations. The matrix is a three dimensional array which must be generated by GraInitMatrix() before it is used for matrix calculations.

Graphic segments which are scaled must have been previously generated from graphic primitives. The functions GraSegOpen() and GraSegClose() are used to define a graphic segment. GraScale() performs calculations for the scaling and the function GraSegDraw() makes the scaling visible. Scaling factors larger than 1 enlarge a segment, factors between 0 and 1 reduce a segment and negative values produce a mirror image.

Matrix operations cannot be calculated for raster images (bitmaps). To scale raster images the function GraBitBlt() must be used.

Scaling a segment


// In the example a box is drawn, followed by the display 
// of three scaling transformations. Each scaling has 
// a different point of reference which is identified by a 
// marker. After each transformation a key must be 
// pressed. 

#include "Gra.ch" 

PROCEDURE Main 
   LOCAL aMatrix := GraInitMatrix() 
   LOCAL nSegment, i 

   SetColor("N/W")                     // fill window with pale gray 
   CLS 

   nSegment := graSegOpen()            // create segment 
   GraBox( NIL, {200,150}, {300,230}, GRA_OUTLINE ) 
   GraSegClose() 

   GraSegDraw(NIL, nSegment)           // draw segment 
   Inkey(0) 
                                       // scale 
   GraScale( NIL, aMatrix, {2,2}, {200,150} ) 
   GraSegDraw(NIL, nSegment, aMatrix)  // point of reference is 
   GraMarker( NIL, {200,150} )         // lower left corner 

   Inkey(0) 

   GraScale( NIL, aMatrix, {2,2}, {250,190} ) 
   GraSegDraw(NIL, nSegment, aMatrix)  // point of reference is 
   GraMarker( NIL, {250,190} )         // the mid-point of box 
   Inkey(0) 

   GraScale( NIL, aMatrix, {2,2}, {150,100} ) 
   GraSegDraw(NIL, nSegment, aMatrix)  // point of reference is left 
   GraMarker( NIL, {150,100} )         // below the box 
   Inkey(0) 

RETURN

Function GraScale() Foundation