Ogre::Math Class Reference
[Math]

Class to provide access to common mathematical functions. More...

#include <OgreMath.h>

Public Types
enum	AngleUnit { AU_DEGREE, AU_RADIAN }
	The angular units used by the API. More...
Public Member Functions
	Math (unsigned int trigTableSize=4096)
	Default constructor.
	~Math ()
	Default destructor.
Static Public Member Functions
static int	IAbs (int iValue)
static int	ICeil (float fValue)
static int	IFloor (float fValue)
static int	ISign (int iValue)
static Real	Abs (Real fValue)
	Absolute value function.
static Degree	Abs (const Degree &dValue)
	Absolute value function.
static Radian	Abs (const Radian &rValue)
	Absolute value function.
static Radian	ACos (Real fValue)
	Arc cosine function.
static Radian	ASin (Real fValue)
	Arc sine function.
static Radian	ATan (Real fValue)
	Arc tangent function.
static Radian	ATan2 (Real fY, Real fX)
	Arc tangent between two values function.
static Real	Ceil (Real fValue)
	Ceiling function Returns the smallest following integer.
static bool	isNaN (Real f)
static Real	Cos (const Radian &fValue, bool useTables=false)
	Cosine function.
static Real	Cos (Real fValue, bool useTables=false)
	Cosine function.
static Real	Exp (Real fValue)
static Real	Floor (Real fValue)
	Floor function Returns the largest previous integer.
static Real	Log (Real fValue)
static Real	Log2 (Real fValue)
static Real	LogN (Real base, Real fValue)
static Real	Pow (Real fBase, Real fExponent)
static Real	Sign (Real fValue)
static Radian	Sign (const Radian &rValue)
static Degree	Sign (const Degree &dValue)
static Real	Sin (const Radian &fValue, bool useTables=false)
	Sine function.
static Real	Sin (Real fValue, bool useTables=false)
	Sine function.
static Real	Sqr (Real fValue)
	Squared function.
static Real	Sqrt (Real fValue)
	Square root function.
static Radian	Sqrt (const Radian &fValue)
	Square root function.
static Degree	Sqrt (const Degree &fValue)
	Square root function.
static Real	InvSqrt (Real fValue)
	Inverse square root i.e.
static Real	UnitRandom ()
	Generate a random number of unit length.
static Real	RangeRandom (Real fLow, Real fHigh)
	Generate a random number within the range provided.
static Real	SymmetricRandom ()
	Generate a random number in the range [-1,1].
static Real	Tan (const Radian &fValue, bool useTables=false)
	Tangent function.
static Real	Tan (Real fValue, bool useTables=false)
	Tangent function.
static Real	DegreesToRadians (Real degrees)
static Real	RadiansToDegrees (Real radians)
static void	setAngleUnit (AngleUnit unit)
	These functions used to set the assumed angle units (radians or degrees) expected when using the Angle type.
static AngleUnit	getAngleUnit (void)
	Get the unit being used for angles.
static Real	AngleUnitsToRadians (Real units)
	Convert from the current AngleUnit to radians.
static Real	RadiansToAngleUnits (Real radians)
	Convert from radians to the current AngleUnit .
static Real	AngleUnitsToDegrees (Real units)
	Convert from the current AngleUnit to degrees.
static Real	DegreesToAngleUnits (Real degrees)
	Convert from degrees to the current AngleUnit.
static bool	pointInTri2D (const Vector2 &p, const Vector2 &a, const Vector2 &b, const Vector2 &c)
	Checks whether a given point is inside a triangle, in a 2-dimensional (Cartesian) space.
static bool	pointInTri3D (const Vector3 &p, const Vector3 &a, const Vector3 &b, const Vector3 &c, const Vector3 &normal)
	Checks whether a given 3D point is inside a triangle.
static std::pair< bool, Real >	intersects (const Ray &ray, const Plane &plane)
	Ray / plane intersection, returns boolean result and distance.
static std::pair< bool, Real >	intersects (const Ray &ray, const Sphere &sphere, bool discardInside=true)
	Ray / sphere intersection, returns boolean result and distance.
