libogc  v2.9.0
Data Structures | Macros | Typedefs | Functions
gu.h File Reference

GU/Matrix subsystem. More...

#include <gctypes.h>

Data Structures

struct  _qrtn
 
struct  _vecf
 

Macros

#define DegToRad(a)   ( (a) * 0.01745329252f )
 
#define FIX32TOF(x)   ((f32)(x) * (1.0f / (f32)0x00010000))
 
#define FTOFIX32(x)   (s32)((x) * (f32)0x00010000)
 
#define FTOFRAC8(x)   ((s32) MIN(((x) * (128.0f)), 127.0f) & 0xff)
 
#define guMtx44Concat   c_guMtx44Concat
 
#define guMtxApplyScale   c_guMtxApplyScale
 
#define guMtxApplyTrans   c_guMtxApplyTrans
 
#define guMtxConcat   c_guMtxConcat
 
#define guMtxCopy   c_guMtxCopy
 
#define guMtxIdentity   c_guMtxIdentity
 
#define guMtxInverse   c_guMtxInverse
 
#define guMtxInvXpose   c_guMtxInvXpose
 
#define guMtxQuat   c_guMtxQuat
 
#define guMtxReflect   c_guMtxReflect
 
#define guMtxRotAxisDeg(mt, axis, deg)   guMtxRotAxisRad(mt,axis,DegToRad(deg))
 
#define guMtxRotAxisRad   c_guMtxRotAxisRad
 
#define guMtxRotDeg(mt, axis, deg)   guMtxRotRad(mt,axis,DegToRad(deg))
 
#define guMtxRotRad   c_guMtxRotRad
 
#define guMtxRotTrig   c_guMtxRotTrig
 
#define guMtxRowCol(mt, row, col)   (mt[row][col])
 Provides storage-safe access to elements of Mtx and Mtx44. More...
 
#define guMtxScale   c_guMtxScale
 
#define guMtxScaleApply   c_guMtxScaleApply
 
#define guMtxTrans   c_guMtxTrans
 
#define guMtxTransApply   c_guMtxTransApply
 
#define guMtxTranspose   c_guMtxTranspose
 
#define guQuatAdd   c_guQuatAdd
 
#define guQuatInverse   c_guQuatInverse
 
#define guQuatMtx   c_guQuatMtx
 
#define guQuatMultiply   c_guQuatMultiply
 
#define guQuatNoramlize   c_guQuatNormalize
 
#define guQuatSub   c_guQuatSub
 
#define guVecAdd   c_guVecAdd
 
#define guVecCross   c_guVecCross
 
#define guVecDotProduct   c_guVecDotProduct
 
#define guVecMultiply   c_guVecMultiply
 
#define guVecMultiplySR   c_guVecMultiplySR
 
#define guVecNormalize   c_guVecNormalize
 
#define guVecScale   c_guVecScale
 
#define guVecSub   c_guVecSub
 
#define M_DTOR   (3.14159265358979323846/180.0)
 
#define M_PI   3.14159265358979323846
 
#define MAX(a, b)   (((a)>(b))?(a):(b))
 
#define MIN(a, b)   (((a)<(b))?(a):(b))
 
#define MTX_USE_C
 
#define RadToDeg(a)   ( (a) * 57.29577951f )
 

Typedefs

typedef struct _qrtn guQuaternion
 
typedef struct _vecf guVector
 
typedef f32 Mtx[3][4]
 Standard 3x4 matrix. More...
 
typedef f32 Mtx33[3][3]
 3x3 matrix.
 
typedef f32(* Mtx33P)[3]
 
typedef f32 Mtx44[4][4]
 4x4 matrix. More...
 
typedef f32(* Mtx44P)[4]
 
typedef f32(* MtxP)[4]
 
typedef f32 ROMtx[4][3]
 Column-major representation of the standard Mtx structure. More...
 
typedef f32(* ROMtxP)[3]
 

Functions

void c_guMtx44Concat (const Mtx44 a, const Mtx44 b, Mtx44 ab)
 
void c_guMtxApplyScale (const Mtx src, Mtx dst, f32 xS, f32 yS, f32 zS)
 
void c_guMtxApplyTrans (const Mtx src, Mtx dst, f32 xT, f32 yT, f32 zT)
 
void c_guMtxConcat (const Mtx a, const Mtx b, Mtx ab)
 
void c_guMtxCopy (const Mtx src, Mtx dst)
 
void c_guMtxIdentity (Mtx mt)
 
u32 c_guMtxInverse (const Mtx src, Mtx inv)
 
u32 c_guMtxInvXpose (const Mtx src, Mtx xPose)
 
void c_guMtxQuat (Mtx m, const guQuaternion *a)
 
