# general_math

Mathematical functions

## Definition

global general_math
{
public:
float Degree(float x);
vector MinimizeAngle(vector a1, vector a2);
vector VectorToHPB(vector v);
vector HSVToRGB(vector hsv);
vector RGBToHSV(vector rgb);
vector PointLineDistance(vector p0, vector v0, vector q);
anytype abs(anytype x);
float acos(anytype x);
float asin(anytype x);
float atan(anytype x);
float ceil(float x);
float cos(float x);
float cosh(float x);
float exp(float x);
float floor(float x);
float log(anytype x);
float log10(anytype x);
float pow(anytype base, anytype x);
float sin(anytype x);
float sinh(anytype x);
float sqrt(anytype x);
float tan(anytype x);
float tanh(anytype x);
vector vcross(vector v1, vector v2);
float vlen(vector v);
vector vnorm(vector v);
float Modulo(float a, float b);
float Step(float a, float x);
float Pulse(float a, float b, float x);
float Clamp(float a, float b, float x);
float BoxStep(float a, float b, float x);
float SmoothStep(float a, float b, float x);
float GammaCorrect(float gamma, float x);
float Bias(float bias, float x);
float Gain(float g, float x);
anytype Mix(anytype a, anytype b, anytype x);
};

## Members

#### float Degree(float x)

Returns the angle x converted to degrees.

##### Parameters
float x

x is an angle measured in radians. (360° = 2 * Pi radians)

Returns the angle x converted to radians.

##### Parameters
float x

x is an angle measured in degree.

#### vector MinimizeAngle(vector a1, vector a2)

The change of the HPB angles from a1 to a2 might include loops with angles greater than 180°. This function returns a new value of a2 that represents the same rotation, but won't create loops when one rotates from a1 to a2.

##### Parameters
vector a1

a1 is a vector that contains HPB angles.

vector a2

a2 is a another vector that contains HPB angles.

#### vector VectorToHPB(vector v)

Returns HPB angles from the vector v.

##### Parameters
vector v

A directional vector.

#### vector HSVToRGB(vector hsv)

Converts hsv into the RGB color space and returns the converted value.

##### Parameters
vector hsv

A vector the encodes a color value in HSV space

#### vector RGBToHSV(vector rgb)

Converts rgb into the HSV color space and returns the converted value.

##### Parameters
vector rgb

A vector that encodes a color in RGB space

#### vector PointLineDistance(vector p0, vector v0, vector q)

Returns the shortest vector between the point q and the line defined by the starting point p0 and the direction v0. The returned vector points from the nearest point on the line to q. Therefore the length of the returned vector gives the shortest distance between the line and q.

##### Parameters
vector p0

Defines the start position of the line.

vector v0

Defines direction and length of the line.

vector q

The position of the point.

#### anytype abs(anytype x)

Calculates the absolute value of a variable.

Example:

// Outputs "abs(x) = 4.7000".

var x = -4.7;
var a = abs(x);

println("abs(x) = ",a);

##### Return
anytype

Result may be int or float

abs() returns the absolute value of x. That means that any minus signs are removed from the value, so that the return value is always positive.

##### Parameters
anytype x

x is a numeric value

#### float acos(anytype x)

Calculates the arc cosine value (abbreviated acos) of a value.

Example:

// Outputs "acos(x) = 1.772154".

var x = -0.2;
var a = acos(x);

println("acos(x) = ",a);

// To convert an angle given in radians to degrees one can
// simply use the SDK function Degree().
//
// Outputs "acos(0.5) = 60.0000°".

var x = 0.5;
var a = Degree(acos(x));

println("acos(0.5) = ",a,"°");

##### Return
float

acos() returns the arc cosine value of x. This will be an angle measured in radians. (360° = 2p radians) Arc cosine is the inverse function of cosine. For more information on the arc cosine function, please refer to a math book.

##### Parameters
anytype x

x is a numeric value between -1 and 1.
Arc cosine is not defined for x > 1 and x < -1.

