Merge pull request #462 from under-view/feature/mat3x4-tables

mat3x4: add tables to docs & fix comments

include/cglm/call/mat3x4.h

@@ -15,11 +15,11 @@ extern "C" {
 
 CGLM_EXPORT
 void
-glmc_mat3x4_copy(mat3x4 mat, mat3x4 dest);
+glmc_mat3x4_copy(mat3x4 src, mat3x4 dest);
 
 CGLM_EXPORT
 void
-glmc_mat3x4_zero(mat3x4 mat);
+glmc_mat3x4_zero(mat3x4 m);
 
 CGLM_EXPORT
 void
@@ -35,7 +35,7 @@ glmc_mat3x4_mulv(mat3x4 m, vec3 v, vec4 dest);
 
 CGLM_EXPORT
 void
-glmc_mat3x4_transpose(mat3x4 m, mat4x3 dest);
+glmc_mat3x4_transpose(mat3x4 src, mat4x3 dest);
 
 CGLM_EXPORT
 void

include/cglm/mat3x4.h

@@ -11,12 +11,12 @@
    GLM_MAT3X4_ZERO
 
  Functions:
-   CGLM_INLINE void glm_mat3x4_copy(mat3x4 mat, mat3x4 dest);
-   CGLM_INLINE void glm_mat3x4_zero(mat3x4 mat);
+   CGLM_INLINE void glm_mat3x4_copy(mat3x4 src, mat3x4 dest);
+   CGLM_INLINE void glm_mat3x4_zero(mat3x4 m);
    CGLM_INLINE void glm_mat3x4_make(const float * __restrict src, mat3x4 dest);
    CGLM_INLINE void glm_mat3x4_mul(mat3x4 m1, mat4x3 m2, mat4 dest);
    CGLM_INLINE void glm_mat3x4_mulv(mat3x4 m, vec3 v, vec4 dest);
-   CGLM_INLINE void glm_mat3x4_transpose(mat3x4 m, mat4x3 dest);
+   CGLM_INLINE void glm_mat3x4_transpose(mat3x4 src, mat4x3 dest);
    CGLM_INLINE void glm_mat3x4_scale(mat3x4 m, float s);
  */
 
@@ -33,36 +33,36 @@
 #define GLM_MAT3X4_ZERO GLM_MAT3X4_ZERO_INIT
 
 /*!
- * @brief copy all members of [mat] to [dest]
+ * @brief Copy mat3x4 (src) to mat3x4 (dest).
  *
- * @param[in]  mat  source
- * @param[out] dest destination
+ * @param[in]  src  mat3x4 (left)
+ * @param[out] dest destination (result, mat3x4)
  */
 CGLM_INLINE
 void
-glm_mat3x4_copy(mat3x4 mat, mat3x4 dest) {
-  glm_vec4_ucopy(mat[0], dest[0]);
-  glm_vec4_ucopy(mat[1], dest[1]);
-  glm_vec4_ucopy(mat[2], dest[2]);
+glm_mat3x4_copy(mat3x4 src, mat3x4 dest) {
+  glm_vec4_ucopy(src[0], dest[0]);
+  glm_vec4_ucopy(src[1], dest[1]);
+  glm_vec4_ucopy(src[2], dest[2]);
 }
 
 /*!
- * @brief make given matrix zero.
+ * @brief Zero out the mat3x4 (m).
  *
- * @param[in, out]  mat  matrix
+ * @param[in, out] mat3x4 (src, dest)
  */
 CGLM_INLINE
 void
-glm_mat3x4_zero(mat3x4 mat) {
+glm_mat3x4_zero(mat3x4 m) {
   CGLM_ALIGN_MAT mat3x4 t = GLM_MAT3X4_ZERO_INIT;
-  glm_mat3x4_copy(t, mat);
+  glm_mat3x4_copy(t, m);
 }
 
 /*!
- * @brief Create mat3x4 matrix from pointer
+ * @brief Create mat3x4 (dest) from pointer (src).
  *
- * @param[in]  src  pointer to an array of floats
- * @param[out] dest matrix
+ * @param[in]  src  pointer to an array of floats (left)
+ * @param[out] dest destination (result, mat3x4)
  */
 CGLM_INLINE
 void
@@ -84,15 +84,15 @@ glm_mat3x4_make(const float * __restrict src, mat3x4 dest) {
 }
 
 /*!
- * @brief multiply m1 and m2 to dest
+ * @brief Multiply mat3x4 (m1) by mat4x3 (m2) and store in mat4 (dest).
  *
  * @code
  * glm_mat3x4_mul(mat3x4, mat4x3, mat4);
  * @endcode
  *
- * @param[in]  m1   left matrix (mat3x4)
- * @param[in]  m2   right matrix (mat4x3)
- * @param[out] dest destination matrix (mat4)
+ * @param[in]  m1   mat3x4 (left)
+ * @param[in]  m2   mat4x3 (right)
+ * @param[out] dest destination (result, mat4)
  */
 CGLM_INLINE
 void
@@ -128,11 +128,11 @@ glm_mat3x4_mul(mat3x4 m1, mat4x3 m2, mat4 dest) {
 }
 
 /*!
- * @brief multiply matrix with column vector and store in dest column vector
+ * @brief Multiply mat3x4 (m) by vec3 (v) and store in vec4 (dest).
  *
- * @param[in]  m    matrix (left)
- * @param[in]  v    vector (right, column vector)
- * @param[out] dest result vector
+ * @param[in]  m    mat3x4 (left)
+ * @param[in]  v    vec3 (right, column vector)
+ * @param[out] dest destination (result, column vector)
  */
 CGLM_INLINE
 void
@@ -146,27 +146,25 @@ glm_mat3x4_mulv(mat3x4 m, vec3 v, vec4 dest) {
 }
 
 /*!
- * @brief transpose matrix and store in dest
+ * @brief Transpose mat3x4 (src) and store in mat4x3 (dest).
  *
- * @param[in]  m     matrix
- * @param[out] dest  result
+ * @param[in]  src  mat3x4 (left)
+ * @param[out] dest destination (result, mat4x3)
  */
 CGLM_INLINE
 void
-glm_mat3x4_transpose(mat3x4 m, mat4x3 dest) {
-  dest[0][0] = m[0][0];  dest[0][1] = m[1][0];  dest[0][2] = m[2][0];
-  dest[1][0] = m[0][1];  dest[1][1] = m[1][1];  dest[1][2] = m[2][1];
-  dest[2][0] = m[0][2];  dest[2][1] = m[1][2];  dest[2][2] = m[2][2];
-  dest[3][0] = m[0][3];  dest[3][1] = m[1][3];  dest[3][2] = m[2][3];
+glm_mat3x4_transpose(mat3x4 src, mat4x3 dest) {
+  dest[0][0] = src[0][0];  dest[0][1] = src[1][0];  dest[0][2] = src[2][0];
+  dest[1][0] = src[0][1];  dest[1][1] = src[1][1];  dest[1][2] = src[2][1];
+  dest[2][0] = src[0][2];  dest[2][1] = src[1][2];  dest[2][2] = src[2][2];
+  dest[3][0] = src[0][3];  dest[3][1] = src[1][3];  dest[3][2] = src[2][3];
 }
 
 /*!
- * @brief scale (multiply with scalar) matrix
+ * @brief Multiply mat3x4 (m) by scalar constant (s).
  *
- * multiply matrix with scalar
- *
- * @param[in, out] m matrix
- * @param[in]    s scalar
+ * @param[in, out] m (src, dest)
+ * @param[in]      s float (scalar)
  */
 CGLM_INLINE
 void

include/cglm/struct/mat3x4.h

@@ -35,87 +35,85 @@
 #define GLMS_MAT3X4_ZERO ((mat3x4s)GLMS_MAT3X4_ZERO_INIT)
 
 /*!
- * @brief make given matrix zero.
+ * @brief Zero out the mat3x4s (dest).
  *
- * @param[in, out]  mat  matrix
+ * @return[out] dest constructed mat3x4s from raw pointer
  */
 CGLM_INLINE
 mat3x4s
 glms_mat3x4_(zero)(void) {
-  mat3x4s r;
-  glm_mat3x4_zero(r.raw);
-  return r;
+  mat3x4s dest;
+  glm_mat3x4_zero(dest.raw);
+  return dest;
 }
 
 /*!
- * @brief Create mat3x4 matrix from pointer
+ * @brief Create mat3x4s (dest) from pointer (src).
  *
- * @param[in]  src  pointer to an array of floats
- * @return constructed matrix from raw pointer
+ * @param[in]   src  pointer to an array of floats
+ * @return[out] dest constructed mat3x4s from raw pointer
  */
 CGLM_INLINE
 mat3x4s
 glms_mat3x4_(make)(const float * __restrict src) {
-  mat3x4s r;
-  glm_mat3x4_make(src, r.raw);
-  return r;
+  mat3x4s dest;
+  glm_mat3x4_make(src, dest.raw);
+  return dest;
 }
 
 /*!
- * @brief multiply m1 and m2 to dest
+ * @brief Multiply mat3x4s (m1) by mat4x3s (m2) and store in mat4s (dest).
  *
  * @code
  * r = glms_mat3x4_mul(mat3x4s, mat4x3s);
  * @endcode
  *
- * @param[in]  m1   left matrix (mat3x4s)
- * @param[in]  m2   right matrix (mat4x3s)
- * @returns destination matrix (mat4s)
+ * @param[in]   m1   mat3x4s (left)
+ * @param[in]   m2   mat4x3s (right)
+ * @return[out] dest constructed mat4s from raw pointers
  */
 CGLM_INLINE
 mat4s
 glms_mat3x4_(mul)(mat3x4s m1, mat4x3s m2) {
-  mat4s r;
-  glm_mat3x4_mul(m1.raw, m2.raw, r.raw);
-  return r;
+  mat4s dest;
+  glm_mat3x4_mul(m1.raw, m2.raw, dest.raw);
+  return dest;
 }
 
 /*!
- * @brief multiply matrix with column vector and store in dest column vector
+ * @brief Multiply mat3x4s (m) by vec3s (v) and store in vec4s (dest).
  *
- * @param[in]  m    matrix (left)
- * @param[in]  v    vector (right, column vector)
- * @returns destination vector (vec4s)
+ * @param[in]   m    mat3x4s (left)
+ * @param[in]   v    vec3s (right, column vector)
+ * @return[out] dest constructed vec4s from raw pointers
  */
 CGLM_INLINE
 vec4s
 glms_mat3x4_(mulv)(mat3x4s m, vec3s v) {
-  vec4s r;
-  glm_mat3x4_mulv(m.raw, v.raw, r.raw);
-  return r;
+  vec4s dest;
+  glm_mat3x4_mulv(m.raw, v.raw, dest.raw);
+  return dest;
 }
 
 /*!
- * @brief transpose matrix and store in dest
+ * @brief Transpose mat3x4s (m) and store in mat4x3s (dest).
  *
- * @param[in]  m     matrix
- * @param[out] dest  result
+ * @param[in]   m    mat3x4s (left)
+ * @return[out] dest constructed mat4x3s from raw pointers
  */
 CGLM_INLINE
 mat4x3s
 glms_mat3x4_(transpose)(mat3x4s m) {
-  mat4x3s r;
-  glm_mat3x4_transpose(m.raw, r.raw);
-  return r;
+  mat4x3s dest;
+  glm_mat3x4_transpose(m.raw, dest.raw);
+  return dest;
 }
 
 /*!
- * @brief scale (multiply with scalar) matrix
+ * @brief Multiply mat3x4s (m) by scalar constant (s).
  *
- * multiply matrix with scalar
- *
- * @param[in, out] m matrix
- * @param[in]    s scalar
+ * @param[in, out] m mat3x4s (src, dest)
+ * @param[in]      s float (scalar)
  */
 CGLM_INLINE
 mat3x4s