Math functions

ACSUtils provides a wide array of commonly used math functions so you don't have to implement them yourself.

What is this "num" type?

num means that the function accepts both int and fixed numbers as arguments. But all num arguments must be of the same type. And num return values are of the same type as the arguments. For example:

min(1.0, 5.0) returns 1.0

min(1, 5) returns 1

min(1.0, 5) – never write this way

Function list

Generic functions

num min(num a, num b) – returns the lesser of A and B.

num max(num a, num b) – returns the greater of A and B.

num clamp(num x, num a, num b) – limits X to the interval [A, B] and returns the result.

num middle(num a, num b, num c) – out of three numbers, returns the one that is between the other two.

num abs(num x) – returns the absolute value of X. Shorthand for x > 0 ? x : -x.

num sgn(num x) – returns 1 if X is positive, -1 if negative. If X is 0, returns 0.

num cmp(num a, num b) – returns 1 if A is greater than B, -1 if lesser, 0 if they are equal.

Other functions

fixed IntDiv(int x, int y) – divides two integers and returns fixed-point result. Supports any pair of integers whose ratio is less than 32767.

fixed AngleDiff(fixed a, fixed b) – returns the shortest signed rotation angle needed to go from angle A to angle B. Result is always in [-0.5, 0.5]. Both A and B may be outside [0.0, 1.0].

num gcf(num a, num b) – returns the greatest common factor of two numbers.

fixed fract(fixed x) – returns the fractional part of X. For example, fract(12.345) returns 0.345. fract(-1234.56789) == 0.56789.

Powers

num ipow(num x, int power) – returns x^power. Supports int and fixed X, but only integer powers. Uses a multiplication loop.

fixed fpow(fixed x, fixed power) – returns x^power. Supports only fixed-point powers and fixed-point X. Uses multiplication loops.

Trigonometry

sin is already in ZDoom

cos is already in ZDoom

fixed tan(fixed angle) – shorthand for FixedDiv(sin(x), cos(x))

fixed cot(fixed angle) – shorthand for FixedDiv(cos(x), sin(x))

fixed sec(fixed angle) – shorthand for FixedDiv(1.0, sin(angle))

fixed cosec(fixed angle) – shorthand for FixedDiv(1.0, cos(angle))

fixed asin(fixed x)

fixed acos(fixed x)

fixed atan(fixed x) – shorthand for VectorAngle(1.0, x)

fixed acot(fixed x) – shorthand for 0.25 - atan(x)

fixed asec(fixed x) – shorthand for acos(FixedDiv(1.0, x))

fixed acosec(fixed x) – shorthand for asin(FixedDiv(1.0, x))

Vector math

Since some functions need to return a vector or a pair of angles, they use the ACSUtils multiple return values convention.

ZDoom GetActorPitch returns actor pitch with the wrong sign (multiplied by -1). Make sure to fix the sign before using actor pitch in the below vector functions.

Functions returning one value:

fixed VectorLength3D(fixed x, fixed y, fixed z) – a 3D version of VectorLength. Shorthand for VectorLength(z, VectorLength(x, y)).

fixed SqVectorLength(fixed x, fixed y) – squared length of 2D vector.

fixed SqVectorLength3D(fixed x, fixed y, fixed z) – squared length of 3D vector.

fixed dot2(fixed x1, fixed y1, fixed x2, fixed y2) – dot product of two 2D vectors.

fixed dot3(fixed x1, fixed y1, fixed z1, fixed x2, fixed y2, fixed z2) – dot product of two 3D vectors.

Functions returning two values:

fixed, fixed normalize2d(fixed x, fixed y) – returns normalized 2D vector (same direction, but length 1.0)

fixed, fixed VectorToAngles(fixed x, fixed y, fixed z) – converts vector to a pair of angles (angle and pitch)

fixed, fixed RotateVector(fixed x, fixed y, fixed angle) – returns vector rotated by angle

fixed, fixed RotateVectorSC(fixed x, fixed y, fixed sin, fixed cos) – returns vector rotated by sin and cos of some angle (aka rotation vector). This is useful if you already have the sine and cosine of the rotation angle.

fixed, fixed RotatePoint(fixed x, fixed y, fixed originX, fixed originY, fixed angle) – returns 2D point rotated by angle around the origin.

Functions returning three values:

fixed, fixed, fixed normalize3d(fixed x, fixed y, fixed z) – returns normalized 3D vector.

fixed, fixed, fixed AnglesToVector(fixed angle, fixed pitch) – converts a pair of angles to a vector of length 1.

Other useful functions

mod

num mod(num x, num period) – just like x % period, but performs “true” modulo division, without negative results or mirrorings. It's as if you began at 0 in space [0, period) with wraparound, and moved X steps to the right.

Example of practical use of mod that wouldn't work with %:

int NUM_MENU_ITEMS = 10;
int selected_item = 0;
if (KeyPressed(BT_FORWARD))
selected_item--;
if (KeyPressed(BT_BACK))
selected_item++;
// wrap around
selected_item = mod(selected_item, NUM_MENU_ITEMS);

lerp

fixed lerp(fixed a, fixed b, fixed alpha)

Performs linear interpolation (or extrapolation) between two numbers and returns the result.

Simple animation of movement between two points:

for (int time = 0; time < 1.0; time += 0.05)
{
int x = lerp(x1, x2, time);
int y = lerp(y1, y2, time);
DrawSomething(x, y);
Delay(1);
}

Constants

fixed PI = 3.1415926535897932384626433832795 – the number π.

fixed TAU = 6.2831853071795864769252867665590 – the number Tau (2π) (see http://tauday.com/tau-manifesto).

fixed SQRT_2 = 1.41421356237 – square root of 2.

fixed MATH_E = 2.7182818284590452353602874713526624977572470937 – the number e.

fixed LOG2_E = 1.44269504089 – log2(e). Occurs commonly in some formulas.

fixed LOG2_10 = 3.32192809489 – log2(10). Occurs commonly in some formulas.