4. Coordinate Transformations - Xfm,Xfmstack

VglTools Programmer Manual

The Xfm and Xfmstack modules support the transformation of 3D shapes from so-called model coordinates to a screen oriented virtual device coordinate system. These 3D transformations include scaling, translation and rotation. The 3D transformations may be divided into modeling, viewing and projection transformations. The conversion of transformed 3D virtual device coordinates to device coordinates is called the viewport transformation and is performed by the ZBuffer module.

4.1 Transformation Matrices - Xfm

The Xfm module creates coordinate transformation matrices which may be used to translate, rotate and scale 3D graphics objects. All transformation matrices are developed internally as 4 by 4 matrices which operate upon 3D homogeneous coordinates. In this model, a point in 3D euclidean space (x,y,z) becomes a homogeneous point with coordinates (x,y,z,1.). The functions associated with a Xfm object are the following.

Begin and end an instance of an object, generic object functions

    *vgl_XfmBegin        - create an instance of a Xfm object
    vgl_XfmEnd           - destroy an instance of a Xfm object
    vgl_XfmError         - return Xfm object error flag
    vgl_XfmCopy          - make a copy of a Xfm object

Matrix creation and manipulation

    vgl_XfmComputeRotateEuler  - compute Euler angles of rotation matrix
    vgl_XfmComputeRotateVector - compute angle and axis of rotation matrix
    vgl_XfmIdentity      - create identity matrix
    vgl_XfmInvert        - invert current matrix
    vgl_XfmLookAt        - create viewing matrix
    vgl_XfmMult          - multiply two viewing matrices
    vgl_XfmPurge         - purge matrix of rotation, translation or scale
    vgl_XfmRotate        - create rotation matrix about axis
    vgl_XfmRotateEuler   - create rotation matrix given Euler angles
    vgl_XfmRotateVector  - create rotation matrix about vector
    vgl_XfmScale         - create scaling matrix
    vgl_XfmSetMatrix     - create user defined matrix
           GetMatrix     - access current matrix
    vgl_XfmTranslate     - create translation matrix

All graphics device interface modules require 4 by 4 matrices to specify modelling and viewing transformations. Use the Xfm module to create and manipulate these transformation matrices. Use vgl_XfmGetMatrix to access the current 4x4 matrix.

4.2 Function Descriptions

The currently available Xfm functions are described in detail in this section.

Xfm

NAME

*vgl_XfmBegin - create an instance of an Xfm object

C SPECIFICATION

    vgl_Xfm *vgl_XfmBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Xfm object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of an Xfm object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a Xfm object using

         void vgl_XfmEnd (vgl_Xfm *xfm)

Return the current value of a Xfm object error flag using

         Vint vgl_XfmError (vgl_Xfm *xfm)

Make a copy of a Xfm object. The private data from the fromxfm object is copied to the xfm object. Any previous private data in xfm is lost.

         void vgl_XfmCopy (vgl_Xfm *xfm,
                           vgl_Xfm *fromxfm)

Xfm

NAME

vgl_XfmComputeRotateEuler - compute Euler angles of rotation matrix

C SPECIFICATION

    void vgl_XfmComputeRotateEuler (vgl_Xfm *xfm,
                                    Vfloat *anglex,
                                    Vfloat *angley,
                                    Vfloat *anglez)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.

OUTPUT ARGUMENTS

    anglex       Angle of rotation in radians about initial x axis.
    angley       Angle of rotation in radians about rotated y' axis.
    anglez       Angle of rotation in radians about rotated z'' axis.

DESCRIPTION

Compute three Euler angles of a rotation matrix. The rotations are applied in order anglex about the initial x axis, followed by angley about the rotated y' axis followed by anglez about the rotated z'' axis. A positive angle assumes a right hand rotation about the specified axis.

Xfm

NAME

vgl_XfmComputeRotateVector - compute angle and axis of rotation matrix

C SPECIFICATION

    void vgl_XfmComputeRotateVector (vgl_Xfm *xfm,
                                     Vfloat *angle,
                                     Vfloat *vx, Vfloat *vy, Vfloat *vz)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.

OUTPUT ARGUMENTS

    angle        Angle of rotation in radians.
    vx,vy,vz     Direction of vector.

DESCRIPTION

Compute the angle and axis of a rotation matrix. A positive angle assumes a right hand rotation about the specified vector.

Xfm

NAME

vgl_XfmIdentity - create an identity matrix

C SPECIFICATION

    void vgl_XfmIdentity (vgl_Xfm *xfm)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Create an identity matrix.

Xfm

NAME

vgl_XfmInvert - invert the current matrix

C SPECIFICATION

    void vgl_XfmInvert (vgl_Xfm *xfm)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_COMPUTE is generated if the matrix is singular.

