Math Script API

Core math API used by the script system. It can be accessed using the math interface and consists of a number of constants, functions, and built-in vector and matrix types.

Basic Types

Basic math types available to the script system include:

• int - 32-bit signed integer
• uint - 32-bit unsigned integer
• float - 32-bit floating point value

Vector and Matrix Types

• float2, float3, float4 - vector types of the indicated size. A float3, for example, consists of 3 floats in vector format. Components can be accessed as x, y, z, w or by index (see the examples below). GLSL style swizzling is supported, as well as array syntax. Swizzling can be used to copy out smaller vectors as well.
• float2x2, float3x3, float4x4 - matrix types of the indicated size (2x2, 3x3, or 4x4 matrix). Rows can be accessed using the array syntax and are of the associated vector type (float2x2 = 2 x float2).

Vector Operations

Vector types (float, float2, float3, float4) can be referenced using array and component syntax. Swizzling is supported.

Example Swizzles:

float2 v(1, 2);
system.print("{}", v);    // (1, 2)
system.print("{}", v.yx); // (2, 1)
system.print("{}", v.xx); // (1, 1)
float a = v.y;
system.print("{}", a); // 2

float3 v3(1, 2, 3);
float2 v2 = v3.xz;

Example of Array Access:

float2 v2(2,3);
system.print("{}", v2[0]);  // 2
system.print("{}", v2[1]);  // 3

float4 v4(1, 2, 3, 4);
system.print("{}", v4[1]); // 2
system.print("{}", v4[3]); // 4

Example of mathematical operations, basic operations are supported:

float2 a(1,2);
float2 b(2,3);
float4 a4(1,2,3,4);
float2 c = a + b;   // c = (1,2) + (2,3) = (3,5)
float2 d = a * b;   // d = (1,2) * (2,3) = (2,6)
float2 e = a * 2.0; // e = (1,2) * 2 = (2,4)
float3 f = a4.xyz * a.y; // f = (1,2,3) * (2) = (2,4,6)

Matrix Operations

Matrices are stored as a series of vectors, which can be accessed using array syntax. Matrix types support matrix/matrix and matrix/vector multiplication, as well as matrix/float scaling. The following types are supported: float2x2, float3x3, float4x4.

float2x2 m2x2(1, 0, 0, 1); // 2x2 matrix: [1 0]
                                          [0 1]
float3x3 m0(float3(1, 0, 0), float3(0, 1, 0), float3(0, 0, 1)); // 3x3 identity.
float3x3 m1;

float3x3 m2 = m0 * m1; // concatenate matrices m0 and m1.
float3 pos;
float3 r = m2 * pos;  // multiply 'pos' by matrix m2.

float3 v = m0[1]; // v = (0, 1, 0)

float2x2 rot2x2 = math.rotationMatrix2x2(angle);
float3x3 rot3x3 = math.rotationMatrix3x3(pitch, yaw, roll);
// Transform a 2D point.
float2 point;
float2 pivot; // center point of rotation.
float2 rotatedPoint = rot2x2 * (point - pivot) + pivot;

Math Examples

float2 s(2, 3);
float2 t(4, 5);
float2 q(3, 4);
float3 r(4, 5, 6);
float3 color0(1.0, 0.5, 0.5);
float3 color1(0.25, 0.25, 1.0);
float dist = math.distance(s, q);  // distance between (2,3) and (3,4).
float blend = math.smoothstep(0, 5, dist);  // produce a blend factor between [0,1]
float2 value = math.mix(s, t, blend);
float2 sum = r.xy + r.yz;
float3 unit = math.normalize(r);
float3 color = math.mix(color0, color1, blend);

Math Constants

Constant	Description
float pi	value of π
float twoPi	value of 2*π
float e	value of the natural number e

Math Functions

countBits(x)

Counts the number of bits in an integer.

int countBits(uint)
int countBits(int)

findLSB(x)

Return the Least Significant Bit of the integer x.

int findLSB(uint)
int findLSB(int)

findMSB(x)

Return the Most Significant Bit of the integer x.

int findMSB(uint)
int findMSB(int)

