Math

Functions for dealing with vectors and matrices etc.

Functions

Point3F getBoxCenter(Box3F box)

Get the center point of an axis-aligned box.

Parameters:b – A Box3F, in string format using “minExtentX minExtentY minExtentZ maxExtentX maxExtentY maxExtentZ”
Returns:Center of the box.
float getMax(float v1, float v2)

Calculate the greater of two specified numbers.

Parameters:
  • v1 – Input value.
  • v2 – Input value.
Returns:

The greater value of the two specified values.
float getMin(float v1, float v2)

Calculate the lesser of two specified numbers.

Parameters:
  • v1 – Input value.
  • v2 – Input value.
Returns:

The lesser value of the two specified values.
float m2Pi()

Return the value of 2*PI (full-circle in radians).

Returns:The value of 2*PI.
float mAbs(float v)

Calculate absolute value of specified value.

Parameters:v – Input Value.
Returns:Absolute value of specified value.
float mAcos(float v)

Calculate the arc-cosine of v.

Parameters:v – Input Value (in radians).
Returns:The arc-cosine of the input value.
float mAsin(float v)

Calculate the arc-sine of v.

Parameters:v – Input Value (in radians).
Returns:The arc-sine of the input value.
float mAtan(float rise, float run)

Calculate the arc-tangent (slope) of a line defined by rise and run.

Parameters:
  • rise – of line.
  • run – of line.
Returns:

The arc-tangent (slope) of a line defined by rise and run.
void mathInit(...)

Install the math library with specified extensions. Possible parameters are:

  • ‘DETECT’ Autodetect math lib settings.
  • ‘C’ Enable the C math routines. C routines are always enabled.
  • ‘FPU’ Enable floating point unit routines.
  • ‘MMX’ Enable MMX math routines.
  • ‘3DNOW’ Enable 3dNow! math routines.
  • ‘SSE’ Enable SSE math routines.
int mCeil(float v)

Round v up to the nearest integer.

Parameters:v – Number to convert to integer.
Returns:Number converted to integer.
float mClamp(float v, float min, float max)

Clamp the specified value between two bounds.

Parameters:
  • v – Input value.
  • min – Minimum Bound.
  • max – Maximum Bound.
Returns:

The specified value clamped to the specified bounds.
float mCos(float v)

Calculate the cosine of v.

Parameters:v – Input Value (in radians).
Returns:The cosine of the input value.
float mDegToRad(float degrees)

Convert specified degrees into radians.

Parameters:degrees – Input Value (in degrees).
Returns:The specified degrees value converted to radians.
string mFloatLength(float v, int precision)

Formats the specified number to the given number of decimal places.

Parameters:
  • v – Number to format.
  • precision – Number of decimal places to format to (1-9).
Returns:

Number formatted to the specified number of decimal places.
int mFloor(float v)

Round v down to the nearest integer.

Parameters:v – Number to convert to integer.
Returns:Number converted to integer.
float mFMod(float v, float d)

Calculate the remainder of v/d.

Parameters:
  • v – Input Value.
  • d – Divisor Value.
Returns:

The remainder of v/d.
bool mIsPow2(int v)

Returns whether the value is an exact power of two.

Parameters:v – Input value.
Returns:Whether the specified value is an exact power of two.
float mLerp(float v1, float v2, float time)

Calculate linearly interpolated value between two specified numbers using specified normalized time.

Parameters:
  • v1 – Interpolate From Input value.
  • v2 – Interpolate To Input value.
  • time – Normalized time used to interpolate values (0-1).
Returns:

The interpolated value between the two specified values at normalized time t.
float mLog(float v)

Calculate the natural logarithm of v.

Parameters:v – Input Value.
Returns:The natural logarithm of the input value.
float mPi()

Return the value of PI (half-circle in radians).

Returns:The value of PI.
float mPow(float v, float p)

Calculate b raised to the p-th power.

Parameters:
  • v – Input Value.
  • p – Power to raise value by.
Returns:

v raised to the p-th power.
float mRadToDeg(float radians)

Convert specified radians into degrees.

Parameters:radians – Input Value (in radians).
Returns:The specified radians value converted to degrees.
int mRound(float v)

Round v to the nearest integer.

Parameters:v – Number to convert to integer.
Returns:Number converted to integer.
float mSaturate(float v)

Clamp the specified value between 0 and 1 (inclusive).

Parameters:v – Input value.
Returns:The specified value clamped between 0 and 1 (inclusive).
float mSin(float v)

Calculate the sine of v.

Parameters:v – Input Value (in radians).
Returns:The sine of the input value.
string mSolveCubic(float a, float b, float c, float d)

Solve a cubic equation (3rd degree polynomial) of form a*x^3 + b*x^2 + c*x + d = 0.

Parameters:
  • a – First Coefficient.
  • b – Second Coefficient.
  • c – Third Coefficient.
  • d – Fourth Coefficient.
Returns:

A 4-tuple, containing: (sol x0 x1 x2). (sol) is the number of solutions(being 0, 1, 2 or 3), and (x0), (x1) and (x2) are the solutions, if any.
string mSolveQuadratic(float a, float b, float c)

