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 | 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_guMtxApplyScale (Mtx src, Mtx dst, f32 xS, f32 yS, f32 zS) |
void | c_guMtxApplyTrans (Mtx src, Mtx dst, f32 xT, f32 yT, f32 zT) |
void | c_guMtxConcat (Mtx a, Mtx b, Mtx ab) |
void | c_guMtxCopy (Mtx src, Mtx dst) |
void | c_guMtxIdentity (Mtx mt) |
u32 | c_guMtxInverse (Mtx src, Mtx inv) |
u32 | c_guMtxInvXpose (Mtx src, Mtx xPose) |
void | c_guMtxQuat (Mtx m, guQuaternion *a) |
void | c_guMtxReflect (Mtx m, guVector *p, 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 (Mtx src, Mtx dst, f32 xS, f32 yS, f32 zS) |
void | c_guMtxTrans (Mtx mt, f32 xT, f32 yT, f32 zT) |
void | c_guMtxTransApply (Mtx src, Mtx dst, f32 xT, f32 yT, f32 zT) |
void | c_guMtxTranspose (Mtx src, Mtx xPose) |
void | c_guQuatAdd (guQuaternion *a, guQuaternion *b, guQuaternion *ab) |
void | c_guQuatInverse (guQuaternion *a, guQuaternion *d) |
void | c_guQuatMtx (guQuaternion *a, Mtx m) |
void | c_guQuatMultiply (guQuaternion *a, guQuaternion *b, guQuaternion *ab) |
void | c_guQuatNormalize (guQuaternion *a, guQuaternion *d) |
void | c_guQuatSub (guQuaternion *a, guQuaternion *b, guQuaternion *ab) |
void | c_guVecAdd (guVector *a, guVector *b, guVector *ab) |
void | c_guVecCross (guVector *a, guVector *b, guVector *axb) |
f32 | c_guVecDotProduct (guVector *a, guVector *b) |
void | c_guVecMultiply (Mtx mt, guVector *src, guVector *dst) |
void | c_guVecMultiplySR (Mtx mt, guVector *src, guVector *dst) |
void | c_guVecNormalize (guVector *v) |
void | c_guVecScale (guVector *src, guVector *dst, f32 scale) |
void | c_guVecSub (guVector *a, 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, guVector *camPos, guVector *camUp, guVector *target) |
Sets a world-space to camera-space transformation matrix. More... | |
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 (guVector *a, guVector *b, guVector *half) |
Computes a vector that lies halfway between a and b. More... | |
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.
#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.
[in] | mt | Matrix to be accessed. |
[in] | r | Row index of element to access. |
[in] | c | Column index of element to access. |
f32 Mtx[3][4] |
Standard 3x4 matrix.
f32 Mtx44[4][4] |
4x4 matrix.
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.
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.
[out] | mt | New projection matrix. |
[in] | t | Top edge of view volume at the near clipping plane. |
[in] | b | Bottom edge of view volume at the near clipping plane. |
[in] | l | Left edge of view volume at the near clipping plane. |
[in] | r | Right edge of view volume at the near clipping plane. |
[in] | n | Positive distance to the near clipping plane. |
[in] | f | Positive distance to the far clipping plane. |
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.
[out] | mt | New projection matrix. |
[in] | t | Top edge of view volume at the near clipping plane. |
[in] | b | Bottom edge of view volume at the near clipping plane. |
[in] | l | Left edge of view volume at the near clipping plane. |
[in] | r | Right edge of view volume at the near clipping plane. |
[in] | n | Positive distance to the near clipping plane. |
[in] | scaleS | Scale in the S direction for projected coordinates (usually 0.5). |
[in] | scaleT | Scale in the T direction for projected coordinates (usually 0.5). |
[in] | transS | Translate in the S direction for projected coordinates (usually 0.5). |
[in] | transT | Translate in the T direction for projected coordinates (usually 0.5). |
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.
[out] | mt | New parallel projection matrix. |
[in] | t | Top edge of view volume. |
[in] | b | Bottom edge of view volume. |
[in] | l | Left edge of view volume. |
[in] | r | Right edge of view volume. |
[in] | scaleS | Scale in the S direction for projected coordinates (usually 0.5). |
[in] | scaleT | Scale in the T direction for projected coordinates (usually 0.5). |
[in] | transS | Translate in the S direction for projected coordinates (usually 0.5). |
[in] | transT | Translate in the T direction for projected coordinates (usually 0.5). |
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.
[out] | mt | New projection matrix. |
[in] | fovy | Total field of view in the YZ plane measured in degrees. |
[in] | aspect | View window aspect ratio (width / height) |
[in] | scaleS | Scale in the S direction for projected coordinates (usually 0.5). |
[in] | scaleT | Scale in the T direction for projected coordinates (usually 0.5). |
[in] | transS | Translate in the S direction for projected coordinates (usually 0.5). |
[in] | transT | Translate in the T direction for projected coordinates (usually 0.5). |
Sets a world-space to camera-space transformation matrix.
Create the matrix m by specifying a camera position (camPos), a camera "up" direction (camUp), and a target position (target).
The camera's reference viewing direction is the -z axis. The camera's reference 'up' direction is the +y axis.
This function is especially convenient for creating a tethered camera, aiming at an object, panning, or specifying an arbitrary view.
[out] | mt | New viewing matrix. |
[in] | camPos | Vector giving 3D camera position in world space. |
[in] | camUp | Vector containing camera "up" vector; does not have to be a unit vector. |
[in] | target | Vector giving 3D target position in world space. |
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.
[out] | mt | New parallel projection matrix. |
[in] | t | Top edge of view volume. |
[in] | b | Bottom edge of view volume. |
[in] | l | Left edge of view volume. |
[in] | r | Right edge of view volume. |
[in] | n | Positive distance to the near clipping plane. |
[in] | f | Positive distance to the far clipping plane. |
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.
[out] | mt | New perspective projection matrix. |
[in] | fovy | Total field of view in the Y-Z plane measured in degrees. |
[in] | aspect | View window aspect ratio (width/height) |
[in] | n | Positive distance to near clipping plane. |
[in] | f | Positive distance to far clipping plane. |
Computes a vector that lies halfway between a and b.
The halfway vector is useful in specular reflection calculations. It is interpreted as pointing from the reflecting surface to the general viewing direction.
a and b do not have to be unit vectors. Both of these vectors are assumed to be pointing towards the surface from the light or viewer, respectively. Local copies of these vectors are negated, normalized and added head to tail.
half is computed as a unit vector that points from the surface to halfway between the light and the viewing direction.
[in] | a | Pointer to incident vector. Must point from the light source to the surface. |
[in] | b | Pointer to viewing vector. Must point from the viewer to the surface. |
[out] | half | Pointer to resultant half-angle unit vector; points from the surface to halfway between the light and the viewing direction. |