DESCRIPTION

Invert the current matrix.

Xfm

NAME

vgl_XfmLookAt - create a viewing matrix

C SPECIFICATION

    void vgl_XfmLookAt (vgl_Xfm *xfm,
                        Vfloat ex, Vfloat ey, Vfloat ez,
                        Vfloat cx, Vfloat cy, Vfloat cz,
                        Vfloat ux, Vfloat uy, Vfloat uz)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    ex,ey,ez     Coordinates of eye point.
    cx,cy,cz     Coordinates of reference point.
    ux,uy,uz     Direction of up vector

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_COMPUTE is generated if the coordinates of the eye and reference points are coincident, if the up vector length is zero or if the up vector is parallel to the line of sight.

DESCRIPTION

Create a viewing matrix defined by the position of the eye, the position of a reference point and the direction of an up vector. The viewing matrix maps the coordinates of the eye to the origin and the negative z-axis (the line of sight) to the reference point. The up vector is mapped to the y-axis so that it points directly upward in the viewport.

Xfm

NAME

vgl_XfmMult - multiply two viewing matrices

C SPECIFICATION

    void vgl_XfmMult (vgl_Xfm *xfm,
                      vgl_Xfm *xfmmult)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    xfmmult      Pointer to Xfm object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Precontatenate xfm by xfmmult.

    xfm = xfmmult * xfm

Xfm

NAME

vgl_XfmPurge - purge matrix of rotation, translation or scale

C SPECIFICATION

    void vgl_XfmPurge (vgl_Xfm *xfm,
                       Vint type)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    type         Specify type of component to purge
                 =XFM_ROTATE    Diagonalize rotation submatrix
                 =XFM_TRANSLATE Zero translation components
                 =XFM_SCALE     Set scaling to unity

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Purge a matrix of the rotation, translation or scaling components. This function is useful, for example, for generating a model view matrix for drawing an orientation triad which only represents the rotation applied to an object.

Xfm

NAME

vgl_XfmRotate - create a rotation matrix

C SPECIFICATION

    void vgl_XfmRotate (vgl_Xfm *xfm,
                        Vfloat angle,
                        Vint axis)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    angle        Angle of rotation in radians.
    axis         Specify axis of rotation.
                 =XFM_XAXIS    Rotate about x axis.
                 =XFM_YAXIS    Rotate about y axis.
                 =XFM_ZAXIS    Rotate about z axis.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_ENUM is generated if an improper axis is specified.

DESCRIPTION

Create a rotation matrix. A positive angle assumes a right hand rotation about the specified axis.

Xfm

NAME

vgl_XfmRotateEuler - create rotation matrix given Euler angles

C SPECIFICATION

    void vgl_XfmRotateEuler (vgl_Xfm *xfm,
                             Vfloat anglex, Vfloat angley, Vfloat anglez)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    anglex       Angle of rotation in radians about initial x axis.
    angley       Angle of rotation in radians about rotated y' axis.
    anglez       Angle of rotation in radians about rotated z'' axis.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Create a rotation matrix given a set of three Euler angles. The rotations are applied in order anglex about the initial x axis, followed by angley about the rotated y' axis followed by anglez about the rotated z'' axis. A positive angle assumes a right hand rotation about the specified axis. Compute the euler angles of a rotation matrix using vgl_XfmComputeRotateEuler.

Xfm

NAME

vgl_XfmRotateVector - create a rotation matrix about a vector

C SPECIFICATION

    void vgl_XfmRotateVector (vgl_Xfm *xfm,
                              Vfloat angle,
                              Vfloat vx, Vfloat vy, Vfloat vz)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    angle        Angle of rotation in radians.
    vx,vy,vz     Direction of vector.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_COMPUTE is generated if the vector length is zero.

DESCRIPTION

Create a rotation matrix about an arbitrary vector directed from the origin through the point (vx,vy,vz). A positive angle assumes a right hand rotation about the specified vector. Compute the angle and axis of a rotation matrix using vgl_XfmComputeRotateVector.

Xfm

NAME

vgl_XfmScale - create a scaling matrix

C SPECIFICATION

    void vgl_XfmScale (vgl_Xfm *xfm,
                       Vfloat sx, Vfloat sy, Vfloat sz)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    sx,sy,sz     Scale factors along x,y and x axes

OUTPUT ARGUMENTS

    None

DESCRIPTION

Create a scaling matrix. A scale factor of unity results in no scaling about the associated axis. A scale factor of zero will result in a graphics object being shrunk to either a single pixel along the associated axis or completely vanishing.

Xfm

NAME

vgl_XfmSetMatrix - create user defined matrix

