1. rcrnstn/glslisometry
  2. README.md
Browse code

Add implementation

Robert Cranston authored on 21/12/2021 12:41:46
Showing 1 changed files
README.md
History View file @ b57b691
... ... 
@@ -2,11 +2,106 @@
2 2
3 3 
 A [GLSL][]/[OpenGL][] [\>=2.1][] [isometry][] matrix library.
4 4
5 
+If a `mat4` matrix represents an [isometry][], which in this case means that it
6 
+encodes only rotations and translations (no scaling or shearing, and a
7 
+projective `w` entry equal to `1`), it is easy and performant to extract those
8 
+rotations and translations, and to compute the [inverse][]. This library
9 
+provides functions to do so.
10 
+
5 11 
 [`gliso`]: https://git.rcrnstn.net/rcrnstn/gliso
6 12 
 [GLSL]: https://en.wikipedia.org/wiki/OpenGL_Shading_Language
7 13 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 14 
 [\>=2.1]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 15 
 [isometry]: https://en.wikipedia.org/wiki/Isometry
16 
+[inverse]: https://en.wikipedia.org/wiki/Invertible_matrix
17 
+
18 
+## Requirements
19 
+
20 
+Support for `#include` directives is required. This can be provided by e.g. the
21 
+standardized [`ARB_shading_language_include`][] extension or some third party
22 
+library.
23 
+
24 
+[`ARB_shading_language_include`]: https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shading_language_include.txt
25 
+
26 
+## Usage
27 
+
28 
+Link shader programs with the provided `iso.glsl`.
29 
+
30 
+Include the provided `iso.h` from shaders. It declares the following functions:
31 
+
32 
+-   `mat{3,4} isorot{inv}{3,4}(mat4 iso)`
33 
+
34 
+    Extract (inverse) rotation.
35 
+
36 
+-   `vec{3,4} isotrans{inv}{3,4}(mat4 iso)`
37 
+
38 
+    Extract (inverse) translation.
39 
+
40 
+    The `z` components of the `4` versions are set to `0`.
41 
+
42 
+-   `mat4 isoinv(mat4 iso)`
43 
+
44 
+    Compute inverse.
45 
+
46 
+## Theory
47 
+
48 
+For simplicity, we use the same name for both the [projective][] and
49 
+[Euclidean][] versions of vectors and transformations below.
50 
+
51 
+Assume $M$ is an isometry,
52 
+
53 
+$$
54 
+M v
55 
+=
56 
+\begin{pmatrix}
57 
+    r_{xx} & r_{yx} & r_{zx} & t_x \\
58 
+    r_{xx} & r_{yx} & r_{zx} & t_y \\
59 
+    r_{xx} & r_{yx} & r_{zx} & t_z \\
60 
+         0 &      0 &      0 &   1 \\
61 
+\end{pmatrix}
62 
+\begin{pmatrix}
63 
+    v_x \\
64 
+    v_y \\
65 
+    v_z \\
66 
+      1 \\
67 
+\end{pmatrix}
68 
+=
69 
+R v + t
70 
+$$
71 
+
72 
+It is trivial to extract the rotation $R$ and translation $t$ directly from the
73 
+components of $M$.
74 
+
75 
+Since the rotation part $R$ is [orthonormal][], its inverse is its own
76 
+transpose. The inverse of the translation is its own negation.
77 
+
78 
+$$
79 
+\begin{aligned}
80 
+    R^{-1} &= R^T \\
81 
+    t^{-1} &= -t \\
82 
+\end{aligned}
83 
+$$
84 
+
85 
+Assuming the $3 \mathsf{x} 3$ sub-matrix of $M^{-1}$ is $R^{-1}$, finding the
86 
+full inverse is simply a matter of finding $M^{-1}$'s fourth column $m^{-1}$:
87 
+
88 
+$$
89 
+\begin{aligned}
90 
+    v
91 
+    &= M^{-1} M v \\
92 
+    &= R^{-1} (R v + t) + m^{-1} \\
93 
+    &= v + R^{-1} t + m^{-1} \\
94 
+    &\iff \\
95 
+    m^{-1} &= -R^{-1} t = R^{-1} t^{-1} \\
96 
+\end{aligned}
97 
+$$
98 
+
99 
+Computing this is much faster than the built-in, general, [`inverse`][].
100 
+
101 
+[projective]: https://en.wikipedia.org/wiki/Homogeneous_coordinates
102 
+[Euclidean]: https://en.wikipedia.org/wiki/Cartesian_coordinates
103 
+[orthonormal]: https://en.wikipedia.org/wiki/Orthogonal_matrix
104 
+[`inverse`]: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/inverse.xhtml
10 105
11 106 
 ## Build system
12 107
Browse code

Add project