void c_guMtxReflect (Mtx m, const guVector *p, const guVector *n)
 
void c_guMtxRotAxisRad (Mtx mt, guVector *axis, f32 rad)
 
void c_guMtxRotRad (Mtx mt, const char axis, f32 rad)
 
void c_guMtxRotTrig (Mtx mt, const char axis, f32 sinA, f32 cosA)
 
void c_guMtxScale (Mtx mt, f32 xS, f32 yS, f32 zS)
 
void c_guMtxScaleApply (const Mtx src, Mtx dst, f32 xS, f32 yS, f32 zS)
 
void c_guMtxTrans (Mtx mt, f32 xT, f32 yT, f32 zT)
 
void c_guMtxTransApply (const Mtx src, Mtx dst, f32 xT, f32 yT, f32 zT)
 
void c_guMtxTranspose (const Mtx src, Mtx xPose)
 
void c_guQuatAdd (const guQuaternion *a, const guQuaternion *b, guQuaternion *ab)
 
void c_guQuatInverse (const guQuaternion *a, guQuaternion *d)
 
void c_guQuatMtx (guQuaternion *a, const Mtx m)
 
void c_guQuatMultiply (const guQuaternion *a, const guQuaternion *b, guQuaternion *ab)
 
void c_guQuatNormalize (const guQuaternion *a, guQuaternion *d)
 
void c_guQuatSub (const guQuaternion *a, const guQuaternion *b, guQuaternion *ab)
 
void c_guVecAdd (const guVector *a, const guVector *b, guVector *ab)
 
void c_guVecCross (const guVector *a, const guVector *b, guVector *axb)
 
f32 c_guVecDotProduct (const guVector *a, const guVector *b)
 
void c_guVecMultiply (const Mtx mt, const guVector *src, guVector *dst)
 
void c_guVecMultiplySR (const Mtx mt, const guVector *src, guVector *dst)
 
void c_guVecNormalize (guVector *v)
 
void c_guVecScale (const guVector *src, guVector *dst, f32 scale)
 
void c_guVecSub (const guVector *a, const guVector *b, guVector *ab)
 
void guFrustum (Mtx44 mt, f32 t, f32 b, f32 l, f32 r, f32 n, f32 f)
 Sets a 4x4 perspective projection matrix from viewing volume dimensions. More...
 
void guLightFrustum (Mtx mt, f32 t, f32 b, f32 l, f32 r, f32 n, f32 scaleS, f32 scaleT, f32 transS, f32 transT)
 Sets a 3x4 perspective projection matrix from viewing volume dimensions, two scale values, and two translation values. More...
 
void guLightOrtho (Mtx mt, f32 t, f32 b, f32 l, f32 r, f32 scaleS, f32 scaleT, f32 transS, f32 transT)
 Sets a 3x4 matrix for orthographic projection. More...
 
void guLightPerspective (Mtx mt, f32 fovY, f32 aspect, f32 scaleS, f32 scaleT, f32 transS, f32 transT)
 Sets a 3x4 perspective projection matrix from field of view and aspect ratio parameters, two scale values, and two translation values. More...
 
void guLookAt (Mtx mt, const guVector *camPos, const guVector *camUp, const guVector *target)
 
void guMtx44Copy (const Mtx44 src, Mtx44 dst)
 
void guMtx44Identity (Mtx44 mt)
 
u32 guMtx44Inverse (const Mtx44 src, Mtx44 inv)
 
void guOrtho (Mtx44 mt, f32 t, f32 b, f32 l, f32 r, f32 n, f32 f)
 Sets a 4x4 matrix for orthographic projection. More...
 
void guPerspective (Mtx44 mt, f32 fovy, f32 aspect, f32 n, f32 f)
 Sets a 4x4 perspective projection matrix from field of view and aspect ratio parameters. More...
 
void guVecHalfAngle (const guVector *a, const guVector *b, guVector *half)
 

Detailed Description

GU/Matrix subsystem.

The GU/Matrix subsystem is used for many matrix- , vector- and quaternion-related operations.

The matrix functions are coupled tightly with GX (GX will take Mtx for many of its own matrix-related functions, for example). This library supports 3x3, 3x4, 4x3 and 4x4 matrices.

This library has functions for manipulating vectors as well; some of its functions are for transforming matrices using vectors.

It also includes functions for using and converting between quaternions. Although quaternions are not used natively in libogc, they work well with rotation functions as they aren't susceptible to "gimbal lock". You can use the appropriate functions to freely convert between quaternions and matrices.