C SPECIFICATION

    void vgl_XfmSetMatrix (vgl_Xfm *xfm,
                           Vfloat matrix4x4[4][4])

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    matrix4x4    User defined 4 by 4 transformation matrix

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set a user defined transformation matrix in a Xfm object. By convention matrix4x4 is dimensioned matrix4x4[columns][rows].

Get matrix4x4 as an output argument using

         void vgl_XfmGetMatrix (vgl_Xfm *xfm,
                                Vfloat matrix4x4[4][4])

Xfm

NAME

vgl_XfmTranslate - create a translation matrix

C SPECIFICATION

    void vgl_XfmTranslate (vgl_Xfm *xfm,
                           Vfloat tx, Vfloat ty, Vfloat tz)

INPUT ARGUMENTS

    xfm          Pointer to Xfm object.
    tx,ty,tz     Translation along x,y and z axes

OUTPUT ARGUMENTS

    None

DESCRIPTION

Create a translation matrix.

4.3 Transformation Stack - Xfmstack

The Xfmstack module consists of a stack of 4 x 4 transformation matrices and a 2 x 2 viewport mapping rectangle to implement the transformation from world or object coordinates to device or window coordinates. The Xfmstack module maintains a stack of 32 Xfm objects to generate the modelling transformation or "modelview" matrix, a single Xfm object for the projection matrix and a single 2 x 2 integer array for the viewport mapping. The functions associated with a Xfmstack object are the following.

Begin and end an instance of an object, generic object functions

    *vgl_XfmstackBegin      - create an instance of a Xfmstack object
    vgl_XfmstackEnd         - destroy an instance of a Xfmstack object
    vgl_XfmstackError       - return Xfmstack object error flag

Matrix stack manipulation, projection

    vgl_XfmstackLoad        - load a modelview matrix onto stack
    vgl_XfmstackMult        - multiply a modelview matrix onto stack
    vgl_XfmstackPop         - pop the modelview matrix stack
    vgl_XfmstackPush        - push the modelview matrix stack
    vgl_XfmstackProj        - load the projection matrix
    vgl_XfmstackProject     - transform to device coordinates
    vgl_XfmstackProjPop     - pop the projection matrix stack
    vgl_XfmstackProjPush    - push the projection matrix stack
    vgl_XfmstackUnproject   - transform to world coordinates
    vgl_XfmstackSetViewport - set the viewport rectangle
                GetViewport - get the viewport rectangle

Use the Xfm module to create modelview and projection matrices.

To use an Xfmstack object to project world coordinates to device coordinates and vice versa, use the XfmstackProject and XfmstackUnproject functions respectively. The complete viewing transformation must be set in the Xfmstack object before the projections may be performed. First the 4x4 transformation matrices representing the modelview and projection transformations must be obtained from the graphics device interface object using the vgl_DrawFunGetFloat function. Place the matrices in an Xfm object and set into the Xfmstack object using XfmstackLoad and XfmstackProj. Second query the viewport using vgl_DrawFunGetInteger. Set the viewport device coordinate limits into the Xfmstack object using XfmstackSetViewport.

4.4 Function Descriptions

The currently available Xfm functions are described in detail in this section.

Xfmstack

NAME

*vgl_XfmstackBegin - create an instance of an Xfmstack object

C SPECIFICATION

    vgl_Xfmstack *vgl_XfmstackBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Xfmstack object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of an Xfmstack object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a Xfmstack object using

         void vgl_XfmstackEnd (vgl_Xfmstack *xfmstack)

Return the current value of a Xfmstack object error flag using

         Vint vgl_XfmstackError (vgl_Xfmstack *xfmstack)

Xfmstack

NAME

vgl_XfmstackLoad,vgl_XfmstackMult - load and multiply the modelview matrix

C SPECIFICATION

    void vgl_XfmstackLoad (vgl_Xfmstack *xfmstack,
                           vgl_Xfm *xfm)
    
    void vgl_XfmstackMult (vgl_Xfmstack *xfmstack,
                           vgl_Xfm *xfm)

INPUT ARGUMENTS

    xfmstack      Pointer to Xfmstack object.
    xfm           Pointer to Xfm object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

vgl_XfmstackLoad loads xfm onto the top of the modelview matrix stack replacing the current matrix. This operation makes a copy of the matrix contained in the xfm object. vgl_XfmstackMult pre multiplies xfm by the current modelview matrix. The result replaces the current matrix.

Xfmstack

NAME

vgl_XfmstackPop,vgl_XfmstackPush - pop and push modelview transformation stack

C SPECIFICATION

    void vgl_XfmstackPop (vgl_Xfmstack *xfmstack)
    
    void vgl_XfmstackPush (vgl_Xfmstack *xfmstack)