#### float asin(anytype x)

Calculates the arc sine value (abbreviated asin) of a value.

Example:

// Outputs "asin(x) = -0.201358".

var x = -0.2;
var a = asin(x);

println("asin(x) = ",a);

// To convert an angle given in radians to degrees one can
// simply use the SDK function Degree().
//
// Outputs "asin(0.5) = 30.0000°".

var x = 0.5;
var a = Degree(asin(x));

println("asin(0.5) = ",a,"°");

##### Return
float

asin() returns the arc sine value of x. This will be an angle measured in radians. (360° = 2p radians) Arc sine is the inverse function of sine. For more information on the arc sine function, please refer to a math book.

##### Parameters
anytype x

x is a numeric value between -1 and 1.
Arc sine is not defined for x > 1 and x < -1.

#### float atan(anytype x)

Calculates the arc tangent value (abbreviated atan) of a value.

Example:

// Outputs "atan(x) = -0.197396".

var x = -0.2;
var a = atan(x);

println("atan(x) = ",a);

// To convert an angle given in radians to degrees one can
// simply use the SDK function Degree().
//
// Outputs "atan(1.0) = 45.0000°".

var x = 1.0;
var a = Degree(atan(x));

println("atan(1.0) = ",a,"°");

##### Return
float

atan() returns the arc tangent value of x. This will be an angle measured in radians. (360° = 2p radians) Arc tangent is the inverse function of tangent. For more information on the arc tangent function, please refer to a math book.

##### Parameters
anytype x

x is a numeric value.

#### float ceil(float x)

Rounds a variable up to the nearest whole number.

Example:

// Outputs "ceil(a) = 3.0000
//          ceil(b) = -2.0000".

var a = 2.5;
var b = -2.5;

println("ceil(a) = ",ceil(a));
println("ceil(b) = ",ceil(b));

##### Return
float

ceil() returns the smallest whole number that is larger than or equal to x.

##### Parameters
float x

x is a numeric value.

#### float cos(float x)

Calculates the cosine value (abbreviated cos) of an angle.

Example:

// Outputs "cos(x) = 0.416147".

var x = 2.0;
var a = cos(x);

println("cos(x) = ",a);

// To convert an angle given in degrees to radians one can
// simply use the SDK function Radians().
//
// Outputs "cos(60°) = 0.5000".

var x = 60.0;

println("cos(60°) = ",a);

##### Return
float

cos() returns the cosine value of x. For a definition of the cosine function, please refer to a math book.

##### Parameters
float x

x is an angle measured in radians. (360° = 2 * Pi radians)

#### float cosh(float x)

Calculates the hyperbolic cosine value (abbreviated cosh) of a variable.

Example:

// Outputs "cosh(x) = 3.762196".

var x = 2.0;
var a = cosh(x);

println("cosh(x) = ",a);

##### Return
float

cosh() returns the hyperbolic cosine value of x. This is defined as (ex+e-x)/2. For more information on the hyperbolic cosine function, please refer to a math book.

##### Parameters
float x

x is a numeric value.

#### float exp(float x)

Calculates the mathematical constant e raised to a given power (e is approx. 2.718282).

Example:

// Outputs "exp(x) = 7.389056".

var x = 2.0;
var a = exp(x);

println("exp(x) = ",a);

##### Return
float

exp() returns e raised to the power x, that is ex. For more information on the use of this function, please refer to a math book.

##### Parameters
float x

x is a numeric value.

#### float floor(float x)

Rounds a variable down to the nearest whole number.

Example:

// Outputs "floor(a) = 2.0000
//          floor(b) = -3.0000".

var a = 2.5;
var b = -2.5;

println("floor(a) = ",floor(a));
println("floor(b) = ",floor(b));

// On can use floor() to get the decimal part of a float.
//
// Outputs "fpart(x) = 0.7".

fpart(x)
{
return x - floor(x);
}

var x = 4.7;
var a = fpart(x);

