2.10.2 Matrices

The projection matrix and model-view matrix are set and modified with a variety of commands. The affected matrix is determined by the current matrix mode. The current matrix mode is set with

void MatrixMode ( enum mode ) ;

which takes one of the three pre-defined constants TEXTURE, MODELVIEW, or PROJECTION as the argument value. TEXTURE is described later. If the current matrix mode is MODELVIEW, then matrix operations apply to the model-view matrix; if PROJECTION, then they apply to the projection matrix.

The two basic commands for affecting the current matrix are

void LoadMatrix[fd] ( T m[16] ) ;
void MultMatrix[fd] ( T m[16] ) ;

LoadMatrix  takes a pointer to a matrix stored in column-major order as 16 consecutive floating-point values, i.e. as

(This differs from the standard row-major C ordering for matrix elements. If the standard ordering is used, all of the subsequent transformation equations are transposed, and the columns representing vectors become rows.)

The specified matrix replaces the current matrix with the one pointed to. MultMatrix  takes the same type argument as LoadMatrix , but multiplies the current matrix by the one pointed to and replaces the current matrix with the product. If C is the current matrix and M is the matrix pointed to by MultMatrix 's argument, then the resulting current matrix, , is

The command

void LoadIdentity ( void ) ;

effectively calls LoadMatrix  with the identity matrix:

There are a variety of other commands that manipulate matrices. Rotate , Translate , Scale , Frustum , and Ortho  manipulate the current matrix. Each computes a matrix and then invokes MultMatrix  with this matrix. In the case of

void Rotate[fd] ( T , T x, T y, T z ) ;

gives an angle of rotation in degrees; the coordinates of a vector are given by . The computed matrix is a counter-clockwise rotation about the line through the origin with the specified axis when that axis is pointing up (i.e. the right-hand rule determines the sense of the rotation angle). The matrix is thus

Let . If

then

The arguments to

void Translate[fd] ( T x, T y, T z ) ;

give the coordinates of a translation vector as . The resulting matrix is a translation by the specified vector:

void Scale[fd] ( T x, T y, T z ) ;

produces a general scaling along the x-, y-, and z- axes. The corresponding matrix is

For

void Frustum ( double l, double r, double b, double t, double n, double f ) ;

the coordinates and specify the points on the near clipping plane that are mapped to the lower-left and upper-right corners of the window, respectively (assuming that the eye is located at ). gives the distance from the eye to the far clipping plane. If either or is less than or equal to zero, is equal to , is equal to , or is equal to , the error INVALID_VALUE results. The corresponding matrix is

void Ortho ( double l, double r, double b, double t, double n, double f ) ;

describes a matrix that produces parallel projection. and specify the points on the near clipping plane that are mapped to the lower-left and upper-right corners of the window, respectively. f gives the distance from the eye to the far clipping plane. If is equal to , is equal to , or is equal to , the error INVALID_VALUE results. The corresponding matrix is

There is another matrix that is applied to texture coordinates. This matrix is applied as

where the left matrix is the current texture matrix. The matrix is applied to the coordinates resulting from texture coordinate generation (which may simply be the current texture coordinates), and the resulting transformed coordinates become the texture coordinates associated with a vertex. Setting the matrix mode to TEXTURE causes the already described matrix operations to apply to the texture matrix.

There is a stack of matrices for each of the matrix modes. For MODELVIEW mode, the stack depth is at least 32 (that is, there is a stack of at least 32 model-view matrices). For the other modes, the depth is at least 2. The current matrix in any mode is the matrix on the top of the stack for that mode.

void PushMatrix ( void ) ;

pushes the stack down by one, duplicating the current matrix in both the top of the stack and the entry below it.

void PopMatrix ( void ) ;

pops the top entry off of the stack, replacing the current matrix with the matrix that was the second entry in the stack. The pushing or popping takes place on the stack corresponding to the current matrix mode. Popping a matrix off a stack with only one entry generates the error STACK_UNDERFLOW; pushing a matrix onto a full stack generates STACK_OVERFLOW.

The state required to implement transformations consists of a three-valued integer indicating the current matrix mode, a stack of at least two matrices for each of PROJECTION and TEXTURE with associated stack pointers, and a stack of at least 32 matrices with an associated stack pointer for MODELVIEW. Initially, there is only one matrix on each stack, and all matrices are set to the identity. The initial matrix mode is MODELVIEW.