.TH gSPInsertMatrix 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gSPInsertMatrix, gsSPInsertMatrix
\- Modify elements of a matrix without multiplications.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gSPInsertMatrix(Gfx *gdl, unsigned int where, unsigned int num)

gsSPInsertMatrix(unsigned int where, unsigned int num)
\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I where
specifies which 2 elements of the matrix to modify. Should be one of:
			G_MWO_MATRIX_XX_XY_I
			G_MWO_MATRIX_XZ_XW_I
			G_MWO_MATRIX_YX_YY_I
			G_MWO_MATRIX_YZ_YW_I
			G_MWO_MATRIX_ZX_ZY_I
			G_MWO_MATRIX_ZZ_ZW_I
			G_MWO_MATRIX_WX_WY_I
			G_MWO_MATRIX_WZ_WW_I
			G_MWO_MATRIX_XX_XY_F
			G_MWO_MATRIX_XZ_XW_F
			G_MWO_MATRIX_YX_YY_F
			G_MWO_MATRIX_YZ_YW_F
			G_MWO_MATRIX_ZX_ZY_F
			G_MWO_MATRIX_ZZ_ZW_F
			G_MWO_MATRIX_WX_WY_F
			G_MWO_MATRIX_WZ_WW_F
.TP
.I num
The new values of the elements.  This should be a 32 bit integer.  The
high 16 bits will replace the 1st element described by the
.I where
parameter, and the low 16 bits will replace the 2nd element.



.SH DESCRIPTION
This is an advanced command.  A good understanding of how
matrices work in the RSP microcode is suggested before using
this command (see 
.I gSPMatrix (3P)).
.PP
This command replaces 2 elements of the concatenated MODELVIEW 
and PROJECTION matrix with 2 new numbers (supplied in the 
.I num
parameter).  Due to the internal format of the RSP's Matrices (see
.I gSPMatrix (3P)),
elements of the matrix can only be modified in pairs.  It
is important to understand that the matrix which is being modified 
is the concatenated MODELVIEW and PROJECTION matrix, and that no
matrix multiplication is performed after the 
.I gSPInsertMatrix
command.  No matrix pushes or pops are performed, and the top of the
MODELVIEW and PROJECTION matrix stacks are untouched.
If this command is
followed by a
.I gSPMatrix
(3P) command then the matrix elements modified by
.I gSPInsertMatrix
will be lost and will not affect the new matrix on the RSP (as if the
.I gSPInsertMatrix
command had never been sent).
.PP
The elements which get replaced are specified by the
.I where
parameter.  To modify an element completely you must modify both the
integer and fractional part of the matrix.  See the note on Matrix Format
in the
.I gSPMatrix(3P)
man page for more information.  Values for the where parameter are:
.PD 0
.RS 3
G_MWO_MATRIX_XX_XY_I   xscale and xy components (integer)
.PP
G_MWO_MATRIX_XX_XY_F   xscale and xy components (frac)
.PP
G_MWO_MATRIX_XZ_XW_I   xz and xw components (integer)
.PP
G_MWO_MATRIX_XZ_XW_F   xz and xw components (frac)
.PP
G_MWO_MATRIX_YX_YY_I   yx and yscale components (integer)
.PP
G_MWO_MATRIX_YX_YY_F   yx and yscale components (frac)
.PP
G_MWO_MATRIX_YZ_YW_I   yz and yw components (integer)
.PP
G_MWO_MATRIX_YZ_YW_F   yz and yw components (frac)
.PP
G_MWO_MATRIX_ZX_ZY_I   zx and zy components (integer)
.PP
G_MWO_MATRIX_ZX_ZY_F   zx and zy components (frac)
.PP
G_MWO_MATRIX_ZZ_ZW_I   zscale and zw components (integer)
.PP
G_MWO_MATRIX_ZZ_ZW_F   zscale and zw components (frac)
.PP
G_MWO_MATRIX_WX_WY_I   x and y translate components(integer)
.PP
G_MWO_MATRIX_WX_WY_F   x and y translate components(frac)
.PP
G_MWO_MATRIX_WZ_WW_I   z translate and wscale components(integer)
.PP
G_MWO_MATRIX_WZ_WW_F   z translate and wscale components(frac)

.PD 1
.RE

.SH IMPORTANT NOTE
The 
.I gSPInsertMatrix (3P)
command does not affect lighting.  Therefore, if you are using lighting
and you use the 
.I gSPInsertMatrix (3P)
command, the lights will act on a rendered object according to the
RSP's matrix state preceding the
.I gSPInsertMatrix (3P)
command, but the object's position and orientation will be affected by
the changes to the matrix made by the
.I gSPInsertMatrix (3P)
command.


.SH MATRIX FORMAT
Please see the note on Matrix Format in the
.I gSPMatrix (3P)
man page.

.SH EXAMPLE
To modify the x and y translate terms of a matrix to be 
20.5 and 15.25 (respectively) do:
.Ex

gSPInsertMatrix(glistp++, G_MWO_MATRIX_WX_WY_I, 0x0014000f);
gSPInsertMatrix(glistp++, G_MWO_MATRIX_WX_WY_F, 0x80004000);

.Ee

.SH SEE ALSO
.IR gSPMatrix (3P),
.IR gSPForceMatrix (3P)