# `gliso` A [GLSL][]/[OpenGL][] [\>=2.1][] [isometry][] matrix library. If a `mat4` matrix represents an [isometry][], which in this case means that it encodes only rotations and translations (no scaling or shearing, and a projective `w` entry equal to `1`), it is easy and performant to extract those rotations and translations, and to compute the [inverse][]. This library provides functions to do so. [`gliso`]: https://git.rcrnstn.net/rcrnstn/gliso [GLSL]: https://en.wikipedia.org/wiki/OpenGL_Shading_Language [OpenGL]: https://en.wikipedia.org/wiki/OpenGL [\>=2.1]: https://en.wikipedia.org/wiki/OpenGL#Version_history [isometry]: https://en.wikipedia.org/wiki/Isometry [inverse]: https://en.wikipedia.org/wiki/Invertible_matrix ## Requirements Support for `#include` directives is required. This can be provided by e.g. the standardized [`ARB_shading_language_include`][] extension or some third party library. [`ARB_shading_language_include`]: https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shading_language_include.txt ## Usage Link shader programs with the provided `iso.glsl`. Include the provided `iso.h` from shaders. It declares the following functions: - `mat{3,4} isorot{inv}{3,4}(mat4 iso)` Extract (inverse) rotation. - `vec{3,4} isotrans{inv}{3,4}(mat4 iso)` Extract (inverse) translation. The `z` components of the `4` versions are set to `0`. - `mat4 isoinv(mat4 iso)` Compute inverse. ## Theory For simplicity, we use the same name for both the [projective][] and [Euclidean][] versions of vectors and transformations below. Assume $M$ is an isometry, $$ M v = \begin{pmatrix} r_{xx} & r_{yx} & r_{zx} & t_x \\ r_{xx} & r_{yx} & r_{zx} & t_y \\ r_{xx} & r_{yx} & r_{zx} & t_z \\ 0 & 0 & 0 & 1 \\ \end{pmatrix} \begin{pmatrix} v_x \\ v_y \\ v_z \\ 1 \\ \end{pmatrix} = R v + t $$ It is trivial to extract the rotation $R$ and translation $t$ directly from the components of $M$. Since the rotation part $R$ is [orthonormal][], its inverse is its own transpose. The inverse of the translation is its own negation. $$ \begin{aligned} R^{-1} &= R^T \\ t^{-1} &= -t \\ \end{aligned} $$ Assuming the $3 \mathsf{x} 3$ sub-matrix of $M^{-1}$ is $R^{-1}$, finding the full inverse is simply a matter of finding $M^{-1}$'s fourth column $m^{-1}$: $$ \begin{aligned} v &= M^{-1} M v \\ &= R^{-1} (R v + t) + m^{-1} \\ &= v + R^{-1} t + m^{-1} \\ &\iff \\ m^{-1} &= -R^{-1} t = R^{-1} t^{-1} \\ \end{aligned} $$ Computing this is much faster than the built-in, general, [`inverse`][]. [projective]: https://en.wikipedia.org/wiki/Homogeneous_coordinates [Euclidean]: https://en.wikipedia.org/wiki/Cartesian_coordinates [orthonormal]: https://en.wikipedia.org/wiki/Orthogonal_matrix [`inverse`]: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/inverse.xhtml ## Build system This project has support for [CMake][], and uses [`cmake-cxx`][]. There are several ways to use this project in another CMake-based project: - Use [`FetchContent`][] to download it and import the targets automatically as part of the configure step: ```cmake include(FetchContent) FetchContent_Declare(project-name GIT_REPOSITORY https://example.com/user/project-name ) FetchContent_MakeAvailable( project-name ) ``` - Bundle it and import the targets with [`add_subdirectory`][]. - Use [`find_package`][] (requires that the project is [packaged](#packaging) or [installed](#installing)). As usual, use [`add_dependencies`][]/[`target_link_libraries`][] to declare the dependency. [CMake]: https://cmake.org [`cmake-cxx`]: https://git.rcrnstn.net/rcrnstn/cmake-cxx [`FetchContent`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html [`add_subdirectory`]: https://cmake.org/cmake/help/v3.14/command/add_subdirectory.html [`find_package`]: https://cmake.org/cmake/help/v3.14/command/find_package.html [`add_dependencies`]: https://cmake.org/cmake/help/v3.14/command/add_dependencies.html [`target_link_libraries`]: https://cmake.org/cmake/help/v3.14/command/target_link_libraries.html ### Configure and generate To configure and generate a build tree, use `cmake`: ```sh cmake -B build ``` To set the [`CMAKE_BUILD_TYPE`][], pass e.g. `-DCMAKE_BUILD_TYPE=Release`. [`cmake`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#generate-a-project-buildsystem [`CMAKE_BUILD_TYPE`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BUILD_TYPE.html ### Build To build, use [`cmake --build`][]: ```sh cmake --build build ``` [`cmake --build`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#build-a-project ### Test To run tests, use [`ctest`][]: ```sh (cd build && ctest --output-on-failure) ``` [`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html ### Package To package, use [`cpack`][]: ```sh (cd build && cpack) ``` [`cpack`]: https://cmake.org/cmake/help/v3.14/manual/cpack.1.html ### Install To install onto the current system, use [`cmake --install`][]: ```sh cmake --install build ``` [`cmake --install`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#install-a-project ## License Licensed under the [ISC License][] unless otherwise noted, see the [`LICENSE`](LICENSE) file. [ISC License]: https://choosealicense.com/licenses/isc/