abs(x)

Returns the absolute value of the input, operates per-component.

int abs(int)
float abs(float)
float2 abs(float2)
float3 abs(float3)
float4 abs(float4)

all(x)

Returns true if all components are non-zero.

bool all(float)
bool all(float2)
bool all(float3)
bool all(float4)

any(x)

Returns true if any component is non-zero.

bool any(float)
bool any(float2)
bool any(float3)
bool any(float4)

acos(x)

Arccosine of angles in radians, operates per-component.

float acos(float)
float2 acos(float2)
float3 acos(float3)
float4 acos(float4)

asin(x)

Arcsine of angles in radians, operates per-component.

float asin(float)
float2 asin(float2)
float3 asin(float3)
float4 asin(float4)

atan(x)

Arctangent of angles in radians, operates per-component.

float atan(float)
float2 atan(float2)
float3 atan(float3)
float4 atan(float4)

atan2(y, x)

Returns the angle θ between the positive x-axis and the ray from the origin to the point (x, y), confined to (−π, π].

float atan2(float, float)
float2 atan2(float2, float2)
float3 atan2(float3, float3)
float4 atan2(float4, float4)

cos(x)

Computes the cosine of the input angle in radians.

float cos(float)
float2 cos(float2)
float3 cos(float3)
float4 cos(float4)

sin(x)

Computes the sine of the input angle in radians.

float sin(float)
float2 sin(float2)
float3 sin(float3)
float4 sin(float4)

tan(x)

Computes the tangent of the input angle in radians.

float tan(float)
float2 tan(float2)
float3 tan(float3)
float4 tan(float4)

sincos(x)

Compute the sine of the input angle and store it in x, and cosine of the angle in y.

float2 sincos(float)

degrees(x)

Converts from radians to degrees, operates per-component.

float degrees(float)
float2 degrees(float2)
float3 degrees(float3)
float4 degrees(float4)

radians(x)

Converts from degrees to radians, operates per-component.

float radians(float)
float2 radians(float2)
float3 radians(float3)
float4 radians(float4)

exp(x)

Computes the natural number e to the power of x, and operates per component.

float exp(float)
float2 exp(float2)
float3 exp(float3)
float4 exp(float4)

exp2(x)

Computes 2 to the power of x, and operates per component.

float exp2(float)
float2 exp2(float2)
float3 exp2(float3)
float4 exp2(float4)

log(x)

Computes the natural (base e) logarithm of the input.

float log(float)
float2 log(float2)
float3 log(float3)
float4 log(float4)

log2(x)

Computes the base 2 logarithm of the input.

float log2(float)
float2 log2(float2)
float3 log2(float3)
float4 log2(float4)

log10(x)

Computes the base 10 logarithm of the input.

float log10(float)
float2 log10(float2)
float3 log10(float3)
float4 log10(float4)

pow(x, y)

Compute the power of x to the power of y (x^y).

float pow(float, float)
float2 pow(float2, float)
float2 pow(float2, float2)
float3 pow(float3, float)
float3 pow(float3, float3)
float4 pow(float4, float)
float4 pow(float4, float4)

floor(x)

Rounds the input down to the nearest integer, operates per-component.

float floor(float)
float2 floor(float2)
float3 floor(float3)
float4 floor(float4)

ceil(x)

Rounds the input up to the nearest integer, operates per-component.

float ceil(float)
float2 ceil(float2)
float3 ceil(float3)
float4 ceil(float4)

fract(x)

Extract the signed fractional part of the input, operates per-component.

float fract(float)
float2 fract(float2)
float3 fract(float3)
float4 fract(float4)

max(x, y)

Returns the maximum of two values, operates per-component.

float max(float, float)
float2 max(float2, float)
float2 max(float2, float2)
float3 max(float3, float)
float3 max(float3, float3)
float4 max(float4, float)
float4 max(float4, float4)

min(x, y)

Returns the minimum of two values, operates per-component.

float min(float, float)
float2 min(float2, float)
float2 min(float2, float2)
float3 min(float3, float)
float3 min(float3, float3)
float4 min(float4, float)
float4 min(float4, float4)

