.TH gSPMatrix 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gSPMatrix, gsSPMatrix
\- matrix loading, concatenation and stack push
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

/*
 * 4x4 Matrix, Fixed point s15.16 format.
 * First 8 words are integer portion of 
 * the 4x4 matrix. Last 8 words are the 
 * fraction portion of the 4x4 matrix
 */

typedef long	Mtx_t[4][4];

typedef {
    Mtx_t		m;
    long long int	force_structure_alignment;
} Mtx;

gSPMatrix(Gfx *gdl, Mtx *matrix, unsigned char param)

gsSPMatrix(Mtx *matrix, unsigned char param)
\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I matrix
4x4 fixed point matrix (see note below about format).
.TP
.I param
parameters to the matrix command.
This is an inclusive-or of
\f3G_MTX_PROJECTION, G_MTX_MODELVIEW, G_MTX_MUL, G_MTX_LOAD, G_MTX_NOPUSH\fP
.SH DESCRIPTION
gSPMatrix inserts a matrix operation in the display list.
The parameters allows you to select which matrix stack to use (projection or modelview), where to load or concatenation, and whether to push the matrix stack.
These parameters are bit-ORed together and the meaning of each field are as follows:
.TP
.B G_MTX_PROJECTION G_MTX_MODELVIEW
whether the matrix operation will be performed on the projection or the
modelview matrix.
.TP
.B G_MTX_MUL
concatenate matrix m with the top of matrix stack.
.TP
.B G_MTX_LOAD
load matrix m onto the top of matrix stack.
.TP
.B G_MTX_NOPUSH
do not push the matrix stack prior to matrix operations.
.TP
.B G_MTX_PUSH
push the matrix stack prior to matrix operations.
.SH MATRIX FORMAT
The format of the fixed-point matrices may seem a little awkward to the
application programmer, since it is optimized for the RSP geometry engine.
This unusual format is hidden in the graphics utility libraries and
not normally exposed to the application programmer, but in some cases
(static matrix declarations or direct element manipulation) it is
necessary to understand the format.

The integer and fractional components of the matrix elements are separated.
The first 8 words (16 shorts) hold the 16-bit integer elements, the second 
8 words (16 shorts) hold the 16-bit fractional elements. That the
.B Mtx
type is declared as a
.B long [4][4]
array is slightly misleading.

For example, to declare a static identity matrix, the code would look like 
this:

.nf
\f3#include "gbi.h"
static Mtx ident =
{
	/* integer portion: */
	0x00010000, 0x00000000,
	0x00000001, 0x00000000,
	0x00000000, 0x00010000,
	0x00000000, 0x00000001,

	/* fractional portion: */
	0x00000000, 0x00000000,
	0x00000000, 0x00000000,
	0x00000000, 0x00000000,
	0x00000000, 0x00000000,
};
\fP
.fi

To force the translation elements of a matrix to be (10.5, 20.5, 30.5), the
code would look like this:

.nf
\f3#include "gbi.h"

	mat.m[1][2] = (10 << 16) | (20);
	mat.m[1][3] = (30 << 16) | (1);

	mat.m[3][2] = (0x8000 << 16) | (0x8000);
	mat.m[3][3] = (0x8000 << 16) | (0);
.fi

.SH NOTE
Matrix concatenation in the RSP geometry engine is done using 32 bit integer arithmatic.
A 32 x 32 bit multiply results in a 64 bit number.
Only the middle 32 bits of this 64 bit results are kept for the new matrix.
Therefore, when concatenating matrices, one should understand the resulting fixed point numerical error.
.PP
For example, to retain maximum precision, the number ranges must be similar. Large scale and translate parameters can decrease the transformation precision.
Since rotation and projection matricies require quite a bit of fractional accuracy, these fractions may get tossed out if multipled against large integer numbers. 
.PP
Another example is that each concatenation will result in the rounding of the LSB of each matrix term.
This means that each concatenation will inject 1/2 LSB of error into the matrix.
.PP
A method for keeping full precision is to concatenate matrices in floating point on the processor and just load the result into the RSP.
.SH PERFORMANCE
Each \f3G_MTX_MODELVIEW\fP matrix operation has an implicit matrix multiplication even if you specify \f3G_MTX_LOAD\fP.
This is the combined model view (M) and projection (P) matrix that is necessary for the vertex transformation to use a single matrix during transformation.
.PP
An optimization is to concatenate modeling matrices on the CPU, put the viewing (V) and projection matrices on the projection stack.
In this case, you will only incur the single MxVP matrix concatenation each time you load a modeling matrix.
Furthermore, the application has more information on how to do a cheap hack for modeling matrix concatenation.
For example, if you want to combine a single axis rotation with a translation. You can just place the coefficients in the correct entries of the resulting matrix.
.PP
.SH SEE ALSO
.IR gSPPopMatrix (3P),
.IR gSPPerspNormalize (3P)
.IR gSPInsertMatrix (3P)
.IR gSPForceMatrix (3P)