| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| new:math [2018/02/18 18:51] – korshun | new:math [2019/04/21 01:25] (current) – [Other useful functions] korshun |
|---|
| ====== Math functions ====== | * ''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. |
| 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. | |
| | |
| ==== Bit math ==== | |
| | |
| * ''int npo2(int x)'' -- returns the lowest power of 2 greater or equal to X. | |
| * ''int bitlog2(int x)'' -- returns the index of the highest used bit, aka integer binary logarithm. Useful to convert flags like ''1<<8 = 256'' back into ''8''. | |
| | |
| ==== Trigonometry ==== | |
| | |
| * [[zdoom>sin]] is already in ZDoom | |
| * [[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 ==== | ==== Vector math ==== |
| |
| Since some functions need to return a vector or a pair of angles, they use the ACSUtils [[multiple return values]] convention. | Since some functions need to return a vector or a pair of angles, they use the ACSUtils [[multiple return values]] convention. |
| | |
| | <note important>ZDoom [[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.</note> |
| |
| Functions returning one value: | Functions returning one value: |
| |
| * ''fixed VectorLength3D(fixed x, fixed y, fixed z)'' -- a 3D version of [[zdoom>VectorLength]]. Shorthand for ''VectorLength(z, VectorLength(x, y))''. | * ''fixed VectorLength3D(fixed x, fixed y, fixed z)'' -- a 3D version of [[zdoom>VectorLength]]. Shorthand for ''VectorLength(z, VectorLength(x, y))''. |
| * ''fixed SqVectorLength(fixed x, fixed y)'' -- squared length of 2D vector. May be faster for length comparisons. | * ''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 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 dot2(fixed x1, fixed y1, fixed x2, fixed y2)'' -- dot product of two 2D vectors. |
| * ''fixed, fixed VectorToAngles(fixed x, fixed y, fixed z)'' -- converts vector to a pair of angles (angle and pitch) | * ''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 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 RotateVectorCS(fixed x, fixed y, fixed rx, fixed ry)'' -- returns vector rotated by another vector's angle. Result is multipled by the second vector's length. If the second vector is normalized, it's a (cos(angle), sin(angle)) vector of rotation angle. |
| * ''fixed, fixed RotatePoint(fixed x, fixed y, fixed originX, fixed originY, fixed angle)'' -- returns 2D point rotated by angle around the origin. | * ''fixed, fixed RotatePoint(fixed x, fixed y, fixed originX, fixed originY, fixed angle)'' -- returns 2D point rotated by angle around the origin. |
| |
| * ''fixed, fixed, fixed normalize3d(fixed x, fixed y, fixed z)'' -- returns normalized 3D vector. | * ''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. | * ''fixed, fixed, fixed AnglesToVector(fixed angle, fixed pitch)'' -- converts a pair of angles to a vector of length 1. |
| |
| <note important>ZDoom [[zdoom>GetActorPitch]] returns actor pitch with the wrong sign (multiplied by -1). Make sure to fix the sign before using actor pitch in the above vector functions.</note> | |
| |
| ==== Other useful functions ==== | ==== Other useful functions ==== |
| selected_item = mod(selected_item, NUM_MENU_ITEMS); | selected_item = mod(selected_item, NUM_MENU_ITEMS); |
| </code> | </code> |
| |
| === lerp === | |
| |
| ''fixed lerp(fixed a, fixed b, fixed alpha)'' | |
| |
| Performs [[wp>Linear interpolation|linear interpolation]] (or extrapolation) between two numbers and returns the result. | |
| |
| Simple animation of movement between two points: | |
| <code> | |
| 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); | |
| } | |
| </code> | |
| |
| |
| |
| ===== 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. | |
| |
| |
| |
| |
