diff --git a/doc/en/scripting.md b/doc/en/scripting.md index 18b1e762..2f815077 100644 --- a/doc/en/scripting.md +++ b/doc/en/scripting.md @@ -7,6 +7,8 @@ Subsections: - [User input](scripting/user-input.md) - [Filesystem and serialization](scripting/filesystem.md) - [UI properties and methods](scripting/ui.md) +- [Libraries](#) + - [mat4](scripting/builtins/libmat4.md) - [Module core:bit_converter](scripting/modules/core_bit_converter.md) - [Module core:data_buffer](scripting/modules/core_data_buffer.md) - [Module core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md) diff --git a/doc/en/scripting/builtins/libmat4.md b/doc/en/scripting/builtins/libmat4.md new file mode 100644 index 00000000..4327fc34 --- /dev/null +++ b/doc/en/scripting/builtins/libmat4.md @@ -0,0 +1,100 @@ +# *mat4* library + +*mat4* contains a set of functions for work with transformation 4x4 matrices. + +Most functions have several options for argument lists (overloads). + +## Data types + +Type conventions will be used on this page. +- vector - an array of three or four numbers +- vec3 - array of three numbers +- matrix - array of 16 numbers - matrix + +>[!ATTENTION] +> Type annotations are part of the documentation and are not present in Lua. + +## Identity matrix - *mat4.idt(...)* + +```lua +-- creates an identity matrix +mat4.idt() + +-- writes an identity matrix to dst +mat4.idt(dst: matrix) +``` + +## Matrix multiplication - *mat4.mul(...)* + +```lua +-- returns the result of matrix multiplication +mat4.mul(a: matrix, b: matrix) +-- writes the result of matrix multiplication to dst +mat4.mul(a: matrix, b: matrix, dst: matrix) + +-- returns the result of multiplying a matrix and a vector +mat4.mul(a: matrix, v: vector) +-- writes the result of matrix and vector multiplication to dst +mat4.mul(a: matrix, v: vector, dst: vector) +``` + +## Matrix inversion - *mat4.inverse(...)* + +```lua +-- returns the result of matrix inversion +mat4.inverse(m: matrix) +-- writes the result of matrix inversion to dst +mat4.inverse(m: matrix, dst: matrix) +``` + +## Matrix transposition - *mat4.transpose(...)* + +```lua +-- returns the result of matrix transposition +mat4.transpose(m: matrix) +-- writes the result of matrix transposition to dst +mat4.transpose(m: matrix, dst: matrix) +``` + +## Offset - *mat4.translate(...)* + +```lua +-- creates a translation matrix +mat4.translate(translation: vec3) +-- returns the result of applying a translation to matrix m +mat4.translate(m: matrix, translation: vec3) +-- writes the result of applying a translation to matrix m to dst +mat4.translate(m: matrix, translation: vec3, dst: matrix) +``` +## Scaling - *mat4.scale(...)* + +```lua +-- creates a scaling matrix +mat4.scale(scale: vec3) +-- returns the result of applying scaling to matrix m +mat4.scale(m: matrix, scale: vec3) +-- writes the result of applying scaling to matrix m to dst +mat4.scale(m: matrix, scale: vec3, dst: matrix) +``` + +## Rotation - *mat4.rotate(...)* + +The angle of rotation is indicated in degrees. + +```lua +-- creates a rotation matrix (angle - rotation angle) along a given axis (axis is an unit vector) +mat4.rotate(axis: vec3, angle: number) +-- returns the result of applying rotation to matrix m +mat4.rotate(m: matrix, axis: vec3, angle: number) +-- writes the result of applying rotation to matrix m to dst +mat4.rotate(m: matrix, axis: vec3, angle: number, dst: matrix) +``` + +## Translation to string - *mat4.tostring(...)* + +```lua +-- returns a string representing the contents of the matrix +mat4.tostring(m: matrix) +-- returns a string representing the contents of the matrix, human-readable if multiline = true +mat4.tostring(m: matrix, multiline: bool) +``` diff --git a/doc/ru/scripting.md b/doc/ru/scripting.md index 80a6f3c6..2335431e 100644 --- a/doc/ru/scripting.md +++ b/doc/ru/scripting.md @@ -7,6 +7,8 @@ - [Пользовательский ввод](scripting/user-input.md) - [Файловая система и сериализация](scripting/filesystem.md) - [Свойства и методы UI элементов](scripting/ui.md) +- [Библиотеки](#) + - [mat4](scripting/builtins/libmat4.md) - [Модуль core:bit_converter](scripting/modules/core_bit_converter.md) - [Модуль core:data_buffer](scripting/modules/core_data_buffer.md) - [Модули core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md) diff --git a/doc/ru/scripting/builtins/libmat4.md b/doc/ru/scripting/builtins/libmat4.md new file mode 100644 index 00000000..9be91165 --- /dev/null +++ b/doc/ru/scripting/builtins/libmat4.md @@ -0,0 +1,100 @@ +# Библиотека *mat4* + +*mat4* содержит набор функций для работы с матрицами трансформации размерностью 4x4. + +Большинство функций имеют несколько вариантов списка агрументов (перегрузок). + +## Типы данных + +На данной странице будут использоваться условные обозначения типов. +- vector - массив из трех или четырех чисел +- vec3 - массив из трех чисел +- matrix - массив из 16 чисел - матрица + +>[!ATTENTION] +> Аннотации типов являются частью документации и не указываются при вызове использовании. + +## Единичная матрица - *mat4.idt(...)* + +```lua +-- создает единичную матрицу +mat4.idt() + +-- записывает единичную матрицу в dst +mat4.idt(dst: matrix) +``` + +## Умножение матриц - *mat4.mul(...)* + +```lua +-- возвращает результат умножения матриц +mat4.mul(a: matrix, b: matrix) +-- записывает результат умножения матриц в dst +mat4.mul(a: matrix, b: matrix, dst: matrix) + +-- возвращает результат умножения матрицы и вектора +mat4.mul(a: matrix, v: vector) +-- записывает результат умножения матрицы и вектора в dst +mat4.mul(a: matrix, v: vector, dst: vector) +``` + +## Инверсия матрицы - *mat4.inverse(...)* + +```lua +-- возвращает результат инверсии матрицы +mat4.inverse(m: matrix) +-- записывает результат инверсии матрицы в dst +mat4.inverse(m: matrix, dst: matrix) +``` + +## Транспонирование матрицы - *mat4.transpose(...)* + +```lua +-- возвращает результат транспонирования матрицы +mat4.transpose(m: matrix) +-- записывает результат транспонирования матрицы в dst +mat4.transpose(m: matrix, dst: matrix) +``` + +## Смещение - *mat4.translate(...)* + +```lua +-- создает матрицу смещения +mat4.translate(translation: vec3) +-- возвращает результат применения смещения к матрице m +mat4.translate(m: matrix, translation: vec3) +-- записывает результат применения смещения к матрице m в dst +mat4.translate(m: matrix, translation: vec3, dst: matrix) +``` +## Масштабирование - *mat4.scale(...)* + +```lua +-- создает матрицу масштабирования +mat4.scale(scale: vec3) +-- возвращает результат применения масштабирования к матрице m +mat4.scale(m: matrix, scale: vec3) +-- записывает результат применения масштабирования к матрице m в dst +mat4.scale(m: matrix, scale: vec3, dst: matrix) +``` + +## Вращение - *mat4.rotate(...)* + +Угол поворота (angle) указывается в градусах. + +```lua +-- создает матрицу поворота (angle - угол поворота) по заданной оси (axis - единичный вектор) +mat4.rotate(axis: vec3, angle: number) +-- возвращает результат применения вращения к матрице m +mat4.rotate(m: matrix, axis: vec3, angle: number) +-- записывает результат применения вращения к матрице m в dst +mat4.rotate(m: matrix, axis: vec3, angle: number, dst: matrix) +``` + +## Перевод в строку - *mat4.tostring(...)* + +```lua +-- возвращает строку представляющую содержимое матрицы +mat4.tostring(m: matrix) +-- возвращает строку представляющую содержимое матрицы, многострочную, если multiline = true +mat4.tostring(m: matrix, multiline: bool) +```