From b737bb2ddefdc0a93a1b4b279931b3b7ad5715f9 Mon Sep 17 00:00:00 2001
From: Recep Aslantas <info@recp.me>
Date: Tue, 27 Feb 2018 10:53:45 +0300
Subject: [PATCH] docs: add docs for affine matrix

---
 docs/source/affine-mat.rst | 77 ++++++++++++++++++++++++++++++++++++++
 docs/source/api.rst        |  1 +
 2 files changed, 78 insertions(+)
 create mode 100644 docs/source/affine-mat.rst

diff --git a/docs/source/affine-mat.rst b/docs/source/affine-mat.rst
new file mode 100644
index 0000000..0d09e12
--- /dev/null
+++ b/docs/source/affine-mat.rst
@@ -0,0 +1,77 @@
+.. default-domain:: C
+
+Affine Transform Matrix (Specialized Functions)
+================================================================================
+
+Header: cglm/affine-mat.h
+
+We mostly use glm_mat4_* for 4x4 general and transform matrices. **cglm**
+provides optimized version of some functions. Because affine transform matrix is
+a known format, for instance all last item of first three columns is zero.
+
+You should be careful when using these functions. For instance :c:func:`glm_mul`
+assumes matrix will be this format:
+
+.. code-block:: text
+
+   R  R  R  X
+   R  R  R  Y
+   R  R  R  Z
+   0  0  0  W
+
+if you override zero values here then use :c:func:`glm_mat4_mul` version.
+You cannot use :c:func:`glm_mul` anymore.
+
+Same is also true for :c:func:`glm_inv_tr` if you only have rotation and
+translation then it will work as expected, otherwise you cannot use that.
+
+In the future it may accept scale factors too but currectly it does not.
+
+Table of contents (click func go):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Functions:
+
+1. :c:func:`glm_mul`
+#. :c:func:`glm_inv_tr`
+
+Functions documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: void  glm_mul(mat4 m1, mat4 m2, mat4 dest)
+
+    | this is similar to glm_mat4_mul but specialized to affine transform
+
+    Matrix format should be:
+
+    .. code-block:: text
+
+       R  R  R  X
+       R  R  R  Y
+       R  R  R  Z
+       0  0  0  W
+
+    this reduces some multiplications. It should be faster than mat4_mul.
+    if you are not sure about matrix format then DON'T use this! use mat4_mul
+
+    Parameters:
+      | *[in]*  **m1**    affine matrix 1
+      | *[in]*  **m2**    affine matrix 2
+      | *[out]* **dest**  result matrix
+
+.. c:function:: void  glm_inv_tr(mat4 mat)
+
+    | inverse orthonormal rotation + translation matrix (ridig-body)
+
+    .. code-block:: text
+
+       X = | R  T |   X' = | R' -R'T |
+           | 0  1 |        | 0     1 |
+
+    use this if you only have rotation + translation, this should work faster
+    than :c:func:`glm_mat4_inv`
+
+    Don't use this if your matrix includes other things e.g. scale, shear...
+
+    Parameters:
+      | *[in,out]*  **mat**  affine matrix
diff --git a/docs/source/api.rst b/docs/source/api.rst
index 94164b1..01515cf 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -27,6 +27,7 @@ Follow the :doc:`build` documentation for this
    :caption: API categories:
 
    affine
+   affine-mat
    cam
    mat4
    mat3