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.
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
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 objectC 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 matrixC 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 matrixC 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 matrixC 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 matrixC 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 matrixC 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 matricesC 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 scaleC 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 matrixC 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 anglesC 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 vectorC 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 matrixC 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 matrixC 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 matrixC 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
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 objectC 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 matrixC 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 stackC 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 matrixC 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 coordinatesC 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 stackC 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 rectangleC 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)