println("fpart(x) = ",a);

##### Return
float

floor() returns the largest whole number that is less than or equal to x.

##### Parameters
float x

x is a numeric value.

#### float log(anytype x)

Calculates the natural logarithm (abbreviated log) of a variable.

Example:

// Outputs "log(x) = 0.693147".

var x = 2.0;
var a = log(x);

println("log(x) = ",a);

// One can use the natural logarithm to calculate the logarithm
// in any base using the simple formula below.
//
// Outputs "logn(2,x) = 5.0000".

logn(base,x)
{
return log(x)/log(base);
}

var x = 32.0;
var a = logn(2,x);

println("logn(2,x) = ",a);

##### Return
float

log() returns the natural logarithm of x. The natural logarithm is the inverse to the function exp(). For more information on the use of logarithms, please refer to a math book.

##### Parameters
anytype x

x is a numeric value. Logarithms are not defined for x <= 0.

#### float log10(anytype x)

Calculates the logarithm of of a variable in base 10 (abbreviated log10).

Example:

// Outputs "log10(x) = 0.301030".

var x = 2.0;
var a = log10(x);

println("log10(x) = ",a);

##### Return
float

log10() returns the logarithm of x in base 10. This is the inverse to the function 10x or pow(10,x) in code. For more information on the use of logarithms, please refer to a math book.

##### Parameters
anytype x

x is a numeric value. Logarithms are not defined for x <= 0.

#### float pow(anytype base, anytype x)

Raises a variable raised to a given power.

Example:

// Outputs "pow(3.5,x) = 12.2500".

var x = 2.0;
var a = pow(3.5,x);

println("pow(3.5,x) = ",a);

// For simple whole number powers, like 2 or 3, it is often faster
// to use several multiplications instead.
//
// Outputs "x*x = 22.0900".

var x = 4.7;
var a = x*x; // Instead of pow(x,2);

println("x*x = ",a);

##### Return
float

pow() returns base raised to the power of x, that is base^x. For more information on the power function, please refer to a math book.

##### Parameters
anytype base

The base.

anytype - int or float

anytype x

The exponent.

anytype - int or float

#### float sin(anytype x)

Calculates the sine value (abbreviated sin) of an angle.

Example:

// Outputs "sin(x) = 0.909297".

var x = 2.0;
var a = sin(x);

println("sin(x) = ",a);

// To convert an angle given in degrees to radians one can
// simply use the SDK function Radians().
//
// Outputs "sin(30°) = 0.5000".

var x = 30.0;

println("sin(30°) = ",a);

##### Return
float

sin() returns the sine value of x. For a definition of the sine function, please refer to a math book.

anytype x

A numeric value.

#### float sinh(anytype x)

Calculates the hyperbolic sine value (abbreviated sinh) of a variable.

Example:

// Outputs "sinh(x) = 3.626860".

var x = 2.0;
var a = sinh(x);

println("sinh(x) = ",a);

##### Return
float

sinh() returns the hyperbolic sine value of x. This is defined as ((e^x)-e^(-x))/2. For more information on the hyperbolic sine function, please refer to a math book.

anytype x

A numeric value.

#### float sqrt(anytype x)

Calculates the square root (abbreviated sqrt) of a variable.

Example:

// Outputs "sqrt(x) = 1.414214".

var x = 2.0;
var a = sqrt(x);

println("sqrt(x) = ",a);

##### Return
float

sqrt() returns the square root of x. The square root of a number is the positive number that multiplied by itself equals the original number, that is sqrt(x) * sqrt(x) = x. Extracting the square root of a number is the same as raising it to the power of one half, that is x ^ (1/2) or pow(x, 0.5) in code. For more information on the square root function, please refer to a math book.

anytype x

A numeric value.

#### float tan(anytype x)

Calculates the tangent value (abbreviated tan) of an angle.

Example:

// Outputs "tan(x) = -2.185040".

var x = 2.0;
var a = tan(x);