static std::pair< bool, Real >	intersects (const Ray &ray, const AxisAlignedBox &box)
	Ray / box intersection, returns boolean result and distance.
static bool	intersects (const Ray &ray, const AxisAlignedBox &box, Real d1, Real d2)
	Ray / box intersection, returns boolean result and two intersection distance.
static std::pair< bool, Real >	intersects (const Ray &ray, const Vector3 &a, const Vector3 &b, const Vector3 &c, const Vector3 &normal, bool positiveSide=true, bool negativeSide=true)
	Ray / triangle intersection, returns boolean result and distance.
static std::pair< bool, Real >	intersects (const Ray &ray, const Vector3 &a, const Vector3 &b, const Vector3 &c, bool positiveSide=true, bool negativeSide=true)
	Ray / triangle intersection, returns boolean result and distance.
static bool	intersects (const Sphere &sphere, const AxisAlignedBox &box)
	Sphere / box intersection test.
static bool	intersects (const Plane &plane, const AxisAlignedBox &box)
	Plane / box intersection test.
static std::pair< bool, Real >	intersects (const Ray &ray, const vector< Plane >::type &planeList, bool normalIsOutside)
	Ray / convex plane list intersection test.
static std::pair< bool, Real >	intersects (const Ray &ray, const list< Plane >::type &planeList, bool normalIsOutside)
	Ray / convex plane list intersection test.
static bool	intersects (const Sphere &sphere, const Plane &plane)
	Sphere / plane intersection test.
static bool	RealEqual (Real a, Real b, Real tolerance=std::numeric_limits< Real >::epsilon())
	Compare 2 reals, using tolerance for inaccuracies.
static Vector3	calculateTangentSpaceVector (const Vector3 &position1, const Vector3 &position2, const Vector3 &position3, Real u1, Real v1, Real u2, Real v2, Real u3, Real v3)
	Calculates the tangent space vector for a given set of positions / texture coords.
static Matrix4	buildReflectionMatrix (const Plane &p)
	Build a reflection matrix for the passed in plane.
static Vector4	calculateFaceNormal (const Vector3 &v1, const Vector3 &v2, const Vector3 &v3)
	Calculate a face normal, including the w component which is the offset from the origin.
static Vector3	calculateBasicFaceNormal (const Vector3 &v1, const Vector3 &v2, const Vector3 &v3)
	Calculate a face normal, no w-information.
static Vector4	calculateFaceNormalWithoutNormalize (const Vector3 &v1, const Vector3 &v2, const Vector3 &v3)
	Calculate a face normal without normalize, including the w component which is the offset from the origin.
static Vector3	calculateBasicFaceNormalWithoutNormalize (const Vector3 &v1, const Vector3 &v2, const Vector3 &v3)
	Calculate a face normal without normalize, no w-information.
static Real	gaussianDistribution (Real x, Real offset=0.0f, Real scale=1.0f)
	Generates a value based on the Gaussian (normal) distribution function with the given offset and scale parameters.
template<typename T >
static T	Clamp (T val, T minval, T maxval)
	Clamp a value within an inclusive range.
static Matrix4	makeViewMatrix (const Vector3 &position, const Quaternion &orientation, const Matrix4 *reflectMatrix=0)
static Real	boundingRadiusFromAABB (const AxisAlignedBox &aabb)
	Get a bounding radius value from a bounding box.
Static Public Attributes
static const Real	LOG2
	Stored value of log(2) for frequent use.
static const Real	POS_INFINITY
static const Real	NEG_INFINITY
static const Real	PI
static const Real	TWO_PI
static const Real	HALF_PI
static const Real	fDeg2Rad
static const Real	fRad2Deg
Protected Member Functions
void	buildTrigTables ()
	Private function to build trig tables.
Static Protected Member Functions
static Real	SinTable (Real fValue)
static Real	TanTable (Real fValue)
Static Protected Attributes
static AngleUnit	msAngleUnit
static int	mTrigTableSize
	Size of the trig tables as determined by constructor.
static Real	mTrigTableFactor
	Radian -> index factor value ( mTrigTableSize / 2 * PI ).
static Real *	mSinTable
static Real *	mTanTable

Detailed Description

Class to provide access to common mathematical functions.

