gu.h File Reference

GU/Matrix subsystem. More...

#include <gctypes.h>

Include dependency graph for gu.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	_vecf
struct	_qrtn

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

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

Functions
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	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	guOrtho (Mtx44 mt, f32 t, f32 b, f32 l, f32 r, f32 n, f32 f)
	Sets a 4x4 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	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	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	guLookAt (Mtx mt, guVector *camPos, guVector *camUp, guVector *target)
	Sets a world-space to camera-space transformation matrix. More...
void	guVecHalfAngle (guVector *a, guVector *b, guVector *half)
	Computes a vector that lies halfway between a and b. More...
void	c_guVecAdd (guVector *a, guVector *b, guVector *ab)
void	c_guVecSub (guVector *a, guVector *b, guVector *ab)
void	c_guVecScale (guVector *src, guVector *dst, f32 scale)
void	c_guVecNormalize (guVector *v)
void	c_guVecMultiply (Mtx mt, guVector *src, guVector *dst)
void	c_guVecCross (guVector *a, guVector *b, guVector *axb)
void	c_guVecMultiplySR (Mtx mt, guVector *src, guVector *dst)
f32	c_guVecDotProduct (guVector *a, guVector *b)
void	c_guQuatAdd (guQuaternion *a, guQuaternion *b, guQuaternion *ab)
void	c_guQuatSub (guQuaternion *a, guQuaternion *b, guQuaternion *ab)
void	c_guQuatMultiply (guQuaternion *a, guQuaternion *b, guQuaternion *ab)
void	c_guQuatNormalize (guQuaternion *a, guQuaternion *d)
void	c_guQuatInverse (guQuaternion *a, guQuaternion *d)
void	c_guQuatMtx (guQuaternion *a, Mtx m)
void	c_guMtxIdentity (Mtx mt)
void	c_guMtxCopy (Mtx src, Mtx dst)
void	c_guMtxConcat (Mtx a, Mtx b, Mtx ab)
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_guMtxApplyScale (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_guMtxApplyTrans (Mtx src, Mtx dst, f32 xT, f32 yT, f32 zT)
u32	c_guMtxInverse (Mtx src, Mtx inv)
u32	c_guMtxInvXpose (Mtx src, Mtx xPose)
void	c_guMtxTranspose (Mtx src, Mtx xPose)
void	c_guMtxRotRad (Mtx mt, const char axis, f32 rad)
void	c_guMtxRotTrig (Mtx mt, const char axis, f32 sinA, f32 cosA)
void	c_guMtxRotAxisRad (Mtx mt, guVector *axis, f32 rad)
void	c_guMtxReflect (Mtx m, guVector *p, guVector *n)
void	c_guMtxQuat (Mtx m, guQuaternion *a)

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

DegToRad

#define DegToRad

(

a

)

( (a) * 0.01745329252f )

FIX32TOF

#define FIX32TOF

(

x

)

((f32)(x) * (1.0f / (f32)0x00010000))

FTOFIX32

#define FTOFIX32

(

x

)

(s32)((x) * (f32)0x00010000)

FTOFRAC8

#define FTOFRAC8

(

x

)

((s32) MIN(((x) * (128.0f)), 127.0f) & 0xff)

guMtxApplyScale

#define guMtxApplyScale   c_guMtxApplyScale

guMtxApplyTrans

#define guMtxApplyTrans   c_guMtxApplyTrans

guMtxConcat

#define guMtxConcat   c_guMtxConcat

guMtxCopy

#define guMtxCopy   c_guMtxCopy

guMtxIdentity

#define guMtxIdentity   c_guMtxIdentity

guMtxInverse

#define guMtxInverse   c_guMtxInverse

guMtxInvXpose

#define guMtxInvXpose   c_guMtxInvXpose

guMtxQuat

#define guMtxQuat   c_guMtxQuat

guMtxReflect

#define guMtxReflect   c_guMtxReflect

guMtxRotAxisDeg

#define guMtxRotAxisDeg	(		mt,
			axis,
			deg
	)		guMtxRotAxisRad(mt,axis,DegToRad(deg))

