math Namespace Reference

math functions More...

Classes
class	Matrix
	math::Matrix is osg::Matrix extended with a flat-index operator[]. More...
class	Quaternion
	Quaternion defines a rotation (no position). More...
class	QuaternionPosition
	Quaternion with a position. More...
class	Radian
	Distinct float type. More...
class	Degree
	Distinct float type. More...
Typedefs
typedef osg::Vec2f	Vector2
	2D vector
typedef osg::Vec3f	Vector3
	3D vector
typedef osg::Vec3f	LocalVertex
	3D vertex in local/object space
typedef osg::Vec3f	WorldVertex
	3D vertex in world space
typedef osg::Vec3f	EyeVertex
	3D vertex in eye space
Enumerations
enum	{   Xx, Yx, Zx, Xw,   Xy, Yy, Zy, Yw,   Xz, Yz, Zz, Zw,   Ox, Oy, Oz, Ow }
Functions
template<typename FP>
bool	FP_EQ (FP a, FP b)
template<typename FP>
bool	FP_LE (FP a, FP b)
template<typename FP>
bool	FP_GE (FP a, FP b)
template<typename FP>
bool	FP_EQ (const FP a, const FP b, const uint fracDigits)
template<typename T1, typename T2>
bool	IfSameSign (const T1 a, const T2 b)
template<typename FP>
FP	SQRT (FP f)
template<typename T>
T	SQUARE (T x)
template<typename T>
T	AVG (T x, T y)
template<typename T>
T	Range (T val, T lo, T hi)
template<typename T>
T	IfInRange (T a0, T a1, T b0, T b1)
INLINE fp	FractionInRange (fp n, fp low, fp high)
INLINE fp	Remap (fp value, fp rangeOld, fp rangeNew)
INLINE fp	Truncate (fp val, fp interval)
template<typename T>
T	ModuloAbs (const T n, const T limit)
INLINE osg::Vec3f	Axis2Vec3 (const uint axis, const int dir)
INLINE osg::Vec3f	Axis2Vec3 (const uint axis)
INLINE WorldVertex	TransformLocal2World (const LocalVertex &lv, const Matrix &objectMatrix)
INLINE EyeVertex	TransformWorld2Eye (const WorldVertex &wv, const Matrix &viewMatrix)
template<typename DEST, typename SRC, typename MATRIX>
DEST	RotateTranslate (const SRC &v, const MATRIX &m)
template<typename DEST, typename SRC, typename MATRIX>
DEST	TranslateRotate (const SRC &src, const MATRIX &m)
template<typename FP>
pair< FP, FP >	SinCos (const Radian rad)
INLINE Radian	Deg2Rad (const Degree deg)
INLINE Degree	Rad2Deg (const Radian rad)
INLINE Degree::value_type	Sin (const Degree deg)
INLINE Degree::value_type	Cos (const Degree deg)
template<typename FP>
FP	Distance (const FP x, const FP y, const FP z)
INLINE fp	Distance (const Vector2 &v)
INLINE fp	Distance (const Vector3 &v)
template<typename VECTOR3A, typename VECTOR3B>
fpx	Distance (const VECTOR3A &v1, const VECTOR3B &v2)
INLINE Vector3::value_type	DistanceSquared (const Vector3 &v1, const Vector3 &v2)
INLINE Vector3	Normalize (const Vector3 &v)
template<typename VERTEX, typename FP>
VERTEX	Normalize (const FP x, const FP y, const FP z)
INLINE Vector3::value_type	NormalizeCoord (const uint axis, const Vector3 &v)
INLINE Vector3	AddDistance (const Vector3 &v, const fp distance1)
INLINE Vector3	CrossProduct (const Vector3 &v1, const Vector3 &v2, const Vector3 &v0=Vector3(0, 0, 0))
INLINE fp	DotProduct2 (const Vector2 &v1, const Vector2 &v2)
template<typename VECTOR3A, typename VECTOR3B>
fp	DotProduct3 (const VECTOR3A &v1, const VECTOR3B &v2)
template<typename VECTOR3A, typename VECTOR3B>
fpx	DotProduct3_fpx (const VECTOR3A &v1, const VECTOR3B &v2)
INLINE Radian	Angle2 (const Vector2 &u, const Vector2 &v)
template<typename VECTOR>
Radian	Angle3 (const VECTOR &u, const VECTOR &v)
INLINE Vector3	Interpolate (const Vector3 &v1, const Vector3 &v2, const fp fraction)
template<typename T>
T	Midpoint (const T &x1, const T &x2)
INLINE Vector3	Midpoint (const Vector3 &v1, const Vector3 &v2)
INLINE uint	CycleAxis3 (const uint axis)
WorldVertex	ComputeVertexOnDome (const Degree lat, const Degree lon, const fp radius)
Degree	ComputeMatrixRollDegree (const Matrix &matrix, const Matrix &nextMatrix)
INLINE bool	IF_Z_FACING (const fp z)
void	MatrixScale (osg::MatrixTransform &transform, const Vector3 &scale)
void	MatrixTranslate (osg::MatrixTransform &transform, const Vector3 &offset)
void	MatrixRotateLocal (osg::MatrixTransform &transform, const uint axis, const Radian rad)
void	MatrixRotateFixed (osg::MatrixTransform &transform, const uint axis, const Radian rad)
ostream &	operator<< (ostream &strm, const Matrix &m)
template<typename MATRIX>
void	MatrixIdentity (MATRIX &m)
template<typename MATRIX>
void	MatrixTranslate (MATRIX &m, const Vector3 &offset)
template<typename MATRIX, typename FPM>
void	MatrixTranslateFixed (MATRIX &m, const uint axis, const FPM inc)
template<typename MATRIX, typename FPM>
void	MatrixTranslateLocal (MATRIX &m, const uint axis, const FPM inc)
template<typename MATRIX, typename VECTOR3>
void	MatrixTranslateLocal (MATRIX &m, const VECTOR3 &v)
template<typename MATRIX>
void	MatrixRotateFixed (MATRIX &m, const uint axis, const Radian rad)
template<typename MATRIX>
void	MatrixRotateLocal (MATRIX &m, const uint axis, const Radian rad)
template<typename MATRIX>
MATRIX	MatrixInvert (const MATRIX &src)
template<typename MATRIX>
void	MatrixTranspose (MATRIX &dest, const MATRIX &src)
template<typename MATRIX1, typename MATRIX2>
fpx	MatrixDistanceSquared (const MATRIX1 &m1, const MATRIX2 &m2)
Quaternion	Interpolate (const Quaternion &q0, const Quaternion &q1, const fp fraction)
QuaternionPosition	Interpolate (const QuaternionPosition &qp0, const QuaternionPosition &qp1, const fp fraction)
istream &	operator>> (istream &strm, Quaternion &quat)
ostream &	operator<< (ostream &strm, const Quaternion &quat)
	DECLARE_DISTINCT_TYPE (Radian, fpx, FP) DECLARE_DISTINCT_TYPE(Degree
Variables
const fpx	PI = 3.14159265358979323846L
	L for long double.
const fpx	PI_DOUBLE = 6.28318530717958647692L
	pi * 2.0
const fpx	PI_HALF = 1.57079632679489661926L
	pi / 2.0 [equivalent to 90']
const Radian	RADIAN_EQU_DEGREE_90 = math::PI_HALF
	90' in radians (quarter circle)
const Radian	RADIAN_EQU_DEGREE_180 = math::PI
	180' in radians (half circle)
const Radian	RADIAN_EQU_DEGREE_360 = math::PI_DOUBLE
	360' in radians (full circle)
const Radian	RADIAN_EQU_DEGREE_1 = RADIAN_EQU_DEGREE_90 / 90.0
	1' in radians
const uint	XX = 0
const uint	YY = 1
const uint	ZZ = 2
const uint	WW = 3
const uint	AXIS_X = 0
const uint	AXIS_Y = 1
const uint	AXIS_Z = 2
const uint	AXIS_INVALID = ~0
INTERN const fpx	degRadRatio = (1.0 / 360.0) * (math::PI_DOUBLE)
INTERN const fpx	radDegRatio = (1.0 / math::PI_DOUBLE) * 360.0
const fp	EYE_MATRIX_ORIGIN_SIGN = -1.0
	fpx

---

Detailed Description

math functions

---

Typedef Documentation

typedef osg::Vec3f math::EyeVertex

3D vertex in eye space

typedef osg::Vec3f math::LocalVertex

3D vertex in local/object space

typedef osg::Vec2f math::Vector2

2D vector

typedef osg::Vec3f math::Vector3

3D vector

typedef osg::Vec3f math::WorldVertex

3D vertex in world space

---

Enumeration Type Documentation

anonymous enum

Enumerator:

Xx
Yx
Zx
Xw
Xy
Yy
Zy
Yw
Xz
Yz
Zz
Zw
Ox
Oy
Oz
Ow

---

Function Documentation

INLINE Vector3 math::AddDistance	(	const Vector3 &	v,
		const fp	distance1
	)

Increase/decrease a 3D vector by a scalar.

The WRONG way, of course, is to simply add the scalar to each dimension. For example, Vector(1,1) vs. Vector(2,2): math.sqrt( (1.0*1.0) + (1.0*1.0) ) 1.4142135623730951 math.sqrt( (2.0*2.0) + (2.0*2.0) ) 2.8284271247461903 # oops != 2.4142

The right way is to turn the scalar distance into a 3D vector with the same direction as the input vector. This is done by multiplying the scalar distance by the normalized input vector, then adding.

INLINE Radian math::Angle2	(	const Vector2 &	u,
		const Vector2 &	v
	)

Calculate angle (in radians) between two vectors sharing the same origin.

template<typename VECTOR>

Radian math::Angle3	(	const VECTOR &	u,
		const VECTOR &	v
	)			[inline]

template<typename T>

T math::AVG	(	T	x,
		T	y
	)			[inline]

Average.

INLINE osg::Vec3f math::Axis2Vec3

(

const uint

axis

)

INLINE osg::Vec3f math::Axis2Vec3	(	const uint	axis,
		const int	dir
	)

Convert an axis index to a 3D vector. Useful for then passing 3D vector to OSG makeRotate() etc.

Parameters:

	axis	XX,YY,ZZ
	dir	-1,1

Degree math::ComputeMatrixRollDegree	(	const Matrix &	matrix,
		const Matrix &	nextMatrix
	)

Compute angle between Y axis of two matrixs.

This is used to support cloud sprites. When view matrix is recomputed, the "roll degree" can be computed using the change in the Y axis of the previous/next view matrixs.

WorldVertex math::ComputeVertexOnDome	(	const Degree	lat,
		const Degree	lon,
		const fp	radius
	)

Compute a 3D vertex on a dome from (lat,lon) coordinates.

INLINE Degree::value_type math::Cos

(

const Degree

deg

)

360' cos().

INLINE Vector3 math::CrossProduct	(	const Vector3 &	v1,
		const Vector3 &	v2,
		const Vector3 &	v0 = Vector3(0,0,0)
	)

Calculate a cross product of two vectors which yields a normal vector that is perpendicular to the plane containing the two source vectors. Note: The cross product won't be unit length.

INLINE uint math::CycleAxis3

(

const uint

axis

)

Cycle {X,Y,Z}.

math::DECLARE_DISTINCT_TYPE	(	Radian	,
		fpx	,
		FP
	)

INLINE Radian math::Deg2Rad

(

const Degree

deg

)

template<typename VECTOR3A, typename VECTOR3B>

fpx math::Distance	(	const VECTOR3A &	v1,
		const VECTOR3B &	v2
	)			[inline]

Distance between two vectors (DistanceSquared() is faster than this).

INLINE fp math::Distance

(

const Vector3 &

v

)

INLINE fp math::Distance

(

const Vector2 &

v

)

template<typename FP>

FP math::Distance	(	const FP	x,
		const FP	y,
		const FP	z
	)			[inline]

Distance between vector and implied zero origin.

INLINE Vector3::value_type math::DistanceSquared	(	const Vector3 &	v1,
		const Vector3 &	v2
	)

Calculate the distance^2 (squared) between two vectors. DISTANCE RETURNED IS SQUARED (distance^2). SQUARE ROOT OF DISTANCE IS SKIPPED FOR SPEED. sqrt() and the underlying FPU instruction is very slow.

INLINE fp math::DotProduct2	(	const Vector2 &	v1,
		const Vector2 &	v2
	)

Calculate the dot product of two vectors which yields a scalar. If the angle between the two vectors is between 0 and 90 degrees, the dot product will be positive, else negative.

template<typename VECTOR3A, typename VECTOR3B>

fp math::DotProduct3	(	const VECTOR3A &	v1,
		const VECTOR3B &	v2
	)			[inline]

template<typename VECTOR3A, typename VECTOR3B>

fpx math::DotProduct3_fpx	(	const VECTOR3A &	v1,
		const VECTOR3B &	v2
	)			[inline]

template<typename FP>

bool math::FP_EQ	(	const FP	a,
		const FP	b,
		const uint	fracDigits
	)			[inline]

Compare floats: compare full integral part, compare fracDigits of fractional part. Eg: FP_EQ( 1.234, 1.234, 4 ) Note: In practice, usually, fracDigits should be small, or miscompares will be frequent. Tested by tests/math.cc.

template<typename FP>

bool math::FP_EQ	(	FP	a,
		FP	b
	)			[inline]

Cope with floating-point inaccuracy. Return true if two floats are approximately equal.

template<typename FP>

bool math::FP_GE	(	FP	a,
		FP	b
	)			[inline]

template<typename FP>

bool math::FP_LE	(	FP	a,
		FP	b
	)			[inline]

INLINE fp math::FractionInRange	(	fp	n,
		fp	low,
		fp	high
	)

Compute a fraction for a number in a range. Number is allowed to be outside the range (result will be clamped to 0 or 1). Examples: FractionInRange(100,100,200) = 0.0 FractionInRange(150,100,200) = 0.5 FractionInRange(200,100,200) = 1.0

INLINE bool math::IF_Z_FACING

(

const fp

z

)

template<typename T>

T math::IfInRange	(	T	a0,
		T	a1,
		T	b0,
		T	b1
	)			[inline]

Returns:

True if two lines overlap.

template<typename T1, typename T2>

bool math::IfSameSign	(	const T1	a,
		const T2	b
	)			[inline]

Returns:

True If two numbers have the same sign.

QuaternionPosition math::Interpolate	(	const QuaternionPosition &	qp0,
		const QuaternionPosition &	qp1,
		const fp	fraction
	)

Interpolate between two quaternions and positions. fraction = 0 : return m0 fraction = 1 : return m1

Quaternion math::Interpolate	(	const Quaternion &	q0,
		const Quaternion &	q1,
		const fp	fraction
	)

Interpolate between two quaternions. fraction = 0 : return m0 fraction = 1 : return m1

INLINE Vector3 math::Interpolate	(	const Vector3 &	v1,
		const Vector3 &	v2,
		const fp	fraction
	)

Interpolate between two vectors.

Parameters:

	v1,v2
	fraction	Fraction in range {0,..,1.0}. If fraction is 0.0, v1 is returned. If fraction is 1.0, v2 is returned. If fraction is 0.5, midpoint is returned.

Returns:

Interpolated 3D point.

template<typename MATRIX1, typename MATRIX2>

fpx math::MatrixDistanceSquared	(	const MATRIX1 &	m1,
		const MATRIX2 &	m2
	)			[inline]

Distance^2 between two matrixs. Don't pass different kinds of matrixs (eg Eye origin is negative but Dyna is positive).

template<typename MATRIX>

void math::MatrixIdentity

(

MATRIX &

m

)

[inline]

Reset a matrix to identity (no rotation, no translation).

template<typename MATRIX>

MATRIX math::MatrixInvert

(

const MATRIX &

src

)

[inline]

-- Alternative is MatrixTranspose() -- Reverse the mapping between two coordinate systems. Math notes: osg::Matrix::inverse() is more complex than a purely mathematical function.

template<typename MATRIX>

void math::MatrixRotateFixed	(	MATRIX &	m,
		const uint	axis,
		const Radian	rad
	)			[inline]

Rotate a matrix around a fixed axis. This function is suited to rotating the viewpoint/eye. The word "fixed" should be clear by looking at the math. Eg, the value of the X coord won't be changed by a rotation around the X axis.

void math::MatrixRotateFixed	(	osg::MatrixTransform &	transform,
		const uint	axis,
		const Radian	rad
	)

For osg::MatrixTransform node. Rotate a matrix around a fixed axis. This function is suited to rotating the viewpoint/eye.

template<typename MATRIX>

void math::MatrixRotateLocal	(	MATRIX &	m,
		const uint	axis,
		const Radian	rad
	)			[inline]

Rotate matrix around local axis. Rotate a local coordinate system around its own axis. This function is suited to rotating an independent object. The rotation is relative to local coodinate system (not the fixed/eye system). The trick is to load an identity-mapped matrix and rotate it, then transform it thru the given matrix (which defines the local coordinate system) as though it was the coords (1.0, 1.0, 1.0). These coords of course define the X,Y,Z axises. The transformation is effectively a local rotation.

void math::MatrixRotateLocal	(	osg::MatrixTransform &	transform,
		const uint	axis,
		const Radian	rad
	)

For osg::MatrixTransform node. Rotate matrix around local axis. Rotate a local coordinate system around its own axis.

void math::MatrixScale	(	osg::MatrixTransform &	transform,
		const Vector3 &	scale
	)

Scale a MatrixTransform node. Can effectively scale an Object.

template<typename MATRIX>

void math::MatrixTranslate	(	MATRIX &	m,
		const Vector3 &	offset
	)			[inline]

Translate a Matrix by a vector offset.

void math::MatrixTranslate	(	osg::MatrixTransform &	transform,
		const Vector3 &	offset
	)

Translate a MatrixTransform node.

template<typename MATRIX, typename FPM>

void math::MatrixTranslateFixed	(	MATRIX &	m,
		const uint	axis,
		const FPM	inc
	)			[inline]

Translate a matrix along an axis in fixed space. For translating the eye/viewpoint.

template<typename MATRIX, typename VECTOR3>

void math::MatrixTranslateLocal	(	MATRIX &	m,
		const VECTOR3 &	v
	)			[inline]

template<typename MATRIX, typename FPM>

void math::MatrixTranslateLocal	(	MATRIX &	m,
		const uint	axis,
		const FPM	inc
	)			[inline]

Translate a matrix along its own axis. For translating a Dyna.

template<typename MATRIX>

void math::MatrixTranspose	(	MATRIX &	dest,
		const MATRIX &	src
	)			[inline]

-- Alternative is MatrixInvert() -- Reverse the mapping between two coordinate systems by transposing matrix rows/columns. Math notes: This produces different results than MatrixInvert().

INLINE Vector3 math::Midpoint	(	const Vector3 &	v1,
		const Vector3 &	v2
	)

template<typename T>

T math::Midpoint	(	const T &	x1,
		const T &	x2
	)			[inline]

Midpoint.

template<typename T>

T math::ModuloAbs	(	const T	n,
		const T	limit
	)			[inline]

Modulo that handles negative values by subtracting from limit. For example, ModuloAbs(deg,360.0f) can be used to accomodate a function that requires degrees to be in range {0,..,360} ModuloAbs( -1.0, 360.0 ) = 359.0 ModuloAbs( -90.0, 360.0 ) = 270.0

template<typename VERTEX, typename FP>

VERTEX math::Normalize	(	const FP	x,
		const FP	y,
		const FP	z
	)			[inline]

INLINE Vector3 math::Normalize

(

const Vector3 &

v

)

Returns:

A normalized vector (unit-length 1.0) of the same vector. Not to be confused with calculating the normal vector of two vectors (CrossProduct).

INLINE Vector3::value_type math::NormalizeCoord	(	const uint	axis,
		const Vector3 &	v
	)

Normalize a 3D point (unit 1 distance) then return one normalized coordinate. The return value typically is passed to asin().

ostream & math::operator<<	(	ostream &	strm,
		const Quaternion &	quat
	)

ostream & math::operator<<	(	ostream &	strm,
		const Matrix &	m
	)

operator<<().

istream & math::operator>>	(	istream &	strm,
		Quaternion &	quat
	)

Quaternion stream functions.

INLINE Degree math::Rad2Deg

(

const Radian

rad

)

template<typename T>

T math::Range	(	T	val,
		T	lo,
		T	hi
	)			[inline]

Force a number to be within a range.

INLINE fp math::Remap	(	fp	value,
		fp	rangeOld,
		fp	rangeNew
	)

Map a number from one range into another.

template<typename DEST, typename SRC, typename MATRIX>

DEST math::RotateTranslate	(	const SRC &	v,
		const MATRIX &	m
	)			[inline]

Rotate then translate.

INLINE Degree::value_type math::Sin

(

const Degree

deg

)

360' sin().

template<typename FP>

pair<FP,FP> math::SinCos

(

const Radian

rad

)

[inline]

Compute sine and cosine. Example: pair<fp,fp> si_co = SinCos<fp>( rad ); fp& s = si_co.first; fp& c = si_co.second;

template<typename FP>

FP math::SQRT

(

FP

f

)

[inline]

Square root function.

template<typename T>

T math::SQUARE

(

T

x

)

[inline]

x^2

INLINE WorldVertex math::TransformLocal2World	(	const LocalVertex &	lv,
		const Matrix &	objectMatrix
	)

local --> world Transform vertex from local/object space to world space.

INLINE EyeVertex math::TransformWorld2Eye	(	const WorldVertex &	wv,
		const Matrix &	viewMatrix
	)

world --> eye Transform vertex from world space to eye space.

template<typename DEST, typename SRC, typename MATRIX>

DEST math::TranslateRotate	(	const SRC &	src,
		const MATRIX &	m
	)			[inline]

Translate then rotate.

INLINE fp math::Truncate	(	fp	val,
		fp	interval
	)

Truncate a float at an interval. Eg, Truncate(24,10) returns 20.

---

Variable Documentation

const uint math::AXIS_INVALID = ~0

const uint math::AXIS_X = 0

const uint math::AXIS_Y = 1

const uint math::AXIS_Z = 2

INTERN const fpx math::degRadRatio = (1.0 / 360.0) * (math::PI_DOUBLE)

Convert a (360) degree into a radian. 360' = 2 * PI

const fp math::EYE_MATRIX_ORIGIN_SIGN = -1.0

math::fpx

const fpx math::PI = 3.14159265358979323846L

L for long double.

const fpx math::PI_DOUBLE = 6.28318530717958647692L

pi * 2.0

const fpx math::PI_HALF = 1.57079632679489661926L

pi / 2.0 [equivalent to 90']

INTERN const fpx math::radDegRatio = (1.0 / math::PI_DOUBLE) * 360.0

Convert a radian into a (360) degree. 360' = 2 * PI

const Radian math::RADIAN_EQU_DEGREE_1 = RADIAN_EQU_DEGREE_90 / 90.0

1' in radians

const Radian math::RADIAN_EQU_DEGREE_180 = math::PI

180' in radians (half circle)

const Radian math::RADIAN_EQU_DEGREE_360 = math::PI_DOUBLE

360' in radians (full circle)

const Radian math::RADIAN_EQU_DEGREE_90 = math::PI_HALF

90' in radians (quarter circle)

const uint math::WW = 3

const uint math::XX = 0

const uint math::YY = 1

const uint math::ZZ = 2