println("tan(x) = ",a);

// To convert an angle given in degrees to radians one can
// simply use the SDK function Radians().
//
// Outputs "tan(45°) = 0.5000".

var x = 45.0;

println("tan(45°) = ",a);

##### Return
float

tan() returns the tangent value of x. This is the same as the sine value of x divided by the cosine value of x. For more information on the tangent function, please refer to a math book.

##### Parameters
anytype x

x is an angle measured in radians. (360° = 2 * pi radians)
Tangent is not defined for odd multiples of pi/2.

anytype - int or float

#### float tanh(anytype x)

Calculates the hyperbolic tangent value (abbreviated tanh) of a variable.

Example:

// Outputs "tanh(x) = 0.964028".

var x = 2.0;
var a = tanh(x);

println("tanh(x) = ",a);

##### Return
float

tanh() returns the hyperbolic tangent value of x. This is defined as (e^x - e^-x) / (e^x + e^-x). For more information on the hyperbolic tangent function, please refer to a math book.

##### Parameters
anytype x

x is a numeric value.

anytype - int or float

#### vector vcross(vector v1, vector v2)

Calculates the cross product of two vectors.

Example:

// The cross product of the x-axis and the y-axis
// is of course the z-axis.
//
// Outputs "vcross(v1,v2) = [0.0000,0.0000,1.0000]".

var v1 = vector(1.0,0.0,0.0);
var v2 = vector(0.0,1.0,0.0);

var v = vcross(v1,v2);

println("vcross(v1,v2) = ",v);

// Using cross products, one can easily form an orthogonal
// coordinate system out of just two vectors. One of the
// vectors become the x-axis, the other just defines the
// xy-plane. (To make it easier to visualize the example
// I've chosen v1 and v2 so that the algorithm outputs
// the basic coordinate axes.)
//
// Outputs "x-axis = [1.0000,0.0000,0.0000]
//          y-axis = [0.0000,1.0000,0.0000]
//          z-axis = [0.0000,0.0000,1.0000]"

var v1 = vector(10.0,0.0,0.0); // Try to picture these two
var v2 = vector(5.0,5.0,0.0);  // vectors in the editor.

var xaxis = v1;               // With the above definition in mind,
var zaxis = vcross(xaxis,v2); // try to understand what these two
var yaxis = vcross(zaxis,v1); // vcross operations do.

xaxis = vnorm(xaxis); // Normalize the axes
yaxis = vnorm(yaxis);
zaxis = vnorm(zaxis);

println("x-axis = ",xaxis);
println("y-axis = ",zaxis);
println("z-axis = ",zaxis);

##### Return
vector

vcross() returns the cross product of v1 and v2. Mathematically this is calculated with vector(v1.y*v2.z - v1.z*v2.y , v1.z*v2.x - v1.x*v2.z , v1.x*v2.y - v1.y*v2.x).

What characterizes the cross product is that it's orthogonal to both v1 and v2 (as long as they aren't parallell). This can be visualized as the normal to the plane that v1 and v2 form.

vector v1

A vector.

vector v2

Another vector.

#### float vlen(vector v)

Calculates the length of a vector.

Example:

// Outputs "vlen(v) = 3.0000".

var v = vector(1.0,2.0,2.0);
var a = vlen(v);

println("vlen(v) = ",a);

// vlen() can be used to measure the distance between
// two points or object positions.
//
// Outputs "distance(p1,p2) = 500.0000".

distance(p1,p2)
{
// Calculates the length of the vector
// that goes from p1 to p2.

return vlen(p2-p1);
}

var p1 = obj1->GetPosition(); // p1 = [100.0,0.0,0.0]
var p2 = obj2->GetPosition(); // p2 = [-200.0,400.0,0.0]

println("distance(p1,p2) = ",distance(p1,p2));

##### Return
float

vlen() returns the vector length of v, that is the distance from origo to a point at the coordinates v. Mathematically this is calculated with sqrt(v.x*v.x + v.y*v.y + v.z*v.z).