Note
Many of the functions come in two flavors: C and "paired single". Both perform the same exact operations, but with a key difference: the C versions are written in pure C and are slightly more accurate, while the PS versions are hand-written assembly routines utilizing the Gekko's "paired-single" extension, which is much faster for almost every operation but slightly less accurate. When building for the GameCube or Wii (which is probably always), the library is configured to automatically use the paired-single tuned versions, as the speed difference is worth the accuracy hit. If you want to use the C routine and take the performance hit instead, prefix the function with "c_". You are not limited to using only one or the other collection; you can use both in your code if you wish.
Warning
Some functions (notably guFrustum() and related) take a 4x4 matrix, while the rest work only on 4x3 matrices. Make sure you are passing the correct matrix type to each function, as passing the wrong one can create subtle bugs.

Macro Definition Documentation

◆ guMtxRowCol

#define guMtxRowCol (   mt,
  row,
  col 
)    (mt[row][col])

Provides storage-safe access to elements of Mtx and Mtx44.

This macro provides storage-safe access to elements of Mtx and Mtx44. Matrix storage format is transparent to the programmer as long as matrices are initialized and manipulated exclusively with the matrix API. Do not initialize matrices when they are first declared and do not set values by hand. To insulate code from changes to matrix storage format, you should use this macro instead of directly accessing individual matrix elements.

Note
When using this function, think of the matrix in row-major format.
Parameters
[in]mtMatrix to be accessed.
[in]rRow index of element to access.
[in]cColumn index of element to access.
Returns
none

Typedef Documentation

◆ Mtx

f32 Mtx[3][4]

Standard 3x4 matrix.

Warning
Some functions take the 4x4 matrix type rather than this one, so make sure you don't mix up the two.

◆ Mtx44

f32 Mtx44[4][4]

4x4 matrix.

Warning
Some functions take this instead of the 3x4 matrix, so make sure you don't mix up the two.

◆ ROMtx

f32 ROMtx[4][3]

Column-major representation of the standard Mtx structure.

It is not a true transpose, as it is a 4x3 matrix. These structures are only accepted by functions that explicitly require reordered matrices.

Function Documentation

◆ guFrustum()

void guFrustum ( Mtx44  mt,
f32  t,
f32  b,
f32  l,
f32  r,
f32  n,
f32  f 
)

Sets a 4x4 perspective projection matrix from viewing volume dimensions.

This matrix is used by the GX API to transform points to screen space.

For normal perspective projection, the axis of projection is the -z axis, so t = positive, b = -t, r = positive, l = -r. n and f must both be given as positive distances.

Note
m negates a point's 'z' values, so pre-transformed points should have negative 'z' values in eye space in order to be visible after projection.
Parameters
[out]mtNew projection matrix.
[in]tTop edge of view volume at the near clipping plane.
[in]bBottom edge of view volume at the near clipping plane.
[in]lLeft edge of view volume at the near clipping plane.
[in]rRight edge of view volume at the near clipping plane.
[in]nPositive distance to the near clipping plane.
[in]fPositive distance to the far clipping plane.
Returns
none

◆ guLightFrustum()

void guLightFrustum ( Mtx  mt,
f32  t,
f32  b,
f32  l,
f32  r,
f32  n,
f32  scaleS,
f32  scaleT,
f32  transS,
f32  transT 
)

Sets a 3x4 perspective projection matrix from viewing volume dimensions, two scale values, and two translation values.

This matrix is used to project points into texture space and yield texture coordinates.

For normal perspective projection, the axis of projection is the -z axis, so t = positive, b = -t, r = positive, l = -r. n must be given as a positive distance.

Standard projection yields values ranging from -1.0 to 1.0 in both dimensions of the front clipping plane. Since texture coordinates usually should be within the range of 0.0 to 1.0, we have added a scale and translation value for both S and T. The most common usage of these values is to set all of them to 0.5 so that points in the range of -1.0 to 1.0 are first scaled by 0.5 to be in the range of -0.5 to 0.5, and are then translated by 0.5 to be in the range of 0.0 to 1.0. Other values can be used for translation and scale to yield different effects.

Parameters
[out]mtNew projection matrix.
[in]tTop edge of view volume at the near clipping plane.
[in]bBottom edge of view volume at the near clipping plane.
[in]lLeft edge of view volume at the near clipping plane.
[in]rRight edge of view volume at the near clipping plane.
[in]nPositive distance to the near clipping plane.
[in]scaleSScale in the S direction for projected coordinates (usually 0.5).
[in]scaleTScale in the T direction for projected coordinates (usually 0.5).
[in]transSTranslate in the S direction for projected coordinates (usually 0.5).
[in]transTTranslate in the T direction for projected coordinates (usually 0.5).
Returns
none

◆ guLightOrtho()

void guLightOrtho ( Mtx  mt,
f32  t,
f32  b,
f32  l,
f32  r,
f32  scaleS,
f32  scaleT,
f32  transS,
f32  transT 
)