Robert Cranston authored on 22/12/2021 09:57:03
Showing 1 changed files
README.md
History View file @ bc48408
... ... 
@@ -8,6 +8,94 @@ A [GLSL][]/[OpenGL][] [\>=2.1][] [isometry][] matrix library.
8 8 
 [\>=2.1]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 9 
 [isometry]: https://en.wikipedia.org/wiki/Isometry
10 10
11 
+## Build system
12 
+
13 
+This project has support for [CMake][], and uses [`cmake-cxx`][].
14 
+
15 
+There are several ways to use this project in another CMake-based project:
16 
+
17 
+-   Use [`FetchContent`][] to download it and import the targets automatically
18 
+    as part of the configure step:
19 
+
20 
+    ```cmake
21 
+    include(FetchContent)
22 
+    FetchContent_Declare(project-name
23 
+        GIT_REPOSITORY https://example.com/user/project-name
24 
+    )
25 
+    FetchContent_MakeAvailable(
26 
+        project-name
27 
+    )
28 
+    ```
29 
+
30 
+-   Bundle it and import the targets with [`add_subdirectory`][].
31 
+
32 
+-   Use [`find_package`][] (requires that the project is [packaged](#packaging)
33 
+    or [installed](#installing)).
34 
+
35 
+As usual, use [`add_dependencies`][]/[`target_link_libraries`][] to declare the
36 
+dependency.
37 
+
38 
+[CMake]: https://cmake.org
39 
+[`cmake-cxx`]: https://git.rcrnstn.net/rcrnstn/cmake-cxx
40 
+[`FetchContent`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html
41 
+[`add_subdirectory`]: https://cmake.org/cmake/help/v3.14/command/add_subdirectory.html
42 
+[`find_package`]: https://cmake.org/cmake/help/v3.14/command/find_package.html
43 
+[`add_dependencies`]: https://cmake.org/cmake/help/v3.14/command/add_dependencies.html
44 
+[`target_link_libraries`]: https://cmake.org/cmake/help/v3.14/command/target_link_libraries.html
45 
+
46 
+### Configure and generate
47 
+
48 
+To configure and generate a build tree, use `cmake`:
49 
+
50 
+```sh
51 
+cmake -B build
52 
+```
53 
+
54 
+To set the [`CMAKE_BUILD_TYPE`][], pass e.g. `-DCMAKE_BUILD_TYPE=Release`.
55 
+
56 
+[`cmake`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#generate-a-project-buildsystem
57 
+[`CMAKE_BUILD_TYPE`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BUILD_TYPE.html
58 
+
59 
+### Build
60 
+
61 
+To build, use [`cmake --build`][]:
62 
+
63 
+```sh
64 
+cmake --build build
65 
+```
66 
+
67 
+[`cmake --build`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#build-a-project
68 
+
69 
+### Test
70 
+
71 
+To run tests, use [`ctest`][]:
72 
+
73 
+```sh
74 
+(cd build && ctest --output-on-failure)
75 
+```
76 
+
77 
+[`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html
78 
+
79 
+### Package
80 
+
81 
+To package, use [`cpack`][]:
82 
+
83 
+```sh
84 
+(cd build && cpack)
85 
+```
86 
+
87 
+[`cpack`]: https://cmake.org/cmake/help/v3.14/manual/cpack.1.html
88 
+
89 
+### Install
90 
+
91 
+To install onto the current system, use [`cmake --install`][]:
92 
+
93 
+```sh
94 
+cmake --install build
95 
+```
96 
+
97 
+[`cmake --install`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#install-a-project
98 
+
11 99 
 ## License
12 100
13 101 
 Licensed under the [ISC License][] unless otherwise noted, see the
Browse code

Add license

Robert Cranston authored on 21/12/2021 12:34:50
Showing 1 changed files
README.md
History View file @ 9fe502a
... ... 
@@ -7,3 +7,10 @@ A [GLSL][]/[OpenGL][] [\>=2.1][] [isometry][] matrix library.
7 7 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 8 
 [\>=2.1]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 9 
 [isometry]: https://en.wikipedia.org/wiki/Isometry
10 
+
11 
+## License
12 
+
13 
+Licensed under the [ISC License][] unless otherwise noted, see the
14 
+[`LICENSE`](LICENSE) file.
15 
+
16 
+[ISC License]: https://choosealicense.com/licenses/isc/
Browse code

Add readme

Robert Cranston authored on 21/12/2021 12:33:52
Showing 1 changed files
README.md
History View file @ b85356c
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,9 @@
1 
+# `gliso`
2 
+
3 
+A [GLSL][]/[OpenGL][] [\>=2.1][] [isometry][] matrix library.
4 
+
5 
+[`gliso`]: https://git.rcrnstn.net/rcrnstn/gliso
6 
+[GLSL]: https://en.wikipedia.org/wiki/OpenGL_Shading_Language
7 
+[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 
+[\>=2.1]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 
+[isometry]: https://en.wikipedia.org/wiki/Isometry