vector v

A vector.

#### vector vnorm(vector v)

Normalizes a vector to unit length.

Example:

// Outputs "vnorm(v) = [0.0000,1.0000,0.0000]".

var v = vector(0.0,300.0,0.0);
var a = vnorm(v);

println("vnorm(v) = ",a);

// If one has a vector and want to make it a certain number
// of units in length, one can just normalize it and multiply
// by the wanted length.
//
// Outputs "v       = [20.7345,-478.1134,144.8367]
//          vlen(v) = 500.0000".

var v = vector(3.4,-78.4,23.75);
var length = 500.0;

v = vnorm(v) * length;

println("v       = ",v);
println("vlen(v) = ",vlen(v));

##### Return
vector

vnorm() returns a normalized copy of v, that is a vector pointing in the same direction as v but exactly one unit long. Mathematically this is calculated with v/vlen(v).

vector v

A vector.

#### float Modulo(float a, float b)

Returns a modulo b.

#### float Step(float a, float x)

Returns 1.0 if x is greater than or equal to a, else 0.0.

Pulse if x [float] is between or equal to a,b returns 1.0 else 0.0 Clamp if x [float] is less than a returns a else if it is greater than b returns b else returns x BoxStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b SmoothStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b and smoothed out (ease in ease out curve).

#### float Pulse(float a, float b, float x)

Returns 1.0 if x is between or equal to either of a and b, else 0.0.

Pulse if x [float] is between or equal to a,b returns 1.0 else 0.0 Clamp if x [float] is less than a returns a else if it is greater than b returns b else returns x BoxStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b SmoothStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b and smoothed out (ease in ease out curve).

#### float Clamp(float a, float b, float x)

Returns a if x is less than a and b if x is greater than b, else returns x.

Pulse if x [float] is between or equal to a,b returns 1.0 else 0.0 Clamp if x [float] is less than a returns a else if it is greater than b returns b else returns x BoxStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b SmoothStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b and smoothed out (ease in ease out curve).

#### float BoxStep(float a, float b, float x)

Returns 0.0 if x is less than a and 1.0 if x is greater than b, else returns x mapped on the range [a,b] (a number between 0.0 and 1.0).

Pulse if x [float] is between or equal to a,b returns 1.0 else 0.0 Clamp if x [float] is less than a returns a else if it is greater than b returns b else returns x BoxStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b SmoothStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b and smoothed out (ease in ease out curve).

#### float SmoothStep(float a, float b, float x)

Returns 0.0 if x is less than a and 1.0 if x is greater than b, else returns x mapped on the range [a,b] (a number between 0.0 and 1.0). The mapping is smoothed using an ease-in/ease-out curve.

Pulse if x [float] is between or equal to a,b returns 1.0 else 0.0 Clamp if x [float] is less than a returns a else if it is greater than b returns b else returns x BoxStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b SmoothStep if x [float] is less than a returns 0.0 else if it is greater than b returns 1.0 else returns x mapped on the range a,b and smoothed out (ease in ease out curve).

#### float GammaCorrect(float gamma, float x)

Returns the gamma corrected value of x, calculated with the formula x^(1/gamma).

#### float Bias(float bias, float x)

Returns the bias as the defined in the book "Texturing and Modeling" by Ebert.

The internal code is:

Bias(b, x)
{
return Pow(x, -Ln(b) / 0.693147180559945);
}

#### float Gain(float g, float x)

Returns the gain as the defined in the book "Texturing and Modeling" by Ebert.

The internal code is:

Gain(g, x)
{
if (x<0.5)
return Bias(1.0 - g, 2.0 * x) * 0.5;
else
return 1.0 - Bias(1.0 - g, 2.0 - 2.0 * x) * 0.5;
}

#### anytype Mix(anytype a, anytype b, anytype x)

Returns a mixed value of a and b using the parameter x, as calculated by a+(b-a)*x.