Remarks:: Most of the maths functions are aliased versions of the C runtime library functions. They are aliased here to provide future optimisation opportunities, either from faster RTLs or custom math approximations.

Note:: This is based on MgcMath.h from Wild Magic.

Definition at line 190 of file OgreMath.h.

Member Enumeration Documentation

enum Ogre::Math::AngleUnit

The angular units used by the API.

This functionality is now deprecated in favor of discreet angular unit types ( see Degree and Radian above ). The only place this functionality is actually still used is when parsing files. Search for usage of the Angle class for those instances

Enumerator:

AU_DEGREE
AU_RADIAN

Definition at line 198 of file OgreMath.h.

Constructor & Destructor Documentation

Ogre::Math::Math ( unsigned int trigTableSize = 4096 )

Default constructor.

Parameters:

trigTableSize

Optional parameter to set the size of the tables used to implement Sin, Cos, Tan

Ogre::Math::~Math ( )

Default destructor.

Member Function Documentation

static Radian Ogre::Math::Abs ( const Radian & rValue ) [static]

Absolute value function.

Parameters:

fValue

The value, in radians, whose absolute value will be returned.

Definition at line 255 of file OgreMath.h.

References Ogre::Radian::valueRadians().

static Degree Ogre::Math::Abs ( const Degree & dValue ) [static]

Absolute value function.

Parameters:

fValue

The value, in degrees, whose absolute value will be returned.

Definition at line 249 of file OgreMath.h.

References Ogre::Degree::valueDegrees().

static Real Ogre::Math::Abs ( Real fValue ) [static]

Absolute value function.

Parameters:

fValue

The value whose absolute value will be returned.

Definition at line 243 of file OgreMath.h.

Referenced by Ogre::Vector3::absDotProduct(), Ogre::Vector3::directionEquals(), Ogre::Vector3::primaryAxis(), and Ogre::AxisAlignedBox::transformAffine().

static Radian Ogre::Math::ACos ( Real fValue ) [static]

Arc cosine function.

Parameters:

fValue

The value whose arc cosine will be returned.

Referenced by Ogre::Vector3::angleBetween(), Ogre::Vector2::angleBetween(), and Ogre::Vector3::directionEquals().

static Real Ogre::Math::AngleUnitsToDegrees ( Real units ) [static]

Convert from the current AngleUnit to degrees.

Referenced by Ogre::Angle::operator Degree().

static Real Ogre::Math::AngleUnitsToRadians ( Real units ) [static]

Convert from the current AngleUnit to radians.

Referenced by Ogre::Angle::operator Radian().

static Radian Ogre::Math::ASin ( Real fValue ) [static]

Arc sine function.

Parameters:

fValue

The value whose arc sine will be returned.

static Radian Ogre::Math::ATan ( Real fValue ) [static]

Arc tangent function.

Parameters:

fValue

The value whose arc tangent will be returned.

Definition at line 273 of file OgreMath.h.

static Radian Ogre::Math::ATan2	(	Real	fY,
		Real	fX
	)			`[static]`

Arc tangent between two values function.

Parameters:

	fY	The first value to calculate the arc tangent with.
	fX	The second value to calculate the arc tangent with.

Definition at line 281 of file OgreMath.h.

static Real Ogre::Math::boundingRadiusFromAABB ( const AxisAlignedBox & aabb ) [static]

Get a bounding radius value from a bounding box.

static Matrix4 Ogre::Math::buildReflectionMatrix ( const Plane & p ) [static]

Build a reflection matrix for the passed in plane.

void Ogre::Math::buildTrigTables ( ) [protected]

Private function to build trig tables.

static Vector3 Ogre::Math::calculateBasicFaceNormal	(	const Vector3 &	v1,
		const Vector3 &	v2,
		const Vector3 &	v3
	)			`[static]`

Calculate a face normal, no w-information.

static Vector3 Ogre::Math::calculateBasicFaceNormalWithoutNormalize	(	const Vector3 &	v1,
		const Vector3 &	v2,
		const Vector3 &	v3
	)			`[static]`

Calculate a face normal without normalize, no w-information.