Sets a 3x4 matrix for orthographic projection.

Use this matrix to project points into texture space and yield texture coordinates.

For normal parallel projections, the axis of projection is the -z axis, so t = positive, b = -t, r = positive, l = -r.

Standard projection yields values ranging from -1.0 to 1.0 in both dimensions of the front clipping plane. Since texture coordinates should usually be within the range of 0.0 to 1.0, we have added a scale and translation value for both S and T. The most common way to use these values is to set all of them to 0.5 so that points in the range of -1.0 to 1.0 are first scaled by 0.5 (to be in the range of -0.5 to 0.5). Then they are translated by 0.5 to be in the range of 0.0 to 1.0. Other values can be used for translation and scale to yield different effects.

Parameters
[out]mtNew parallel projection matrix.
[in]tTop edge of view volume.
[in]bBottom edge of view volume.
[in]lLeft edge of view volume.
[in]rRight edge of view volume.
[in]scaleSScale in the S direction for projected coordinates (usually 0.5).
[in]scaleTScale in the T direction for projected coordinates (usually 0.5).
[in]transSTranslate in the S direction for projected coordinates (usually 0.5).
[in]transTTranslate in the T direction for projected coordinates (usually 0.5).
Returns
none

◆ guLightPerspective()

void guLightPerspective ( Mtx  mt,
f32  fovY,
f32  aspect,
f32  scaleS,
f32  scaleT,
f32  transS,
f32  transT 
)

Sets a 3x4 perspective projection matrix from field of view and aspect ratio parameters, two scale values, and two translation values.

This matrix is used to project points into texture space and yield texture coordinates.

This function generates a projection matrix, equivalent to that created by guLightFrustum(), with the axis of projection centered around Z. This function is included to provide an alternative method of specifying texture projection volume dimensions.

The field of view (fovy) is the total field of view in degrees in the YZ plane. aspect is the ratio (width / height) of the view window in screen space.

Standard projection yields values ranging from -1.0 to 1.0 in both dimensions of the front clipping plane. Since texture coordinates should usually be within the range of 0.0 to 1.0, we have added a scale and translation value for both S and T. The most common way to use these values is to set all of them to 0.5 (so that points in the range of -1.0 to 1.0 are first scaled by 0.5) to be in the range of -0.5 to 0.5. Then they are translated by 0.5 to be in the range of 0.0 to 1.0. Other values can be used for translation and scale to yield different effects.

Parameters
[out]mtNew projection matrix.
[in]fovyTotal field of view in the YZ plane measured in degrees.
[in]aspectView window aspect ratio (width / height)
[in]scaleSScale in the S direction for projected coordinates (usually 0.5).
[in]scaleTScale in the T direction for projected coordinates (usually 0.5).
[in]transSTranslate in the S direction for projected coordinates (usually 0.5).
[in]transTTranslate in the T direction for projected coordinates (usually 0.5).
Returns
none

◆ guOrtho()

void guOrtho ( Mtx44  mt,
f32  t,
f32  b,
f32  l,
f32  r,
f32  n,
f32  f 
)

Sets a 4x4 matrix for orthographic projection.

This matrix is used by the GX API to transform points from eye space to screen space.

For normal parallel projections, the axis of projection is the -z axis, so t = positive, b = -t, r = positive, l = -r. n and f must both be given as positive distances.

Note
m negates a point's 'z' values, so pre-transformed points should have negative 'z' values in eye space in order to be visible after projection.
Parameters
[out]mtNew parallel projection matrix.
[in]tTop edge of view volume.
[in]bBottom edge of view volume.
[in]lLeft edge of view volume.
[in]rRight edge of view volume.
[in]nPositive distance to the near clipping plane.
[in]fPositive distance to the far clipping plane.
Returns
none

◆ guPerspective()

void guPerspective ( Mtx44  mt,
f32  fovy,
f32  aspect,
f32  n,
f32  f 
)

Sets a 4x4 perspective projection matrix from field of view and aspect ratio parameters.

This matrix is used by the GX API to transform points to screen space.

This function generates a projection matrix equivalent to that created by guFrustum() with the axis of projection centered around Z. It is included to provide an alternative method of specifying view volume dimensions.

The field of view (fovy) is the total field of view in degrees in the Y-Z plane. aspect is the ratio (width/height) of the view window in screen space. n and f must both be given as positive distances.

Note
m negates a point's 'z' values, so pre-transformed points should have negative 'z' values in eye space in order to be visible after projection.
Parameters
[out]mtNew perspective projection matrix.
[in]fovyTotal field of view in the Y-Z plane measured in degrees.
[in]aspectView window aspect ratio (width/height)
[in]nPositive distance to near clipping plane.
[in]fPositive distance to far clipping plane.
Returns
none