INPUT ARGUMENTS

    xfmstack     Pointer to Xfmstack object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_UNDERFLOW is generated by vgl_XfmstackPop if the modelview matrix stack contains one matrix. VGL_ERROR_OVERFLOW is generated by vgl_XfmstackPush if the modelview matrix stack contains XFMSTACK_MAX matrices.

DESCRIPTION

Push and pop the modelview transformation stack. The vgl_XfmstackPush function pushes the modelview matrix stack, duplicating the top matrix. The vgl_XfmstackPop function pops the modelview matrix stack, replacing the top matrix with the one below it. The modelview matrix stack is at least 32 deep. The modelview transformation stack initially contains the identity matrix.

Xfmstack

NAME

vgl_XfmstackProj - load current projection matrix

C SPECIFICATION

    void vgl_XfmstackProj (vgl_Xfmstack *xfmstack,
                           vgl_Xfm *xfm)

INPUT ARGUMENTS

    xfmstack      Pointer to Xfmstack object.
    xfm           Pointer to Xfm object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Load xfm as the current projection matrix. This operation makes a copy of the matrix contained in the xfm object.

Xfmstack

NAME

vgl_XfmstackProject,vgl_XfmstackUnproject - transform device coordinates

C SPECIFICATION

    void vgl_XfmstackProject (vgl_Xfmstack *xfmstack,
                              Vfloat wx, Vfloat wy, Vfloat wz,
                              Vfloat *dx, Vfloat *dy, Vfloat *dz)
    
    void vgl_XfmstackUnproject (vgl_Xfmstack *xfmstack,
                                Vfloat dx, Vfloat dy, Vfloat dz,
                                Vfloat *wx, Vfloat *wy, Vfloat *wz)

INPUT ARGUMENTS

    xfmstack     Pointer to Xfmstack object.
    wx,wy,wz     World or object coordinates.
    dx,dy,dz     Device or window coordinates

OUTPUT ARGUMENTS

    dx,dy,dz     Device or window coordinates
    wx,wy,wz     World or object coordinates.

ERRORS

VGL_ERROR_COMPUTE is generated by vgl_XfmstackUnproject if the modelview matrix matrix is singular.

DESCRIPTION

vgl_XfmstackProject transforms the specified world coordinate to device coordinates using the current modelling, projection and viewport transformations. vgl_XfmstackUnproject performs the inverse operation transforming device coordinates to world coordinates. The modelview and projection matrices and viewport device coordinates must have been previously set using XfmstackLoad, XfmstackProj and XfmstackSetViewport respectively.

Xfmstack

NAME

vgl_XfmstackProjPop,vgl_XfmstackProjPush - pop and push projection matrix stack

C SPECIFICATION

    void vgl_XfmstackProjPop (vgl_Xfmstack *xfmstack)
    
    void vgl_XfmstackProjPush (vgl_Xfmstack *xfmstack)

INPUT ARGUMENTS

    xfmstack     Pointer to Xfmstack object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_UNDERFLOW is generated by vgl_XfmstackProjPop if the projection matrix stack contains one matrix. VGL_ERROR_OVERFLOW is generated by vgl_XfmstackProjPush if the projection matrix stack contains two matrices.

DESCRIPTION

Push and pop the projection matrix stack. The vgl_XfmstackProjPush function pushes the projection matrix stack, duplicating the top matrix. The vgl_XfmstackProjPop function pops the projection matrix stack, replacing the top matrix with the one below it. The projection matrix stack initially contains the identity matrix. The projection matrix stack is at least 32 deep.

Xfmstack

NAME

vgl_XfmstackSetViewport - set the viewport rectangle

C SPECIFICATION

    void vgl_XfmstackSetViewport (vgl_Xfmstack *xfmstack,
                                  Vint left, Vint right,
                                  Vint bottom, Vint top)

INPUT ARGUMENTS

    xfmstack     Pointer to Xfmstack object.
    left, right  Device coordinates of left and right planes of viewing volume
    bottom, top  Device coordinates of bottom and top planes of viewing volume

OUTPUT ARGUMENTS

    None

DESCRIPTION

Define the viewport transformation. The specified viewport transformation replaces the current viewport transformation. vgl_XfmstackSetViewport specifies the mapping of the horizontal and vertical bounds of the viewing volume to a rectangular area in device coordinates. Note that the window device coordinate limits are [0,width-1] and [0,height-1] where width and height are the dimensions of the window in pixels. Initially the viewport rectangle is set to zeros.

Get left, right, bottom, top as an output arguments using

         void vgl_XfmstackGetViewport (vgl_Xfmstack *xfmstack,
                                       Vint *left, Vint *right,
                                       Vint *bottom, Vint *top)