add mat4.decompose

doc/en/scripting/builtins/libmat4.md

@@ -9,6 +9,7 @@ Most functions have several options for argument lists (overloads).
 Type conventions will be used on this page.
 - vector - an array of three or four numbers
 - vec3 - array of three numbers
+- vec4 - array of four numbers
 - matrix - array of 16 numbers - matrix
 
 > [!WARNING]
@@ -98,7 +99,23 @@ mat4.rotate(m: matrix, axis: vec3, angle: number)
 mat4.rotate(m: matrix, axis: vec3, angle: number, dst: matrix)
 ```
 
-## Translation to string - *mat4.tostring(...)*
+## Decomposition - *mat4.decompose(...)*
+
+Decomposes the transformation matrix into its components.
+
+```lua
+mat4.decompose(m: matrix)
+-- returns a table:
+{
+    scale=vec3,
+    rotation=matrix,
+    translation=vec3,
+    skew=vec3,
+    perspective=vec4
+}
+```
+
+## Casting to string - *mat4.tostring(...)*
 
 ```lua
 -- returns a string representing the contents of the matrix

doc/ru/scripting/builtins/libmat4.md

@@ -9,6 +9,7 @@
 На данной странице будут использоваться условные обозначения типов.
 - vector - массив из трех или четырех чисел
 - vec3 - массив из трех чисел
+- vec4 - массив из четырех чисел
 - matrix - массив из 16 чисел - матрица
 
 > [!WARNING]
@@ -98,6 +99,22 @@ mat4.rotate(m: matrix, axis: vec3, angle: number)
 mat4.rotate(m: matrix, axis: vec3, angle: number, dst: matrix)
 ```
 
+## Декомпозиция - *mat4.decompose(...)*
+
+Раскладывает матрицу трансформации на составляющие.
+
+```lua
+mat4.decompose(m: matrix)
+-- возвращает таблицу:
+{
+    scale=vec3,
+    rotation=matrix,
+    translation=vec3,
+    skew=vec3,
+    perspective=vec4 
+}
+```
+
 ## Перевод в строку - *mat4.tostring(...)*
 
 ```lua

src/logic/scripting/lua/libmat4.cpp

@@ -1,7 +1,11 @@
 #include "api_lua.hpp"
 
 #include <sstream>
+
+#define GLM_ENABLE_EXPERIMENTAL
 #include <glm/ext/matrix_transform.hpp>
+#include <glm/gtx/matrix_decompose.hpp>
+#include <glm/gtx/quaternion.hpp>
 
 /// Overloads:
 /// mat4.idt() -> float[16] - creates identity matrix
@@ -165,6 +169,48 @@ static int l_transpose(lua::State* L) {
     return 0;
 }
 
+/// mat4.decompose(m: float[16]) -> {
+///   scale=float[3],
+///   rotation=float[16],
+///   translation=float[3],
+///   skew=float[3],
+///   perspective=float[4]
+/// }
+static int l_decompose(lua::State* L) {
+    auto matrix = lua::tomat4(L, 1);
+    glm::vec3 scale;
+    glm::quat rotation;
+    glm::vec3 translation;
+    glm::vec3 skew;
+    glm::vec4 perspective;
+    glm::decompose(
+        matrix,
+        scale,
+        rotation,
+        translation,
+        skew,
+        perspective
+    );
+
+    lua::createtable(L, 0, 5);
+
+    lua::pushvec3_arr(L, scale);
+    lua::setfield(L, "scale");
+
+    lua::pushmat4(L, glm::toMat4(rotation));
+    lua::setfield(L, "rotation");
+
+    lua::pushvec3_arr(L, translation);
+    lua::setfield(L, "translation");
+
+    lua::pushvec3_arr(L, skew);
+    lua::setfield(L, "skew");
+
+    lua::pushvec4_arr(L, perspective);
+    lua::setfield(L, "perspective");
+    return 1;
+}
+
 static int l_tostring(lua::State* L) {
     auto matrix = lua::tomat4(L, 1);
     bool multiline = lua::toboolean(L, 2);
@@ -202,6 +248,7 @@ const luaL_Reg mat4lib [] = {
     {"inverse", lua::wrap<l_inverse>},
     {"transpose", lua::wrap<l_transpose>},
     {"determinant", lua::wrap<l_determinant>},
+    {"decompose", lua::wrap<l_decompose>},
     {"tostring", lua::wrap<l_tostring>},
     {NULL, NULL}
 };