static Vector4 Ogre::Math::calculateFaceNormal	(	const Vector3 &	v1,
		const Vector3 &	v2,
		const Vector3 &	v3
	)			`[static]`

Calculate a face normal, including the w component which is the offset from the origin.

static Vector4 Ogre::Math::calculateFaceNormalWithoutNormalize	(	const Vector3 &	v1,
		const Vector3 &	v2,
		const Vector3 &	v3
	)			`[static]`

Calculate a face normal without normalize, including the w component which is the offset from the origin.

static Vector3 Ogre::Math::calculateTangentSpaceVector	(	const Vector3 &	position1,
		const Vector3 &	position2,
		const Vector3 &	position3,
		Real	u1,
		Real	v1,
		Real	u2,
		Real	v2,
		Real	u3,
		Real	v3
	)			`[static]`

Calculates the tangent space vector for a given set of positions / texture coords.

static Real Ogre::Math::Ceil ( Real fValue ) [static]

Ceiling function Returns the smallest following integer.

(example: Ceil(1.1) = 2)

Parameters:

fValue

The value to round up to the nearest integer.

Definition at line 289 of file OgreMath.h.

template<typename T >

static T Ogre::Math::Clamp	(	T	val,
		T	minval,
		T	maxval
	)			`[static]`

Clamp a value within an inclusive range.

Definition at line 663 of file OgreMath.h.

Referenced by Ogre::Vector3::angleBetween(), and Ogre::Vector2::angleBetween().

static Real Ogre::Math::Cos	(	Real	fValue,
		bool	useTables = `false`
	)			`[static]`

Cosine function.

Parameters:

	fValue	Angle in radians
	useTables	If true, uses lookup tables rather than calculation - faster but less accurate.

Definition at line 314 of file OgreMath.h.

static Real Ogre::Math::Cos	(	const Radian &	fValue,
		bool	useTables = `false`
	)			`[static]`

Cosine function.

Parameters:

	fValue	Angle in radians
	useTables	If true, uses lookup tables rather than calculation - faster but less accurate.

Definition at line 304 of file OgreMath.h.

References Ogre::Radian::valueRadians().

static Real Ogre::Math::DegreesToAngleUnits ( Real degrees ) [static]

Convert from degrees to the current AngleUnit.

Referenced by Ogre::Degree::valueAngleUnits().

static Real Ogre::Math::DegreesToRadians ( Real degrees ) [static]

Definition at line 448 of file OgreMath.h.

Referenced by Ogre::Degree::valueRadians().

static Real Ogre::Math::Exp ( Real fValue ) [static]

Definition at line 318 of file OgreMath.h.

static Real Ogre::Math::Floor ( Real fValue ) [static]

Floor function Returns the largest previous integer.

(example: Floor(1.9) = 1)

Parameters:

fValue

The value to round down to the nearest integer.

Definition at line 326 of file OgreMath.h.

static Real Ogre::Math::gaussianDistribution	(	Real	x,
		Real	offset = `0.0f`,
		Real	scale = `1.0f`
	)			`[static]`

Generates a value based on the Gaussian (normal) distribution function with the given offset and scale parameters.

static AngleUnit Ogre::Math::getAngleUnit ( void ) [static]

Get the unit being used for angles.

static int Ogre::Math::IAbs ( int iValue ) [static]

Definition at line 234 of file OgreMath.h.

static int Ogre::Math::ICeil ( float fValue ) [static]

Definition at line 235 of file OgreMath.h.

static int Ogre::Math::IFloor ( float fValue ) [static]

Definition at line 236 of file OgreMath.h.

static bool Ogre::Math::intersects	(	const Sphere &	sphere,
		const Plane &	plane
	)			`[static]`

Sphere / plane intersection test.

Remarks:: NB just do a plane.getDistance(sphere.getCenter()) for more detail!

static std::pair<bool, Real> Ogre::Math::intersects	(	const Ray &	ray,
		const list< Plane >::type &	planeList,
		bool	normalIsOutside
	)			`[static]`

Ray / convex plane list intersection test.

Parameters:

	ray	The ray to test with
	plaeList	List of planes which form a convex volume
	normalIsOutside	Does the normal point outside the volume