guMtxRotAxisRad

#define guMtxRotAxisRad   c_guMtxRotAxisRad

guMtxRotDeg

#define guMtxRotDeg	(		mt,
			axis,
			deg
	)		guMtxRotRad(mt,axis,DegToRad(deg))

guMtxRotRad

#define guMtxRotRad   c_guMtxRotRad

guMtxRotTrig

#define guMtxRotTrig   c_guMtxRotTrig

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]	mt	Matrix to be accessed.
[in]	r	Row index of element to access.
[in]	c	Column index of element to access.

Returns

none

guMtxScale

#define guMtxScale   c_guMtxScale

guMtxScaleApply

#define guMtxScaleApply   c_guMtxScaleApply

guMtxTrans

#define guMtxTrans   c_guMtxTrans

guMtxTransApply

#define guMtxTransApply   c_guMtxTransApply

guMtxTranspose

#define guMtxTranspose   c_guMtxTranspose

guQuatAdd

#define guQuatAdd   c_guQuatAdd

guQuatInverse

#define guQuatInverse   c_guQuatInverse

guQuatMtx

#define guQuatMtx   c_guQuatMtx

guQuatMultiply

#define guQuatMultiply   c_guQuatMultiply

guQuatNoramlize

#define guQuatNoramlize   c_guQuatNormalize

guQuatSub

#define guQuatSub   c_guQuatSub

guVecAdd

#define guVecAdd   c_guVecAdd

guVecCross

#define guVecCross   c_guVecCross

guVecDotProduct

#define guVecDotProduct   c_guVecDotProduct

guVecMultiply

#define guVecMultiply   c_guVecMultiply

guVecMultiplySR

#define guVecMultiplySR   c_guVecMultiplySR

guVecNormalize

#define guVecNormalize   c_guVecNormalize

guVecScale

#define guVecScale   c_guVecScale

guVecSub

#define guVecSub   c_guVecSub

M_DTOR

#define M_DTOR   (3.14159265358979323846/180.0)

M_PI

#define M_PI   3.14159265358979323846

MAX

#define MAX	(		a,
			b
	)		(((a)>(b))?(a):(b))

MIN

#define MIN	(		a,
			b
	)		(((a)<(b))?(a):(b))

MTX_USE_C

#define MTX_USE_C

RadToDeg

#define RadToDeg

(

a

)

( (a) * 57.29577951f )

Typedef Documentation

guQuaternion

typedef struct _qrtn guQuaternion

guVector

typedef struct _vecf guVector

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.

Mtx33

f32 Mtx33[3][3]

3x3 matrix.

Mtx33P

typedef f32(* Mtx33P)[3]

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.

Mtx44P

typedef f32(* Mtx44P)[4]

MtxP

typedef f32(* MtxP)[4]

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.

ROMtxP

typedef f32(* ROMtxP)[3]

Function Documentation

c_guMtxApplyScale()

void c_guMtxApplyScale	(	Mtx	src,
		Mtx	dst,
		f32	xS,
		f32	yS,
		f32	zS
	)

c_guMtxApplyTrans()

void c_guMtxApplyTrans	(	Mtx	src,
		Mtx	dst,
		f32	xT,
		f32	yT,
		f32	zT
	)

c_guMtxConcat()

void c_guMtxConcat	(	Mtx	a,
		Mtx	b,
		Mtx	ab
	)

Here is the call graph for this function:

Here is the caller graph for this function:

c_guMtxCopy()

void c_guMtxCopy	(	Mtx	src,
		Mtx	dst
	)

Here is the caller graph for this function:

c_guMtxIdentity()

void c_guMtxIdentity

(

Mtx

mt

)

c_guMtxInverse()

u32 c_guMtxInverse	(	Mtx	src,
		Mtx	inv
	)

Here is the call graph for this function:

c_guMtxInvXpose()

u32 c_guMtxInvXpose	(	Mtx	src,
		Mtx	xPose
	)

Here is the call graph for this function:

c_guMtxQuat()

void c_guMtxQuat	(	Mtx	m,
		guQuaternion *	a
	)

