Math Common Functions

WarningThe scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScript (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.

This class represents a collection of common math functions.

Methods:

Name	Description View: Sort by:
abs	Returns the absolute value of the argument.
bezier	Calculates the value of a cubic Bezier function for t = time.
ceil	Ceiling function that returns the smallest integer value that is not less than arg.
clamp	Clamps a value within the specified min and max limits.
compare	Compares two variables of the same type according to the specified degree of precision.
conjugate	Returns the conjugate of a given quaternion.
cross	Cross product of two vectors (either vec3 or dvec3).
dot	Dot product of vectors: It is possible to obtain a dot product of vec3 and vec4, as well as a dot product of dvec3 and dvec4.
dot3	Dot product only of three components of vectors.
floor	Rounds an argument down to the nearest integer.
frac	Returns the fractional part of the argument.
getAngle	Returns the angle (in degrees) between the given first and second vectors.
gradient4	Returns a gradient value for the specified argument using four key components.
inverseLerp	Returns the value calculated according to the following formula: (v - v0) / (v1 - v0) clamped within 0.
length	Calculates the length of a given vector.
length2	Calculates the squared length of a given vector.
lerp	Linear interpolation between two values according to the following formula: v0 + (v1 - v0) * k For quaternions, the function uses a spherical interpolation algorithm (slerp).
max	Finds the highest value.
min	Finds the lowest value.
normalize3	Depending on the argument type, function performs the following: Normalizes the X, Y, Z components of the given vector.
normalize	Normalizes a vector, makes its magnitude equal to 1.
npot	Rounds up to the nearest power of two value.
rcp	Returns the reciprocal of the specified argument.
round	Rounds an argument to the nearest integer value.
saturate	Clamps values within the range of 0.
sign	Returns the sign of the argument.
smoothstep	Returns a smooth Hermite interpolation between 0 and 1, if x is in the range [0, 1].
smootherstep	Returns a smooth interpolation between 0 and 1 using a fifth-order polynomial function, if x is in the range [0, 1].
udiv	Performs integer division with rounding up.

Variables:

Name	Description
AXIS_X = = 0	Positive X axis.
AXIS_Y = = 1	Positive Y axis.
AXIS_Z = = 2	Positive Z axis.
AXIS_NX = = 3	Negative X axis.
AXIS_NY = = 4	Negative Y axis.
AXIS_NZ = = 5	Negative Z axis.
vec4_zero	Vector filled with zeros (0).
vec4_one	Vector filled with ones (1).
vec4_eps	Vector filled with epsilon constant (1e-6f).
vec4_inf	Vector filled with the infinity constant (1e+9f).
vec4_white	White color vector (1, 1, 1, 1).
vec4_black	Black color vector (0, 0, 0, 0).
vec4_red	Red color vector (1, 0, 0, 1).
vec4_green	Green color vector (0, 1, 0, 1).
vec4_blue	Blue color vector (0, 0, 1, 1).

Math Class

Members

Variable abs ( Variable arg ) #

Returns the absolute value of the argument.

Arguments

Variable arg - Argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4

Return value

Absolute value of arg.

Variable bezier ( vec4 times, Variable values, float time ) #

Calculates the value of a cubic Bezier function for t = time.

A cubic Bezier curve is represented by 4 points. P_o is the start point, P₁ and P₂ are control points 1 and 2 and P₃ is the end point. The start and end point denote the beginning and end points of the path and the control points determine how the path moves from the start to the finish. As can be seen from the image, the only variable changing is t which determines how far the path has progressed from P0 to P3. Cubic Bezier curves are used as timing functions particularly for keyframe interpolation.

Arguments

vec4 times - Coordinates of the four points of the curve along the horizontal T (times) axis in the range [0.0f, 1.0f].
Variable values - Coordinates of the four points of the curve along the vertical V (values) axis in the range [0.0f, 1.0f]. They can either be of vec4 or dvec4 types.
float time - Time in the range [0, 1], for which the value of the Bezier function is to be calculated.

Return value

Value of the Bezier function.

Variable ceil ( Variable arg ) #

Ceiling function that returns the smallest integer value that is not less than arg. For vectors ceiling values are obtained per component.

Arguments

Variable arg - Argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4

Return value

Smallest integer value not less than arg. The type of return value depends on the argument type:

float for int, long, float arguments
double for double arguments
vec4 for vec4 arguments
dvec3 for dvec3 arguments
dvec4 for dvec4 arguments

Examples

Source code

float a = ceil(2.3) // a = 3.0

Variable clamp ( Variable v, Variable min, Variable max ) #

Clamps a value within the specified min and max limits.

Arguments

Variable v - Argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4
- ivec3
- ivec4
Variable min - Minimum limit. Type must be the same as the type of v.
If the first argument is int, it can also be string:
- If a string is empty, it will equal to int(0).
- If a string is nonempty, it will equal to int(1).
Variable max - Maximum limit. Type must be the same as the type of v.
If the first argument is int, it can also be string:
- If a string is empty, it will equal to int(0).
- If a string is nonempty, it will equal to int(1).

Return value

Clamped value within min and max limits:

max, if v > max
min, if v < min
otherwise, v

int compare ( Variable v0, Variable v1, Variable epsilon = 1e-6 ) #

Compares two variables of the same type according to the specified degree of precision. The following formula is used:

Source code (C++)

fabs(v0 - v1) < (fabs(v0) + fabs(v1) + 1.0) * eps

Arguments

Variable v0 - Variable of one of the following types:
- float
- double
- vec3
- vec4
- dvec3
- dvec4
- mat4
- dmat4
- quat
Variable v1 - Variable of the same type as v0.
Variable epsilon - Epsilon. Can be of the following types:
- int
- long
- float
- double

Return value

1 if v0 is equal to v1; otherwise, 0.

quat conjugate ( quat q ) #

Returns the conjugate of a given quaternion.

Arguments

quat q - Quaternion.

Return value

Conjugate of a given quaternion.

Variable cross ( Variable v0, Variable v1 ) #

Cross product of two vectors (either vec3 or dvec3).

Arguments

Variable v0 - First vector. Can be of the following types:
- vec3
- dvec3
- ivec3
Variable v1 - Second vector (of the same type as v0 vector).

Return value

Cross product of v0 and v1 (vec3, dvec3 or ivec3).

Variable dot ( Variable v0, Variable v1 ) #

Dot product of vectors:

It is possible to obtain a dot product of vec3 and vec4, as well as a dot product of dvec3 and dvec4. In this case, w component of the four-component vector is added to the dot product of first three components of vectors.
A dot product of ivec3, ivec4 and quat requires the second argument to be exactly of the same type.

Arguments

Variable v0 - First argument. Can be of the following types:
- vec3
- vec4
- dvec3
- dvec4
- ivec3
- ivec4
- quat
Variable v1 - Second argumet. Can be one of the same of similar types as v0.

Return value

Dot product of v0 and v1:

float if case of vec3 or vec4
double if case of dvec3 or dvec4
int if case of ivec3 or ivec4

Examples

Source code (UnigineScript)

printf("%f\n",dot(vec3(1,2,3),vec3(1,2,3)));
printf("%f\n",dot(vec3(1,2,3),vec4(1,2,3,4)));
/*
result is:
14.000000
18.000000
*/

Variable dot3 ( Variable v0, Variable v1 ) #

Dot product only of three components of vectors. In case an argument is a four-component vector, its w component is ignored.
It is possible to obtain a dot product of vec3 and vec4, as well as a dot product of dvec3 and dvec4. But a dot product of vec3 and dvec3, for example, cannot be computed.

Arguments

Variable v0 - First vector. Can be of the following types:
- vec3
- vec4
- dvec3
- dvec4
Variable v1 - Second vector. Can be one of similar types as v0.

Return value

Dot product of v0 and v1:

float if case of vec3 or vec4
double if case of dvec3 or dvec4

Examples

Source code (UnigineScript)

printf("%f\n",dot3(vec3(1,2,3),vec3(1,2,3)));
printf("%f\n",dot3(vec3(1,2,3),vec4(1,2,3,4)));
/*
result is:
14.000000
14.000000
*/

Variable floor ( Variable arg ) #

Rounds an argument down to the nearest integer. For vectors values are obtained per component.

Arguments

Variable arg - Argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4

Return value

Largest integer value not greater than arg. The type of return value depends on the argument type:

float for int, long, float arguments
double for double arguments
vec4
dvec3
dvec4

Examples

Source code

float a = floor(2.3) // a = 2.0

Variable frac ( Variable arg ) #

Returns the fractional part of the argument. For vectors values are obtained per component.

Source code

float a = frac(3.141593); // a = 0.141593

Arguments

Variable arg - Argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4

Return value

Fractional part of arg (arg - floor (arg)). The type of return value depends on the argument type:

float for int, long, float arguments
double for double arguments
vec4 for vec4 arguments
dvec3 for dvec3 arguments
dvec4 for dvec4 arguments

getAngle ( Variable v0, Variable v1 ) #

Returns the angle (in degrees) between the given first and second vectors. The angle returned is the unsigned acute angle between the two vectors. This means the smaller of the two possible angles is used.

Arguments

Variable v0 - First vector (from which the angular difference is measured). Can be of the following types:
- vec3
- quat
Variable v1 - Second vector (to which the angular difference is measured). Can be of the following types:
- vec3
- quat

Return value

Angle between the given vectors, in degrees within the range [0.0; 180.0].

float getAngle ( vec3 v0, vec3 v1, vec3 up ) #

Returns the signed angle (in degrees) between the given first and second vectors relative to the specified "up" vector.

Arguments

vec3 v0 - First vector (from which the angular difference is measured).
vec3 v1 - Second vector (to which the angular difference is measured).
vec3 up - Up vector, around which the other two vectors are rotated.

Return value

Angle between the given vectors, in degrees within the range [-180.0; 180.0].

float gradient4 ( float x, vec4 gradient ) #

Returns a gradient value for the specified argument using four key components. The gradient value is determined as follows:

Source code

smoothstep(gradient.x, gradient.y, x) - smoothstep(gradient.z, gradient.w, x);

See the smoothstep() method.

Arguments

float x - Argument.
vec4 gradient - Vector with four key components.

Return value

Gradient value.

float inverseLerp ( float v0, float v1, float v ) #

Returns the value calculated according to the following formula: (v - v0) / (v1 - v0) clamped within 0.0f and 1.0f.

Arguments

float v0 - The value specifying the beginning of the interval.
float v1 - The value specifying the ending of the interval.
float v - The value within the specified interval.

Return value

Coefficient of the value within a specified interval.

Variable length ( Variable vector ) #

Calculates the length of a given vector.

Arguments

Variable vector - Vector. Can be of the following types:
- vec3
- vec4
- dvec3
- dvec4

Return value

Vector length:

float for vec3 and vec4 arguments
double for dvec3 and dvec4 arguments

Variable length2 ( Variable vector ) #

Calculates the squared length of a given vector. This method is much faster than length() - the calculation is basically the same only without the slow Sqrt call. If you are using lengths simply to compare distances, then it is faster to compare squared lengths against the squares of distances as the comparison gives the same result.

Arguments

Variable vector - Vector. Can be of the following types:
- vec3
- vec4
- dvec3
- dvec4
- ivec3
- ivec4

Return value

Squared length of the vector (X ² + Y ² + Z ²):

float for vec3 and vec4 arguments
double for dvec3 and dvec4 arguments
int for ivec3 and ivec4 arguments

Variable lerp ( Variable v0, Variable v1, Variable k ) #

Linear interpolation between two values according to the following formula:
v0 + (v1 - v0) * k

NoticeFor quaternions, the function uses a spherical interpolation algorithm (slerp).

Arguments

Variable v0 - Start value. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4
- ivec3
- ivec4
- mat4
- dmat4
- quat
Variable v1 - End value. Must be the same type as v0.
Variable k - Value from 0 to 1 indicating the weight of v1. Can be of the following types:
- int
- long
- float
- double
- string if arguments are ivec3 or ivec4:
  - If a string is empty, it will equal to int(0).
  - If a string is nonempty, it will equal to int(1).

Return value

Interpolated value.

Variable max ( Variable arg1, Variable arg2 ) #

Finds the highest value.

Arguments

Variable arg1 - First argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4
- ivec3
- ivec4
Variable arg2 - Second argument. Type must be the same as the type of arg1.
If arg1 is int, the second argument can also be string:
- If a string is empty, it will equal to int(0).
- If a string is nonempty, it will equal to int(1).

Return value

Numerically highest of the parameter values.

Variable min ( Variable arg1, Variable arg2 ) #

Finds the lowest value.

Arguments

Variable arg1 - First argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4
- ivec3
- ivec4
Variable arg2 - Second argument. Type must be the same as the type of arg1.
If arg1 is int, the second argument can be string:
- If a string is empty, it will equal to int(0).
- If a string is nonempty, it will equal to int(1).

Return value

Numerically lowest of the parameter values.

Variable normalize3 ( Variable v ) #

Depending on the argument type, function performs the following:

Normalizes the X, Y, Z components of the given vector.
Recalculates the w component of the given quaternion.

Arguments

Variable v - Argument of one of the following types:
- vec4 v - A vector of 4 float components.
- dvec4 v - A vector of 4 double components.
- quat v - A quaternion.

Return value

Normalized vector or quaternion.

Examples

You can use the normalize3() function when you need to restore the w component of the quaternion, for example:

Source code (UnigineScript)

vec3 t = vec3(1.0f,0.0f,0.0f); // the tangent basis: tangent vector
vec3 b = vec3(0.0f,1.0f,0.0f); // binormal vector
vec3 n = vec3(0.0f,0.0f,1.0f); // normal vector
vec4 tangent = orthoTangent(t,b,n); // this is the mesh compressed tangent vector

quat compact_tangent_quat = quat(tangent); // convert vec4 to quat; currently the last component of the tangent vector contains the sign of the binormal
quat normalized_quat = normalize3(compact_tangent_quat); // normalize quat; now you have the correct quaternion

Variable normalize ( Variable vector ) #

Normalizes a vector, makes its magnitude equal to 1. When normalized, a vector keeps the same direction but its length is equal to 1.

Arguments

Variable vector - A vector. Can be of the following types:
- vec3
- vec4
- dvec3
- dvec4
- quat

Return value

Normalized vector.

int npot ( int arg ) #

Rounds up to the nearest power of two value.

Arguments

int arg - Argument.

Return value

The nearest upper power of 2 number.

Variable rcp ( Variable arg ) #

Returns the reciprocal of the specified argument. For vectors values are obtained per component.

Arguments

Variable arg - Argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4

Return value

1.0 / arg
The type of return value depends on the argument type:

float for int, long, float arguments
double for double arguments
vec4
dvec3
dvec4

Variable round ( Variable arg ) #

Rounds an argument to the nearest integer value. For vectors values are obtained per component.

NoticeIn halfway cases, when an argument has a fractional part of exactly 0.5, the function rounds away from zero to the integer with larger magnitude.
					3.5	 -> 4
- 3.5	 ->	- 4

				

Arguments

Variable arg - Argument. Can be of the following types:
- float
- double
- vec3
- vec4
- dvec3
- dvec4

Return value

Nearest integer value. The type of return value depends on the argument type:

float for float arguments
double for double arguments
vec3
vec4
dvec3
dvec4

Examples

Source code

float a = round(2.3) 					// a = 2.0
float b = round(5.5) 					// b = 6.0
float c = round(-5.5) 					// c = -6.0
Vec3 d = round(Vec3(1.2, 1.8, -1.5)) 	// d = (1.0, 2.0, -2.0)

Variable saturate ( Variable v ) #

Clamps values within the range of 0.0 to 1.0.

Arguments

Variable v - Argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4
- ivec3
- ivec4

Return value

Clamped argument within 0.0 and 1.0. 1.0, if v > 1.0 ; 0.0 if v < 0.0 ; otherwise, v.

Variable sign ( Variable arg ) #

Returns the sign of the argument. For vectors values are obtained per component.

Arguments

Variable arg - Argument. Can be of the following types:
- int
- long
- float
- double
- vec3
- vec4
- dvec3
- dvec4

Return value

Sign of arg. 1.0 if arg >= 0.0 ; -1.0 if arg < 0.0.
The type of return value depends on the argument type:

float for int, long, float arguments
double for double arguments
vec4
dvec3
dvec4

Variable smoothstep ( Variable x ) #

Returns a smooth Hermite interpolation between 0 and 1, if x is in the range [0, 1].

It is convenient for creating a sequence of transitions using smoothstep to interpolate each segment as an alternative to using more sophisticated or expensive interpolation techniques.

Arguments

Variable x - Value to be interpolated. Can be of the following types:
- float
- double

Return value

One of the following values:

0 if x is less than 0;
1 if x is greater than 1;
interpolated value between 0 and 1 if x is in the range [0, 1].

The type of return value depends on the argument type:

float for float arguments
double for double arguments

Variable smoothstep ( Variable edge0, Variable edge1, Variable x ) #

Returns a smooth Hermite interpolation between 0 and 1, if x is in the range [edge0, edge1].

It is convenient for creating a sequence of transitions using smoothstep to interpolate each segment as an alternative to using more sophisticated or expensive interpolation techniques.

Arguments

Variable edge0 - Left edge value. Can be of the following types:
- float
- double
Variable edge1 - Right edge value. Can be of the following types:
- float
- double
Variable x - Value to be interpolated. Can be of the following types:
- float
- double

Return value

One of the following values:

0 if x is less than edge0;
1 if x is greater than edge1;
interpolated value between 0 and 1 if x is in the range [edge0, edge1].

The type of return value depends on the argument type:

float for float arguments
double for double arguments

Variable smootherstep ( Variable x ) #

Returns a smooth interpolation between 0 and 1 using a fifth-order polynomial function, if x is in the range [0, 1].

It is convenient for creating a sequence of transitions using smoothstep to interpolate each segment as an alternative to using more sophisticated or expensive interpolation techniques.

Arguments

Variable x - Value to be interpolated. Can be of the following types:
- float
- double

Return value

One of the following values:

0 if x is less than 0;
1 if x is greater than 1;
interpolated value between 0 and 1 if x is in the range [0, 1].

The type of return value depends on the argument type:

float for float arguments
double for double arguments

Variable smootherstep ( Variable edge0, Variable edge1, Variable x ) #

Returns a smooth interpolation between 0 and 1 using a fifth-order polynomial function, if x is in the range [edge0, edge1].

It is convenient for creating a sequence of transitions using smoothstep to interpolate each segment as an alternative to using more sophisticated or expensive interpolation techniques.

Arguments

Variable edge0 - Left edge value. Can be of the following types:
- float
- double
Variable edge1 - Right edge value. Can be of the following types:
- float
- double
Variable x - Value to be interpolated. Can be of the following types:
- float
- double

Return value

One of the following values:

0 if x is less than edge0;
1 if x is greater than edge1;
interpolated value between 0 and 1 if x is in the range [edge0, edge1].

The type of return value depends on the argument type:

float for float arguments
double for double arguments

int udiv ( int x, int y ) #

Performs integer division with rounding up.

Arguments

int x - First argument.
int y - Second argument.

Return value

The rounded up quotient of two arguments that satisfies the following condition: y * z >= x.

Last update: 2022-03-10

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)