static std::pair<bool, Real> Ogre::Math::intersects	(	const Ray &	ray,
		const vector< Plane >::type &	planeList,
		bool	normalIsOutside
	)			`[static]`

Ray / convex plane list intersection test.

Parameters:

	ray	The ray to test with
	plaeList	List of planes which form a convex volume
	normalIsOutside	Does the normal point outside the volume

static bool Ogre::Math::intersects	(	const Plane &	plane,
		const AxisAlignedBox &	box
	)			`[static]`

Plane / box intersection test.

static bool Ogre::Math::intersects	(	const Sphere &	sphere,
		const AxisAlignedBox &	box
	)			`[static]`

Sphere / box intersection test.

static std::pair<bool, Real> Ogre::Math::intersects	(	const Ray &	ray,
		const Vector3 &	a,
		const Vector3 &	b,
		const Vector3 &	c,
		bool	positiveSide = `true`,
		bool	negativeSide = `true`
	)			`[static]`

Ray / triangle intersection, returns boolean result and distance.

Parameters:

	ray	The ray.
	a	The triangle's first vertex.
	b	The triangle's second vertex.
	c	The triangle's third vertex.
	positiveSide	Intersect with "positive side" of the triangle
	negativeSide	Intersect with "negative side" of the triangle

Returns:: If the ray is intersects the triangle, a pair of true and the distance between intersection point and ray origin returned.

: If the ray isn't intersects the triangle, a pair of false and 0 returned.

static std::pair<bool, Real> Ogre::Math::intersects	(	const Ray &	ray,
		const Vector3 &	a,
		const Vector3 &	b,
		const Vector3 &	c,
		const Vector3 &	normal,
		bool	positiveSide = `true`,
		bool	negativeSide = `true`
	)			`[static]`

Ray / triangle intersection, returns boolean result and distance.

Parameters:

	ray	The ray.
	a	The triangle's first vertex.
	b	The triangle's second vertex.
	c	The triangle's third vertex.
	normal	The triangle plane's normal (passed in rather than calculated on demand since the caller may already have it), doesn't need normalised since we don't care.
	positiveSide	Intersect with "positive side" of the triangle
	negativeSide	Intersect with "negative side" of the triangle

Returns:: If the ray is intersects the triangle, a pair of true and the distance between intersection point and ray origin returned.

: If the ray isn't intersects the triangle, a pair of false and 0 returned.

static bool Ogre::Math::intersects	(	const Ray &	ray,
		const AxisAlignedBox &	box,
		Real *	d1,
		Real *	d2
	)			`[static]`

Ray / box intersection, returns boolean result and two intersection distance.

Parameters:

	ray	The ray.
	box	The box.
	d1	A real pointer to retrieve the near intersection distance from the ray origin, maybe null which means don't care about the near intersection distance.
	d2	A real pointer to retrieve the far intersection distance from the ray origin, maybe null which means don't care about the far intersection distance.

Returns:: If the ray is intersects the box, true is returned, and the near intersection distance is return by d1, the far intersection distance is return by d2. Guarantee 0 <= d1 <= d2.

: If the ray isn't intersects the box, false is returned, and d1 and d2 is unmodified.

static std::pair<bool, Real> Ogre::Math::intersects	(	const Ray &	ray,
		const AxisAlignedBox &	box
	)			`[static]`

Ray / box intersection, returns boolean result and distance.

static std::pair<bool, Real> Ogre::Math::intersects	(	const Ray &	ray,
		const Sphere &	sphere,
		bool	discardInside = `true`
	)			`[static]`

Ray / sphere intersection, returns boolean result and distance.

static std::pair<bool, Real> Ogre::Math::intersects	(	const Ray &	ray,
		const Plane &	plane
	)			`[static]`

Ray / plane intersection, returns boolean result and distance.

Referenced by Ogre::Sphere::intersects(), Ogre::Ray::intersects(), Ogre::PlaneBoundedVolume::intersects(), and Ogre::AxisAlignedBox::intersects().

static Real Ogre::Math::InvSqrt ( Real fValue ) [static]

Inverse square root i.e.

1 / Sqrt(x), good for vector normalisation.