c_guMtxReflect()

void c_guMtxReflect	(	Mtx	m,
		guVector *	p,
		guVector *	n
	)

Here is the call graph for this function:

c_guMtxRotAxisRad()

void c_guMtxRotAxisRad	(	Mtx	mt,
		guVector *	axis,
		f32	rad
	)

Here is the call graph for this function:

c_guMtxRotRad()

void c_guMtxRotRad	(	Mtx	mt,
		const char	axis,
		f32	rad
	)

Here is the call graph for this function:

c_guMtxRotTrig()

void c_guMtxRotTrig	(	Mtx	mt,
		const char	axis,
		f32	sinA,
		f32	cosA
	)

Here is the caller graph for this function:

c_guMtxScale()

void c_guMtxScale	(	Mtx	mt,
		f32	xS,
		f32	yS,
		f32	zS
	)

c_guMtxScaleApply()

void c_guMtxScaleApply	(	Mtx	src,
		Mtx	dst,
		f32	xS,
		f32	yS,
		f32	zS
	)

c_guMtxTrans()

void c_guMtxTrans	(	Mtx	mt,
		f32	xT,
		f32	yT,
		f32	zT
	)

c_guMtxTransApply()

void c_guMtxTransApply	(	Mtx	src,
		Mtx	dst,
		f32	xT,
		f32	yT,
		f32	zT
	)

c_guMtxTranspose()

void c_guMtxTranspose	(	Mtx	src,
		Mtx	xPose
	)

Here is the call graph for this function:

c_guQuatAdd()

void c_guQuatAdd	(	guQuaternion *	a,
		guQuaternion *	b,
		guQuaternion *	ab
	)

c_guQuatInverse()

void c_guQuatInverse	(	guQuaternion *	a,
		guQuaternion *	d
	)

c_guQuatMtx()

void c_guQuatMtx	(	guQuaternion *	a,
		Mtx	m
	)

Here is the call graph for this function:

c_guQuatMultiply()

void c_guQuatMultiply	(	guQuaternion *	a,
		guQuaternion *	b,
		guQuaternion *	ab
	)

c_guQuatNormalize()

void c_guQuatNormalize	(	guQuaternion *	a,
		guQuaternion *	d
	)

Here is the call graph for this function:

Here is the caller graph for this function:

c_guQuatSub()

void c_guQuatSub	(	guQuaternion *	a,
		guQuaternion *	b,
		guQuaternion *	ab
	)

c_guVecAdd()

void c_guVecAdd	(	guVector *	a,
		guVector *	b,
		guVector *	ab
	)

c_guVecCross()

void c_guVecCross	(	guVector *	a,
		guVector *	b,
		guVector *	axb
	)

c_guVecDotProduct()

f32 c_guVecDotProduct	(	guVector *	a,
		guVector *	b
	)

Here is the call graph for this function:

Here is the caller graph for this function:

c_guVecMultiply()

void c_guVecMultiply	(	Mtx	mt,
		guVector *	src,
		guVector *	dst
	)

c_guVecMultiplySR()

void c_guVecMultiplySR	(	Mtx	mt,
		guVector *	src,
		guVector *	dst
	)

c_guVecNormalize()

void c_guVecNormalize

(

guVector *

v

)

Here is the caller graph for this function:

c_guVecScale()

void c_guVecScale	(	guVector *	src,
		guVector *	dst,
		f32	scale
	)

c_guVecSub()

void c_guVecSub	(	guVector *	a,
		guVector *	b,
		guVector *	ab
	)

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]	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.

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]	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).

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]	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).

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]	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).

Returns

none

guLookAt()

void guLookAt	(	Mtx	mt,
		guVector *	camPos,
		guVector *	camUp,
		guVector *	target
	)

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.

Parameters

[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.

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]	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.

Returns

none

Here is the caller graph for this function:

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]	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.

Returns

none

guVecHalfAngle()

void guVecHalfAngle	(	guVector *	a,
		guVector *	b,
		guVector *	half
	)

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.

Parameters

[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.

Returns

none