4. Coordinate Transformations - Xfm,Xfmstack

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.

Table of Contents

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.

Table of Contents

4.2 Function Descriptions

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

Table of Contents , 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)

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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])

Table of Contents , 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.

Table of Contents

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.

Table of Contents

4.4 Function Descriptions

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

Table of Contents , 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)

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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)