clamp(x, a, b)

Returns x clamped to the range of [a,b], operates per-component.

float clamp(float, float, float)
float2 clamp(float2, float, float)
float2 clamp(float2, float2, float2)
float3 clamp(float3, float, float)
float3 clamp(float3, float3, float3)
float4 clamp(float4, float, float)
float4 clamp(float4, float4, float4)

saturate(x)

Clamps the x to the range of [0,1], operates per-component.

float saturate(float)
float2 saturate(float2)
float3 saturate(float3)
float4 saturate(float4)

mix(x, y, a)

Uses a to linearly interpolate between x and y, if a == 0 the result is x, if a == 1 the result is y, in-between is a mix of x and y. Operates per-component.

float mix(float, float, float)
float2 mix(float2, float2, float)
float2 mix(float2, float2, float2)
float3 mix(float3, float3, float)
float3 mix(float3, float3, float3)
float4 mix(float4, float4, float)
float4 mix(float4, float4, float4)

step(edge, x)

A step function comparing x to edge, if x < edge return 0 otherwise return 1. Operates per component.

int step(int, int)
float step(float, float)
float2 step(float, float2)
float2 step(float2, float2)
float3 step(float, float3)
float3 step(float3, float3)
float4 step(float, float4)
float4 step(float4, float4)

smoothstep(edge0, edge1, x)

Performs smooth Hermite interpolation between 0 and 1 when edge0 < x < edge1, operates per-component.

float smoothstep(float, float, float)
float2 smoothstep(float, float, float2)
float2 smoothstep(float2, float2, float)
float2 smoothstep(float2, float2, float2)
float3 smoothstep(float, float, float3)
float3 smoothstep(float3, float3, float)
float3 smoothstep(float3, float3, float3)
float4 smoothstep(float, float, float4)
float4 smoothstep(float4, float4, float)
float4 smoothstep(float4, float4, float4)

sign(x)

Returns the sign of x, -1 if x < 0, 1 if x > 0, 0 if x == 0, operates per-component.

int sign(int)
float sign(float)
float2 sign(float2)
float3 sign(float3)
float4 sign(float4)

sqrt(x)

Returns the square root of the input, operates per-component.

float sqrt(float)
float2 sqrt(float2)
float3 sqrt(float3)
float4 sqrt(float4)

mod(x, y)

The floating-point remainder of the division operation x / y, operates per-component.

float mod(float, float)
float2 mod(float2, float)
float2 mod(float2, float2)
float3 mod(float3, float)
float3 mod(float3, float3)
float4 mod(float4, float)
float4 mod(float4, float4)

distance(x, y)

Computes the (unsigned) distance between points x and y.

float distance(float, float)
float distance(float2, float2)
float distance(float3, float3)
float distance(float4, float4)

dot(x, y)

Computes the dot product of x and y (also known as the inner product).

float dot(float, float)
float dot(float2, float2)
float dot(float3, float3)
float dot(float4, float4)

length(x)

Returns the length of the input vector.

float length(float)
float length(float2)
float length(float3)
float length(float4)

normalize(x)

Returns the normalized (unit) vector of x.

float normalize(float)
float2 normalize(float2)
float3 normalize(float3)
float4 normalize(float4)

perp(x, y)

Computes the perp product of two 2D vectors, x and y. This is similar to the cross product in 2D, where perp(x, y) = |x| * |y| * sin(angle).

float perp(float2, float2)

cross(x, y)

Computes the cross product of two 3D vectors, x and y.

float3 cross(float3, float3)

transpose(x)

Return the transpose of matrix x.

float2x2 transpose(float2x2)
float3x3 transpose(float3x3)
float4x4 transpose(float4x4)

rotationMatrix2x2(angle)

Builds a 2x2 rotation matrix based on angle in radians.

float2x2 rotationMatrix2x2(float)

rotationMatrix3x3(pitch, yaw, roll)

Builds a 3x3 rotation matrix based on yaw, pitch, roll angles in radians. Note that roll = 0.0 by default.

float3x3 rotationMatrix3x3(float, float, float = 0.0)