The SGADE Documentation

the SGADE The Socrates Gameboy Advance Development Engine

The SGADE is a development library for the Nintendo Gameboy Advance. It's free for all uses and is distributed without guarantees. For more information visit the SGADE page.

Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

SoMatrix

Matrix structure definition. More...

Files

file  SoMatrix.c
file  SoMatrix.h

Data Structures

struct  SoMatrix
 Matrix definition. More...


Functions

void SoMatrixMakeIdentity (SoMatrix *a_This)
 Makes the given matrix an identity matrix.

void SoMatrixMakeRotationX (SoMatrix *a_This, s32 a_Angle)
 Makes the given matrix an rotational matrix around the X-axis.

void SoMatrixMakeRotationY (SoMatrix *a_This, s32 a_Angle)
 Makes the given matrix an rotational matrix around the Y-axis.

void SoMatrixMakeRotationZ (SoMatrix *a_This, s32 a_Angle)
 Makes the given matrix an rotational matrix around the Z-axis.

void SoMatrixSetTranslation (SoMatrix *a_This, sofixedpoint a_X, sofixedpoint a_Y, sofixedpoint a_Z)
 Sets the translational part of the matrix.

void SoMatrixScale (SoMatrix *a_This, sofixedpoint a_ScaleX, sofixedpoint a_ScaleY, sofixedpoint a_ScaleZ)
 Non-uniformly scales the matrix.

void SoMatrixMultiplyBy (SoMatrix *a_This, SoMatrix *a_Matrix)
 Multiplies the matrix by another matrix.

void SoMatrixMultiply (SoMatrix *a_This, SoMatrix *a_A, SoMatrix *a_B)
 Multiplies two matrices, placing the result into this.

void SoMatrixMode4DebugDraw (SoMatrix *a_This)
 Prints the matrix elements on the screen for debugging purposes. Only works in mode 4.

Detailed Description

Matrix structure definition.

This module contains the matrix definition and all its methods.

To save memory we use a 3 row, 4 column matrix system. The missing 4th row is assumed to contain [0, 0, 0, 1]. This works because we only support homogeneous transforms (rotations, translations and uniform scales).

All cells in a matrix are in fixed point format.

Note that you rarely need to work with matrices. You should use the SoTransform structure instead, because it is better in dealing with accumulating precision problems. Even in the best case, if you multiply two orthogonal matrices a few hundred times, you can be sure they won't be orthogonal anymore. This is even worse with a fixed-point number system as the errors crop up much faster.

Function Documentation

void SoMatrixMakeIdentity (  SoMatrix *    a_This ) 
 

Makes the given matrix an identity matrix.

Parameters:
a_This  This pointer

void SoMatrixMakeRotationX (  SoMatrix *    a_This,
s32    a_Angle
) 
 

Makes the given matrix an rotational matrix around the X-axis.

Parameters:
a_This  This pointer
a_Angle  Angle. A full circle is 256 degrees.

void SoMatrixMakeRotationY (  SoMatrix *    a_This,
s32    a_Angle
) 
 

Makes the given matrix an rotational matrix around the Y-axis.

Parameters:
a_This  This pointer
a_Angle  Angle. A full circle is 256 degrees.

void SoMatrixMakeRotationZ (  SoMatrix *    a_This,
s32    a_Angle
) 
 

Makes the given matrix an rotational matrix around the Z-axis.

Parameters:
a_This  This pointer
a_Angle  Angle. A full circle is 256 degrees.

void SoMatrixMode4DebugDraw (  SoMatrix *    a_This ) 
 

Prints the matrix elements on the screen for debugging purposes. Only works in mode 4.

Parameters:
a_This  This pointer
Simply prints the 12 elements on the screen in fixed point format. You have to do a fixed to float conversion yourself (if you want any information about wholes and fractions).

Warning:
You should already be in mode 4 for this to work.

void SoMatrixMultiply (  SoMatrix *    a_This,
SoMatrix *    a_A,
SoMatrix *    a_B
) 
 

Multiplies two matrices, placing the result into this.

Parameters:
a_This  This pointer
a_A  Matrix A
a_B  Matrix B
Performs the calculation a_This = a_A * a_B.

Todo:
Probably worth optimizing in assembly.

void SoMatrixMultiplyBy (  SoMatrix *    a_This,
SoMatrix *    a_Matrix
) 
 

Multiplies the matrix by another matrix.

Parameters:
a_This  This pointer
a_Matrix  Matrix to multiply by.
Performs the calculation a_This = a_This * a_Matrix.

Todo:
Probably worth optimizing in assembly.

void SoMatrixScale (  SoMatrix *    a_This,
sofixedpoint    a_ScaleX,
sofixedpoint    a_ScaleY,
sofixedpoint    a_ScaleZ
) 
 

Non-uniformly scales the matrix.

Parameters:
a_This  This pointer
a_ScaleX  Fixed point scale value. X component.
a_ScaleY  Fixed point scale value. Y component.
a_ScaleZ  Fixed point scale value. Z component.
This function scales the given matrix. It leaves any existing rotation and translation in tact.

Todo:
Can this even work this simple? Test whether this works.

void SoMatrixSetTranslation (  SoMatrix *    a_This,
sofixedpoint    a_X,
sofixedpoint    a_Y,
sofixedpoint    a_Z
) 
 

Sets the translational part of the matrix.

Parameters:
a_This  This pointer
a_X  X part of the translation
a_Y  Y part of the translation
a_Z  Z part of the translation
This function only sets the last column of the matrix (which represents the translation). It leaves the rest of the matrix intact.

Copyright 2002 by the SGADE authors. See SoLicense.h or Visit the SGADE page for more information.