Function GraRotate() | Xbase++

Functions and Directives Functions and Directives

Calculates a rotational transformation for a matrix.

GraRotate( [<oPS>], <aMatrix>, <nAngle>, ;
                    <aPoint> , [<nMode>] ) --> lSuccess

<oPS>

The argument <oPS> specifies the presentation space for whose coordinate system the rotational 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() before it is used.

<nAngle> specifies the angle of rotation (in number of degrees). <nAngle> must be an integer numeric value. Positive values lead to counter clockwise rotation, negative values to clockwise rotation.

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

<aPoint> is an array of two elements which determines the coordinates for the turning point of the rotation. The first element <nX> specifies the x coordinate and the second element <nY>specifies the y coordinate. The unit for the coordinates depends on the coordinate system defined for the presentation space. If no presentation space is specified, the values for the coordinates are indicated in pixels, which is the unit for a window. The origin for the coordinates (the point {0,0}) is at the lower left.

<nMode>

The following table lists #define constants used for the optional parameter <nMode>:

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 GraRotate() is .T. (true) when the rotational transformation was calculated, otherwise it is .F. (false). If the return value equals .F., the cause of error can be determined by GraError().

The function GraRotate() performs the matrix calculations required for rotating graphic segments. A matrix must be passed to the function to hold the values resulting from the calculation. This matrix is a three dimensional array which must be generated by GraInitMatrix() before it is used for matrix calculations.

Graphic segments which are rotated (turned) at a specific angle must be previously generated from graphic primitives. The functions GraSegOpen() and GraSegClose() are used to define a graphic segment. GraRotate() calculates the rotation and the function GraSegDraw() makes the rotation visible.

Matrix operations cannot be calculated for raster images (bitmaps) and raster images cannot be rotated.

Rotating a segment


// In the example a graphic segment is defined which draws 
// a box. The segment is then rotated to the left 11 times at 
// 30 degrees and displayed each time. The turning point is the 
// lower left corner of the box. 

#include "Gra.ch" 

PROCEDURE Main 
   LOCAL aMatrix, nSegment, i 

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

   aMatrix  := GraInitMatrix()      // create matrix 
   nSegment := graSegOpen()         // create segment 

                                    // define box 
   GraBox( NIL, {200,150}, {300,230}, GRA_OUTLINE ) 
   GraSegClose()                    // closed segment 

   GraSegDraw(NIL,nSegment,aMatrix) // draw segment 

   FOR i:=1 TO 11                   // rotate segment 
      GraRotate( NIL, aMatrix, 30, {200,150}, GRA_TRANSFORM_ADD ) 
      GraSegDraw(NIL, nSegment, aMatrix) 
   NEXT                             // draw segment 

   Inkey(0) 

RETURN

Function GraRotate() Foundation