N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

   

gSPInsertMatrix

Format
#include "gbi.h"

gSPInsertMatrix(Gfx *gdl,
   unsigned int where,
   unsigned int num)
gsSPInsertMatrix(unsigned int where,
   unsigned int num)
Arguments
  • gdl is the pointer to the graphics display list
  • where is one of the following values that specifies which two elements of the matrix to modify:

    • 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

  • num gives the new values for the elements. It is a 32-bit integer. The high 16 bits replace the first element described by the where argument, and the low 16 bits replace the second element described by the where argument
What This Macro Does
This is an advanced macro. You need to have a good understanding of how matrices work in the RSP microcode before you use this macro (see gSPMatrix).

This macro replaces two elements of the concatenated MODELVIEW and PROJECTION matrix with two new numbers (supplied in the num parameter). Due to the internal format of the RSP's Matrices (see gSPMatrix), elements of the matrix can only be modified in pairs. It is important to understand that the matrix being modified is the concatenated MODELVIEW and PROJECTION matrix, and that no matrix multiplication is performed after the gSPInsertMatrix macro. No matrix pushes or pops are performed, and the top of the MODELVIEW and PROJECTION matrix stacks are untouched. If this macro is followed by a gSPMatrix macro, the matrix elements modified by gSPInsertMatrix will be lost and will not affect the new matrix on the RSP; it will be as if the gSPInsertMatrix macro had never been sent.

The replaced elements are specified by the where argument. 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 gSPMatrix page for more information. Values for the where argument are:
  • G_MWO_MATRIX_XX_XY_I - xscale and xy components (integer)
  • G_MWO_MATRIX_XX_XY_F - xscale and xy components (frac)
  • G_MWO_MATRIX_XZ_XW_I - xz and xw components (integer)
  • G_MWO_MATRIX_XZ_XW_F - xz and xw components (frac)
  • G_MWO_MATRIX_YX_YY_I - yx and yscale components (integer)
  • G_MWO_MATRIX_YX_YY_F - yx and yscale components (frac)
  • G_MWO_MATRIX_YZ_YW_I - yz and yw components (integer)
  • G_MWO_MATRIX_YZ_YW_F - yz and yw components (frac)
  • G_MWO_MATRIX_ZX_ZY_I - zx and zy components (integer)
  • G_MWO_MATRIX_ZX_ZY_F - zx and zy components (frac)
  • G_MWO_MATRIX_ZZ_ZW_I - zscale and zw components (integer)
  • G_MWO_MATRIX_ZZ_ZW_F - zscale and zw components (frac)
  • G_MWO_MATRIX_WX_WY_I - x and y translate components (integer)
  • G_MWO_MATRIX_WX_WY_F - x and y translate components (frac)
  • G_MWO_MATRIX_WZ_WW_I - z translate and wscale components (integer)
  • G_MWO_MATRIX_WZ_WW_F - z translate and wscale components (frac)
Important Note
The gSPInsertMatrix macro does not affect lighting. Therefore, if you are using lighting and you use the gSPInsertMatrix macro, the lights will act on a rendered object according to the RSP's matrix state preceding the gSPInsertMatrix macro, but the object's position and orientation will be affected by the changes to the matrix made by the gSPInsertMatrix macro.

Matrix Format
Please see the note on Matrix Format in the gSPMatrix page.

Example
To modify the x and y translate terms of a matrix to be 20.5 and 15.25 (respectively), use this code:
gSPInsertMatrix(glistp++,
   G_MWO_MATRIX_WX_WY_I,
   0x0014000f);
gSPInsertMatrix(glistp++,
   G_MWO_MATRIX_WX_WY_F,
   0x80004000);
See Also
gSPMatrix
gSPForceMatrix



Nintendo® Confidential

Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.


Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated January 1998