Solve a quadratic equation (2nd degree polynomial) of form a*x^2 + b*x + c = 0.

Parameters:
  • a – First Coefficient.
  • b – Second Coefficient.
  • c – Third Coefficient.
Returns:

A triple, containing: (sol x0 x1). (sol) is the number of solutions(being 0, 1, or 2), and (x0) and (x1) are the solutions, if any.
string mSolveQuartic(float a, float b, float c, float d, float e)

Solve a quartic equation (4th degree polynomial) of form a*x^4 + b*x^3 + c*x^2 + d*x + e = 0.

Parameters:
  • a – First Coefficient.
  • b – Second Coefficient.
  • c – Third Coefficient.
  • d – Fourth Coefficient.
  • e – Fifth Coefficient.
Returns:

A 5-tuple, containing: (sol x0 x1 x2 c3). (sol) is the number of solutions(being 0, 1, 2, 3 or 4), and (x0), (x1), (x2) and (x3) are the solutions, if any.
float mSqrt(float v)

Calculate the square-root of v.

Parameters:v – Input Value.
Returns:The square-root of the input value.
float mTan(float v)

Calculate the tangent of v.

Parameters:v – Input Value (in radians).
Returns:The tangent of the input value.

Vector Math

Functions for working with three-dimensional vectors (VectorF/Point3F).

Functions

VectorF VectorAdd(VectorF a, VectorF b)

Add two vectors.

Parameters:
  • a – The first vector.
  • b – The second vector.
Returns:

.

Example:

// VectorAdd( %a, %b );
// The sum of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
//     a + b = ( ax + bx, ay + by, az + bz )

%a = "1 0 0";
%b = "0 1 0";

// %r = "( 1 + 0, 0 + 1, 0 + 0 )";// %r = "1 1 0";
%r = VectorAdd( %a, %b );
VectorF VectorCross(VectorF a, VectorF b)

Calculcate the cross product of two vectors.

Parameters:
  • a – The first vector.
  • b – The second vector.
Returns:

.

Example:

// VectorCross( %a, %b );
// The cross product of vector a, (ax, ay, az), and vector b, (bx, by, bz), is
//     a x b = ( ( ay * bz ) - ( az * by ), ( az * bx ) - ( ax * bz ), ( ax * by ) - ( ay * bx ) )

%a = "1 1 0";
%b = "2 0 1";

// %r = "( ( 1 * 1 ) - ( 0 * 0 ), ( 0 * 2 ) - ( 1 * 1 ), ( 1 * 0 ) - ( 1 * 2 ) )";
// %r = "1 -1 -2";
%r = VectorCross( %a, %b );
float VectorDist(VectorF a, VectorF b)

Compute the distance between two vectors.

Parameters:
  • a – The first vector.
  • b – The second vector.
Returns:

).

Example:

// VectorDist( %a, %b );
// The distance between vector a, (ax, ay, az), and vector b, (bx, by, bz), is
//     a -> b = ||( b - a )||
//            = ||( bx - ax, by - ay, bz - az )||
//            = mSqrt( ( bx - ax ) * ( bx - ax ) + ( by - ay ) * ( by - ay ) + ( bz - az ) * ( bz - az ) )

%a = "1 1 0";
%b = "2 0 1";

// %r = mSqrt( ( 2 - 1 ) * ( 2 - 1) + ( 0 - 1 ) * ( 0 - 1 ) + ( 1 - 0 ) * ( 1 - 0 ) );
// %r = mSqrt( 3 );
%r = VectorDist( %a, %b );
float VectorDot(VectorF a, VectorF b)

Compute the dot product of two vectors.

Parameters:
  • a – The first vector.
  • b – The second vector.
Returns:

.

Example:

// VectorDot( %a, %b );
// The dot product between vector a, (ax, ay, az), and vector b, (bx, by, bz), is:
//     a . b = ( ax * bx + ay * by + az * bz )

%a = "1 1 0";
%b = "2 0 1";

// %r = "( 1 * 2 + 1 * 0 + 0 * 1 )";
// %r = 2;
%r = VectorDot( %a, %b );
float VectorLen(VectorF v)

Calculate the magnitude of the given vector.

Parameters:v – A vector.
Returns:.

Example:

// VectorLen( %a );
// The length or magnitude of  vector a, (ax, ay, az), is:
//     ||a|| = Sqrt( ax * ax + ay * ay + az * az )

%a = "1 1 0";

// %r = mSqrt( 1 * 1 + 1 * 1 + 0 * 0 );
// %r = mSqrt( 2 );
// %r = 1.414;
%r = VectorLen( %a );
VectorF VectorLerp(VectorF a, VectorF b, float t)

Linearly interpolate between two vectors by t .

Parameters:
  • a – Vector to start interpolation from.
  • b – Vector to interpolate to.
  • t – Interpolation factor (0-1). At zero, a is returned and at one, b is returned. In between, an interpolated vector between a and b is returned.
Returns:

.

Example:

// VectorLerp( %a, %b );
// The point between vector a, (ax, ay, az), and vector b, (bx, by, bz), which is
// weighted by the interpolation factor, t, is
//     r = a + t * ( b - a )
//       = ( ax + t * ( bx - ax ), ay + t * ( by - ay ), az + t * ( bz - az ) )

%a = "1 1 0";
%b = "2 0 1";
%v = "0.25";

// %r = "( 1 + 0.25 * ( 2 - 1 ), 1 + 0.25 * ( 0 - 1 ), 0 + 0.25 * ( 1 - 0 ) )";
// %r = "1.25 0.75 0.25";
%r = VectorLerp( %a, %b );
VectorF VectorNormalize(VectorF v)

Brings a vector into its unit form, i.e. such that it has the magnitute 1.

Parameters:v – The vector to normalize.
Returns:scaled to length 1.

Example:

// VectorNormalize( %a );
// The normalized vector a, (ax, ay, az), is:
//     a^ = a / ||a||
//        = ( ax / ||a||, ay / ||a||, az / ||a|| )

%a = "1 1 0";
%l = 1.414;

// %r = "( 1 / 1.141, 1 / 1.141, 0 / 1.141 )";
// %r = "0.707 0.707 0";
%r = VectorNormalize( %a );
MatrixF VectorOrthoBasis(AngAxisF aa)

Create an orthogonal basis from the given vector.

Parameters:aaf – The vector to create the orthogonal basis from.
Returns:A matrix representing the orthogonal basis.
VectorF VectorScale(VectorF a, float scalar)

Scales a vector by a scalar.

Parameters:
  • a – The vector to scale.
  • scalar – The scale factor.
Returns:

.

Example:

// VectorScale( %a, %v );
// Scaling vector a, (ax, ay, az), but the scalar, v, is:
//     a * v = ( ax * v, ay * v, az * v )

%a = "1 1 0";
%v = "2";

// %r = "( 1 * 2, 1 * 2, 0 * 2 )";
// %r = "2 2 0";
%r = VectorScale( %a, %v );
VectorF VectorSub(VectorF a, VectorF b)

Subtract two vectors.

Parameters:
  • a – The first vector.
  • b – The second vector.
Returns:

.

Example:

// VectorSub( %a, %b );
// The difference of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
//     a - b = ( ax - bx, ay - by, az - bz )

%a = "1 0 0";
%b = "0 1 0";

// %r = "( 1 - 0, 0 - 1, 0 - 0 )";
// %r = "1 -1 0";
%r = VectorSub( %a, %b );

Matrix Math

Functions for working with matrices (MatrixF, AngAxisF, MatrixRotation, MatrixPosition).

Functions

TransformF MatrixCreate(VectorF position, AngAxisF orientation)

Create a transform from the given translation and orientation.

Parameters:
  • position – The translation vector for the transform.
  • orientation – The axis and rotation that orients the transform.
Returns:

A transform based on the given position and orientation.
TransformF MatrixCreateFromEuler(Point3F angles)

a matrix from the given rotations.

Parameters:Vector3F – X, Y, and Z rotation in radians.
Returns:A transform based on the given orientation.
Point3F MatrixMulPoint(TransformF transform, Point3F point)

Multiply the given point by the given transform assuming that w=1. This function will multiply the given vector such that translation with take effect.

Parameters:
  • transform – A transform.
  • point – A vector.
Returns:

The transformed vector.
TransformF MatrixMultiply(TransformF left, TransformF right)

Multiply the two matrices.

Parameters:
  • left – First transform.
  • right – Right transform.
Returns:

Concatenation of the two transforms.
VectorF MatrixMulVector(TransformF transform, VectorF vector)

Multiply the vector by the transform assuming that w=0. This function will multiply the given vector by the given transform such that translation will not affect the vector.

Parameters:
  • transform – A transform.
  • vector – A vector.
Returns:

The transformed vector.

Random Numbers

Functions for generating random numbers. Based on a seed, the random number generator produces a sequence of numbers. As a given seed will always produce the same sequence of numbers this can be used to generate re-producible sequences of apparently random numbers. To set the seed, call setRandomSeed().

Functions

float getRandom(int a, int b)

Returns a random number based on parameters passed in.. If no parameters are passed in, getRandom() will return a float between 0.0 and 1.0. If one parameter is passed an integer between 0 and the passed in value will be returned. Two parameters will return an integer between the specified numbers.

Parameters:
  • a – If this is the only parameter, a number between 0 and a is returned. Elsewise represents the lower bound.
  • b – Upper bound on the random number. The random number will be <= b.
Returns:

, between 0 and a, or a float between 0.0 and 1.1 depending on usage.
int getRandomSeed()

Get the current seed used by the random number generator.

Returns:The current random number generator seed value.
void setRandomSeed(int seed)

Set the current seed for the random number generator. Based on this seed, a repeatable sequence of numbers will be produced by getRandom() .

Parameters:seed – The seed with which to initialize the randon number generator with. The same seed will always leed tothe same sequence of pseudo-random numbers. If -1, the current timestamp will be used as the seed which is a good basis for randomization.