====== Математика ======

===== Заметки =====

==== Что такое "num"? ====

''num'' означает "любой численный тип" (int или fixed). Функции, принимающие num, принимают и int, и fixed. Например:

<code>
num max(num a, num b)
</code>

означает:

"Функция ''max'' принимает два числа и возвращает число. Если оба аргумента -- int, то она возвращает int. Если же оба аргумента fixed, то она возвращает fixed".

Это позволяет использовать функцию ''max'' обоими способами:
<code>
max(2, 5) == 5
max(2.0, 5.0) == 5.0
</code>

**Не смешивайте int и fixed числа** в ''num''. ''num'' в сигнатуре функции все являются либо int, либо fixed! Например, вот так неправильно:
<code>
max(5, 2.0)
</code>

Функция вернёт ''2.0'', потому что ''2.0'' (65536) больше, чем 5.

==== Об углах ====

Все углы в ACSUtils используют формат [[zdoom>Definitions#Fixed_point_angles|fixed-point angles]] из ZDoom (обороты), и допускается их выход за пределы диапазона ''0.0''-''1.0''. Все подобные случаи правильно обрабатываются и движком, и ACSUtils.

===== Константы =====

ACSUtils предоставляет набор математических констант. Все fixed констаты имеют много цифр после запятой, чтобы максимизировать точность. Они имеют даже больше цифр после запятой, чем нужно.

==== Пи и Тау ====

  * ''fixed PI  = 3.1415926535897932384626433832795;''
  * ''fixed TAU = 6.2831853071795864769252867665590;''

Числа Пи и [[https://tauday.com|Тау]].

==== e ====
''fixed MATH_E = 2.7182818284590452353602874713526624977572470937;''

Число [[wp>E_(mathematical_constant)|e]]. Названо ''MATH_E'' во избежание конфликтов с именем переменной ''e''.

==== Важные квадратные корни и логарифмы ====

Предварительно рассчитаны с максимальной точностью и часто встречаются в некоторых алгоритмах.

  * ''fixed SQRT_2 = 1.41421356237;'' -- sqrt(2)
  * ''fixed LOG2_E = 1.44269504089;'' -- log2(e)
  * ''fixed LOG2_10 = 3.32192809489;'' -- log2(10)

===== Математические функции общего назначения =====

==== abs ====
''num abs(num x)''

Возвращает модуль X:
  * Если X -- ноль или положительное число, возвращает X.
  * Если X -- отрицательное число, возвращает -X.

<note important>
**Остерегайтесь использования этой функции с ''[[limits#INT_MIN]]''.**

''abs(INT_MIN) == INT_MIN'', потому что ''-INT_MIN == INT_MIN''. Это единственный случай, когда ''abs'' возвращает отрицательное число.
</note>

==== sgn ====
''int sgn(int x)''

Возвращает знак X:
  * Если X положителен, возвращает ''1''.
  * Если X отрицателен, возвращает ''-1''.
  * Если X -- ноль, возвращает ''0''.

=== Пример использования ===
<code>
// Задаём скорость по X равную 15.0
// но с таким же знаком, что и у foo
int xvel = sgn(foo) * 15.0;
</code>

==== min ====
''num min(num a, num b)''

Возвращает меньшее из двух чисел.

==== max ====
''num max(num a, num b)''

Возвращает большее из двух чисел.

==== clamp ====
''num clamp(num x, num минимум, num максимум)''

Ограничивает X в указанном диапазоне:
  * Если X меньше минимума, возвращает минимум.
  * Если X между минимумом и максимумом, возвращает X.
  * Если X больше максимума, возвращает максимум.

==== cmp ====
''int cmp(num a, num b)''

Сравнивает два числа и возвращает результат:
  * Если A > B, возвращает ''1''.
  * Если A = B, возвращает ''0''.
  * Если A < B, возвращает ''-1''.


===== Тригонометрия =====

ACSUtils предоставляет полный набор тригонометрических функций:

  * [[zdoom>sin]] уже встроен в ZDoom.
  * [[zdoom>cos]] уже встроен в ZDoom.
  * ''fixed tan(fixed angle)'' -- реализован как ''FixedDiv(sin(x), cos(x))''.
  * ''fixed cot(fixed angle)'' -- реализован как ''FixedDiv(cos(x), sin(x))''.
  * ''fixed sec(fixed angle)'' -- реализован как ''FixedDiv(1.0, sin(x))''.
  * ''fixed cosec(fixed angle)'' -- реализован как ''FixedDiv(1.0, cos(x))''.

Inverse trigonometric functions:
  * ''fixed atan(fixed x)'' -- реализован как ''[[zdoom>VectorAngle]](1.0, x)''.
  * ''fixed acot(fixed x)'' -- реализован как ''0.25 - atan(x)''.
  * ''fixed asin(fixed x)'' -- реализован как ''atan(FixedDiv(x, FixedSqrt(1.0 - FixedMul(x, x))))''.
  * ''fixed acos(fixed x)'' -- реализован как ''ang(2 * atan(FixedSqrt(FixedDiv(1.0 - x, 1.0 + x))))''.
  * ''fixed asec(fixed x)'' -- реализован как ''acos(FixedDiv(1.0, x))''.
  * ''fixed acosec(fixed x)'' -- реализован как ''asin(FixedDiv(1.0, x))''.


===== Vector math =====

==== VectorLength3D ====
''fixed VectorLength3D(fixed x, fixed y, fixed z)''

Трёхмерная версия [[zdoom>VectorLength]]. Возвращает длину трёхмерного вектора.

==== dot ====
  * 2D: ''fixed dot2(fixed x1, fixed y1, fixed x2, fixed y2)''
  * 3D: ''fixed dot3(fixed x1, fixed y1, fixed z1, fixed x2, fixed y2, fixed z2)''

Возвращает [[wp>dot product|скалярное произведение]] двух векторов. Краткий способ записи ''FixedMul(x1, x2) + FixedMul(y1, y2) + ...''.

==== normalize ====
  * 2D: ''fixed, fixed normalize2d(fixed x, fixed y)''
  * 3D: ''fixed, fixed, fixed normalize3d(fixed x, fixed y, fixed z)''

[[wp>Normalized vector|Нормализует]] вектор и возвращает результат, используя [[multiple return values|несколько возвращаемых значений]].

=== Пример использования ===
<code>
normalize3d(x, y, z);
x = r1;
y = r2;
z = r2;
</code>

<code>
normalize2d(x, y);
int normalizedX = r1;
int normalziedY = r2;
</code>

==== RotateVector ====
''fixed, fixed RotateVector(fixed x, fixed y, fixed angle)''
  
Поворачивает вектор на указанный угол и возвращает результат, используя [[multiple return values|несколько возвращаемых значений]].

=== Example usage ===

<code>
RotateVector(x, y, angle);
x = r1;
y = r2;
</code>

==== RotateVectorCS ====
''fixed, fixed RotateVector(fixed x, fixed y, fixed cos, fixed sin)''

Более быстрая версия ''RotateVector'', которая принимает косинус и синус угла вращения, вместо того, чтобы вычислять их.

==== RotatePoint ====
''fixed, fixed RotatePoint(fixed x, fixed y, fixed originX, fixed originY, fixed angle)''

Rotates the point around the specified origin by the angle and returns the result using [[multiple return values]].

==== SqVectorLength ====
  * ''fixed SqVectorLength(fixed x, fixed y)''
  * ''fixed SqVectorLength3D(fixed x, fixed y, fixed z)''

Returns vector length squared. 

<note important>Because this function returns a fixed, it won't work correctly for vectors longer than ''256.0''!</note>

==== VectorToAngles ====
''fixed, fixed VectorToAngles(fixed x, fixed y, fixed z''

Converts the vector to a pair of angles (angle, pitch) and returns them using [[multiple return values]].

=== Example usage ===

<code>
// This function makes the actor look in the direction
// specified as a 3D vector.
function void LookInDirection(int tid, int x, int y, int z)
{
    VectorToAngles(x, y, z);
    int angle = r1;
    int pitch = r2;
    SetActorAngle(tid, angle);
    SetActorPitch(tid, -pitch); // SetActorPitch expects inverted pitch.
}
</code>

==== AnglesToVector ====
''fixed, fixed, fixed AnglesToVector(fixed angle, fixed pitch)''

Converts a pair of angles (angle, pitch) to a 3D vector of length ''1.0'' and returns it using [[multiple return values]].