Parameters:

fValue

The value whose inverse square root will be calculated.

static int Ogre::Math::ISign ( int iValue ) [static]

static bool Ogre::Math::isNaN ( Real f ) [static]

Definition at line 290 of file OgreMath.h.

Referenced by Ogre::Vector4::isNaN(), Ogre::Vector3::isNaN(), Ogre::Vector2::isNaN(), Ogre::Quaternion::isNaN(), and Ogre::DualQuaternion::isNaN().

static Real Ogre::Math::Log ( Real fValue ) [static]

Definition at line 328 of file OgreMath.h.

static Real Ogre::Math::Log2 ( Real fValue ) [static]

Definition at line 333 of file OgreMath.h.

static Real Ogre::Math::LogN	(	Real	base,
		Real	fValue
	)			`[static]`

Definition at line 335 of file OgreMath.h.

static Matrix4 Ogre::Math::makeViewMatrix	(	const Vector3 &	position,
		const Quaternion &	orientation,
		const Matrix4 *	reflectMatrix = `0`
	)			`[static]`

static bool Ogre::Math::pointInTri2D	(	const Vector2 &	p,
		const Vector2 &	a,
		const Vector2 &	b,
		const Vector2 &	c
	)			`[static]`

Checks whether a given point is inside a triangle, in a 2-dimensional (Cartesian) space.

Remarks:: The vertices of the triangle must be given in either trigonometrical (anticlockwise) or inverse trigonometrical (clockwise) order.

Parameters:

	p	The point.
	a	The triangle's first vertex.
	b	The triangle's second vertex.
	c	The triangle's third vertex.

Returns:: If the point resides in the triangle, true is returned.

: If the point is outside the triangle, false is returned.

static bool Ogre::Math::pointInTri3D	(	const Vector3 &	p,
		const Vector3 &	a,
		const Vector3 &	b,
		const Vector3 &	c,
		const Vector3 &	normal
	)			`[static]`

Checks whether a given 3D point is inside a triangle.

Remarks:: The vertices of the triangle must be given in either trigonometrical (anticlockwise) or inverse trigonometrical (clockwise) order, and the point must be guaranteed to be in the same plane as the triangle

Parameters:

	p	The point.
	a	The triangle's first vertex.
	b	The triangle's second vertex.
	c	The triangle's third vertex.
	normal	The triangle plane's normal (passed in rather than calculated on demand since the caller may already have it)

Returns:: If the point resides in the triangle, true is returned.

: If the point is outside the triangle, false is returned.

static Real Ogre::Math::Pow	(	Real	fBase,
		Real	fExponent
	)			`[static]`

Definition at line 337 of file OgreMath.h.

static Real Ogre::Math::RadiansToAngleUnits ( Real radians ) [static]

Convert from radians to the current AngleUnit .

Referenced by Ogre::Radian::valueAngleUnits().

static Real Ogre::Math::RadiansToDegrees ( Real radians ) [static]

Definition at line 449 of file OgreMath.h.

Referenced by Ogre::Radian::valueDegrees().

static Real Ogre::Math::RangeRandom	(	Real	fLow,
		Real	fHigh
	)			`[static]`

Generate a random number within the range provided.

Parameters:

	fLow	The lower bound of the range.
	fHigh	The upper bound of the range.

Returns:: A random number in the range from [fLow,fHigh].

static bool Ogre::Math::RealEqual	(	Real	a,
		Real	b,
		Real	tolerance = `std::numeric_limits< Real >::epsilon()`
	)			`[static]`

Compare 2 reals, using tolerance for inaccuracies.

Referenced by Ogre::Matrix4::hasScale(), Ogre::Matrix3::hasScale(), Ogre::QueuedRenderableCollection::DepthSortDescendingLess::operator()(), and Ogre::Vector3::positionEquals().

static void Ogre::Math::setAngleUnit ( AngleUnit unit ) [static]

These functions used to set the assumed angle units (radians or degrees) expected when using the Angle type.

: You can set this directly after creating a new Root, and also before/after resource creation, depending on whether you want the change to affect resource files.

static Degree Ogre::Math::Sign ( const Degree & dValue ) [static]