doc: getting started

docs/source/conf.py

@@ -90,6 +90,16 @@ html_theme = 'alabaster'
 #
 # html_theme_options = {}
 
+html_theme_options = {
+    'github_banner': 'true',
+    'github_button': 'true',
+    'github_user': 'recp',
+    'github_repo': 'cglm',
+    'travis_button': 'true',
+    'show_related': 'true',
+    'fixed_sidebar': 'true'
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -151,6 +161,3 @@ texinfo_documents = [
      author, 'cglm', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-

docs/source/getting_started.rst

@@ -0,0 +1,66 @@
+Getting Started
+================================
+
+**cglm** uses **glm** prefix for all functions e.g. glm_lookat. You can see supported types in common header file:
+
+.. code-block:: c
+  :linenos:
+
+   typedef float vec3[3];
+   typedef int  ivec3[3];
+   typedef CGLM_ALIGN(16) float vec4[4];
+
+   typedef vec3 mat3[3];
+   typedef vec4 mat4[4];
+
+   typedef vec4 versor;
+
+As you can see types don't store extra informations in favor of space.
+You can send these values e.g. matrix to OpenGL directly without casting or calling a function like *value_ptr*
+
+*vec4* and *mat4* requires 16 byte aligment because vec4 and mat4 operations are
+vectorized by SIMD instructions (SSE/AVX).
+
+**NOTE:** Unaligned vec4 and unaligned mat4 operations will be supported in the future. Check todo list.
+Because you may want to multiply a CGLM matrix with external matrix.
+There is no guarantee that non-CGLM matrix is aligned. Unaligned types will have *u* prefix e.g. **umat4**
+
+cglm provides a few way to call a function to do same operation.
+
+* Inline - *glm_, glm_u*
+   * aligned
+   * unaligned (todo)
+* Pre-compiled - *glmc_, glmc_u*
+   * aligned
+   * unaligned (todo)
+
+For instance **glm_mat4_mul** is inline (all *glm_* functions are inline), to make it non-inline (pre-compiled)
+call it as **glmc_mat4_mul** from library, to use unaligned version use **glm_umat4_mul** (todo).
+
+Most functions have **dest** parameter for output. For instance mat4_mul func looks like this:
+
+.. code-block:: c
+
+   CGLM_INLINE
+   void
+   glm_mat4_mul(mat4 m1, mat4 m2, mat4 dest)
+
+The dest parameter is out parameter. Result will be stored in **dest**.
+Also in this case matrix multiplication order is dest = m1 * m2.
+
+* Changing parameter order will change the multiplication order.
+* You can pass all parameter same (this is similar to m1 `*=` m1), you can pass **dest** as m1 or m2 (this is similar to m1 `*=` m2)
+
+**v** postfix in function names
+-------------------------------
+
+You may see **v** postfix in some function names, v stands for vector.
+For instance consider a function that accepts three parameters x, y, z.
+This function may be overloaded by **v** postfix to accept vector (vec3) instead of separate parameters.
+In some places the v means that it will be apply to a vector.
+
+**_to** postfix in function names
+---------------------------------
+
+*_to* version of function will store the result in specified parameter instead of in-out parameter.
+Some functions don't have _to prefix but they still behave like this e.g. glm_mat4_mul.

docs/source/index.rst

@@ -35,6 +35,7 @@ Also currently only **float** type is supported for most operations.
    :caption: Table Of Contents:
 
    build
+   getting_started
 
 Indices and tables
 ==================