From b33e29d50feb7d0f99998e0f8e9a3775709724e0 Mon Sep 17 00:00:00 2001 From: Vincent Davis Jr Date: Fri, 4 Apr 2025 13:22:27 -0400 Subject: [PATCH] mat4x3: add tables to docs & fix comments Signed-off-by: Vincent Davis Jr --- docs/source/mat4x3.rst | 179 ++++++++++++++++++++++++----------- include/cglm/call/mat4x3.h | 6 +- include/cglm/mat4x3.h | 98 ++++++++----------- include/cglm/struct/mat4x3.h | 70 +++++++------- src/mat4x3.c | 12 +-- 5 files changed, 206 insertions(+), 159 deletions(-) diff --git a/docs/source/mat4x3.rst b/docs/source/mat4x3.rst index 5136e88..ac3a1f6 100644 --- a/docs/source/mat4x3.rst +++ b/docs/source/mat4x3.rst @@ -27,7 +27,7 @@ Represented ~~~~~~~~~~~ .. csv-table:: mat4x3 - :header: "", "column 1", "column 2", "column 3", "column4" + :header: "", "column 1", "column 2", "column 3", "column 4" "row 1", "m00", "m10", "m20", "m30" "row 2", "m01", "m11", "m21", "m31" @@ -36,52 +36,103 @@ Represented Functions documentation ~~~~~~~~~~~~~~~~~~~~~~~ -.. c:function:: void glm_mat4x3_copy(mat4x3 mat, mat4x3 dest) +.. c:function:: void glm_mat4x3_copy(mat4x3 src, mat4x3 dest) - copy mat4x3 to another one (dest). + Copy mat4x3 (src) to mat4x3 (dest). Parameters: - | *[in]* **mat** source - | *[out]* **dest** destination + | *[in]* **src** mat4x3 (left) + | *[out]* **dest** destination (result, mat4x3) -.. c:function:: void glm_mat4x3_zero(mat4x3 mat) - - make given matrix zero - - Parameters: - | *[in,out]* **mat** matrix - -.. c:function:: void glm_mat4x3_make(const float * __restrict src, mat4x3 dest) - - Create mat4x3 matrix from pointer - - .. note:: **@src** must contain at least 12 elements. - - Parameters: - | *[in]* **src** pointer to an array of floats - | *[out]* **dest** destination matrix4x3 - -.. c:function:: void glm_mat4x3_mul(mat4x3 m1, mat3x4 m2, mat3 dest) - - multiply m1 and m2 to dest - - .. code-block:: c - - glm_mat4x3_mul(mat4x3, mat3x4, mat3); - - Parameters: - | *[in]* **m1** left matrix (mat4x3) - | *[in]* **m2** right matrix (mat3x4) - | *[out]* **dest** destination matrix (mat3) - - .. csv-table:: mat4x3 + .. csv-table:: mat4x3 **(src)** :header: "", "column 1", "column 2", "column 3", "column 4" "row 1", "a00", "a10", "a20", "a30" "row 2", "a01", "a11", "a21", "a31" "row 3", "a02", "a12", "a22", "a32" - .. csv-table:: mat3x4 + .. csv-table:: mat4x3 **(dest)** + :header: "", "column 1", "column 2", "column 3", "column 4" + + "row 1", "b00 = a00", "b10 = a10", "b20 = a20", "b30 = a30" + "row 2", "b01 = a01", "b11 = a11", "b21 = a21", "b31 = a31" + "row 3", "b02 = a02", "b12 = a12", "b22 = a22", "b32 = a32" + +.. c:function:: void glm_mat4x3_zero(mat4x3 m) + + Zero out the mat4x3 (m). + + Parameters: + | *[in, out]* **m** mat4x3 (src, dest) + + .. csv-table:: mat4x3 **(m)** + :header: "", "column 1", "column 2", "column 3", "column 4" + + "row 1", "0.00", "2.00", "15.00", "44.00" + "row 2", "5.00", "4.00", "6.00", "12.00" + "row 3", "88.00", "8.00", "4.30", "15.00" + + .. csv-table:: mat4x3 **(m)** + :header: "", "column 1", "column 2", "column 3", "column 4" + + "row 1", "0.00", "0.00", "0.00", "0.00" + "row 2", "0.00", "0.00", "0.00", "0.00" + "row3", "0.00", "0.00", "0.00", "0.00" + +.. c:function:: void glm_mat4x3_make(const float * __restrict src, mat4x3 dest) + + Create mat4x3 (dest) from pointer (src). + + .. note:: **@src** must contain at least 12 elements. + + Parameters: + | *[in]* **src** pointer to an array of floats (left) + | *[out]* **dest** destination (result, mat4x3) + + .. csv-table:: float array (1x12) **(src)** + :header: "", "column 1" + + "row 1", "v0" + "row 2", "v1" + "row 3", "v2" + "row 4", "v3" + "row 5", "v4" + "row 6", "v5" + "row 7", "v6" + "row 8", "v7" + "row 9", "v8" + "row 10", "v9" + "row 11", "v10" + "row 12", "v11" + + .. csv-table:: mat4x3 **(dest)** + :header: "", "column 1", "column 2", "column 3", "column 4" + + "row 1", "v0", "v3", "v6", "v9" + "row 2", "v1", "v4", "v7", "v10" + "row 3", "v2", "v5", "v8", "v11" + +.. c:function:: void glm_mat4x3_mul(mat4x3 m1, mat3x4 m2, mat3 dest) + + Multiply mat4x3 (m1) by mat3x4 (m2) and store in mat3 (dest). + + .. code-block:: c + + glm_mat4x3_mul(mat4x3, mat3x4, mat3); + + Parameters: + | *[in]* **m1** mat4x3 (left) + | *[in]* **m2** mat3x4 (right) + | *[out]* **dest** destination (result, mat3) + + .. csv-table:: mat4x3 **(m1)** + :header: "", "column 1", "column 2", "column 3", "column 4" + + "row 1", "a00", "a10", "a20", "a30" + "row 2", "a01", "a11", "a21", "a31" + "row 3", "a02", "a12", "a22", "a32" + + .. csv-table:: mat3x4 **(m2)** :header: "", "column 1", "column 2", "column 3" "row 1", "b00", "b10", "b20" @@ -89,7 +140,7 @@ Functions documentation "row 3", "b02", "b12", "b22" "row 4", "b03", "b13", "b23" - .. csv-table:: mat3x3 + .. csv-table:: mat3x3 **(dest)** :header: "", "column 1", "column 2", "column 3" "row 1", "a00 * b00 + a10 * b01 + a20 * b02 + a30 * b03", "a00 * b10 + a10 * b11 + a20 * b12 + a30 * b13", "a00 * b20 + a10 * b21 + a20 * b22 + a30 * b23" @@ -98,21 +149,21 @@ Functions documentation .. c:function:: void glm_mat4x3_mulv(mat4x3 m, vec4 v, vec3 dest) - multiply mat4x3 with vec4 (column vector) and store in dest column vector + Multiply mat4x3 (m) by vec4 (v) and store in vec3 (dest). Parameters: - | *[in]* **m** mat4x3 (left) - | *[in]* **v** vec4 (right, column vector) - | *[out]* **dest** destination (result, column vector) + | *[in]* **m** mat4x3 (left) + | *[in]* **v** vec4 (right, column vector) + | *[out]* **dest** destination (result, column vector) - .. csv-table:: mat4x3 + .. csv-table:: mat4x3 **(m)** :header: "", "column 1", "column 2", "column 3", "column 4" "row 1", "m00", "m10", "m20", "m30" "row 2", "m01", "m11", "m21", "m31" "row 3", "m02", "m12", "m22", "m32" - .. csv-table:: column vec4 (1x4) + .. csv-table:: column vec4 (1x4) **(v)** :header: "", "column 1" "row 1", "v0" @@ -120,25 +171,47 @@ Functions documentation "row 3", "v2" "row 4", "v3" - .. csv-table:: column vec3 (1x3) + .. csv-table:: column vec3 (1x3) **(dest)** :header: "", "column 1" "row 1", "m00 * v0 + m10 * v1 + m20 * v2 + m30 * v3" "row 2", "m01 * v0 + m11 * v1 + m21 * v2 + m31 * v3" "row 3", "m02 * v0 + m12 * v1 + m22 * v2 + m32 * v3" -.. c:function:: void glm_mat4x3_transpose(mat4x3 m, mat3x4 dest) +.. c:function:: void glm_mat4x3_transpose(mat4x3 src, mat3x4 dest) - transpose matrix and store in dest + Transpose mat4x3 (src) and store in mat3x4 (dest). Parameters: - | *[in]* **m** matrix - | *[out]* **dest** destination + | *[in]* **src** mat4x3 (left) + | *[out]* **dest** destination (result, mat3x4) -.. c:function:: void glm_mat4x3_scale(mat4x3 m, float s) + .. csv-table:: mat4x3 **(src)** + :header: "", "column 1", "column 2", "column 3", "column 4" - multiply matrix with scalar + "row 1", "a00", "a10", "a20", "a30" + "row 2", "a01", "a11", "a21", "a31" + "row 3", "a02", "a12", "a22", "a32" + + .. csv-table:: mat3x4 **(dest)** + :header: "", "column 1", "column 2", "column 3" + + "row 1", "b00 = a00", "b10 = a01", "b20 = a02" + "row 2", "b01 = a10", "b11 = a11", "b21 = a12" + "row 3", "b02 = a20", "b12 = a21", "b22 = a22" + "row 4", "b03 = a30", "b13 = a31", "b23 = a32" + +.. c:function:: void glm_mat4x3_scale(mat4x3 m, float s) + + Multiply mat4x3 (m) by scalar constant (s). Parameters: - | *[in, out]* **m** matrix - | *[in]* **s** scalar + | *[in, out]* **m** mat4x3 (src, dest) + | *[in]* **s** float (scalar) + + .. csv-table:: mat4x3 **(m)** + :header: "", "column 1", "column 2", "column 3", "column 4" + + "row 1", "m00 = m00 * s", "m10 = m10 * s", "m20 = m20 * s", "m30 = m30 * s" + "row 2", "m01 = m01 * s", "m11 = m11 * s", "m21 = m21 * s", "m31 = m31 * s" + "row 3", "m02 = m02 * s", "m12 = m12 * s", "m22 = m22 * s", "m32 = m32 * s" diff --git a/include/cglm/call/mat4x3.h b/include/cglm/call/mat4x3.h index bb5c0a8..e06e102 100644 --- a/include/cglm/call/mat4x3.h +++ b/include/cglm/call/mat4x3.h @@ -15,11 +15,11 @@ extern "C" { CGLM_EXPORT void -glmc_mat4x3_copy(mat4x3 mat, mat4x3 dest); +glmc_mat4x3_copy(mat4x3 src, mat4x3 dest); CGLM_EXPORT void -glmc_mat4x3_zero(mat4x3 mat); +glmc_mat4x3_zero(mat4x3 m); CGLM_EXPORT void @@ -35,7 +35,7 @@ glmc_mat4x3_mulv(mat4x3 m, vec4 v, vec3 dest); CGLM_EXPORT void -glmc_mat4x3_transpose(mat4x3 m, mat3x4 dest); +glmc_mat4x3_transpose(mat4x3 src, mat3x4 dest); CGLM_EXPORT void diff --git a/include/cglm/mat4x3.h b/include/cglm/mat4x3.h index 2ef05c1..a429437 100644 --- a/include/cglm/mat4x3.h +++ b/include/cglm/mat4x3.h @@ -11,12 +11,12 @@ GLM_MAT4X3_ZERO Functions: - CGLM_INLINE void glm_mat4x3_copy(mat4x3 mat, mat4x3 dest); - CGLM_INLINE void glm_mat4x3_zero(mat4x3 mat); + CGLM_INLINE void glm_mat4x3_copy(mat4x3 src, mat4x3 dest); + CGLM_INLINE void glm_mat4x3_zero(mat4x3 m); CGLM_INLINE void glm_mat4x3_make(const float * __restrict src, mat4x3 dest); CGLM_INLINE void glm_mat4x3_mul(mat4x3 m1, mat3x4 m2, mat3 dest); CGLM_INLINE void glm_mat4x3_mulv(mat4x3 m, vec4 v, vec3 dest); - CGLM_INLINE void glm_mat4x3_transpose(mat4x3 m, mat3x4 dest); + CGLM_INLINE void glm_mat4x3_transpose(mat4x3 src, mat3x4 dest); CGLM_INLINE void glm_mat4x3_scale(mat4x3 m, float s); */ @@ -32,48 +32,37 @@ #define GLM_MAT4X3_ZERO GLM_MAT4X3_ZERO_INIT /*! - * @brief copy all members of [mat] to [dest] + * @brief Copy mat4x3 (src) to mat4x3 (dest). * - * @param[in] mat source - * @param[out] dest destination + * @param[in] src mat4x3 (left) + * @param[out] dest destination (result, mat4x3) */ CGLM_INLINE void -glm_mat4x3_copy(mat4x3 mat, mat4x3 dest) { - dest[0][0] = mat[0][0]; - dest[0][1] = mat[0][1]; - dest[0][2] = mat[0][2]; - - dest[1][0] = mat[1][0]; - dest[1][1] = mat[1][1]; - dest[1][2] = mat[1][2]; - - dest[2][0] = mat[2][0]; - dest[2][1] = mat[2][1]; - dest[2][2] = mat[2][2]; - - dest[3][0] = mat[3][0]; - dest[3][1] = mat[3][1]; - dest[3][2] = mat[3][2]; +glm_mat4x3_copy(mat4x3 src, mat4x3 dest) { + glm_vec3_copy(src[0], dest[0]); + glm_vec3_copy(src[1], dest[1]); + glm_vec3_copy(src[2], dest[2]); + glm_vec3_copy(src[3], dest[3]); } /*! - * @brief make given matrix zero. + * @brief Zero out the mat4x3 (m). * - * @param[in, out] mat matrix + * @param[in, out] mat4x3 (src, dest) */ CGLM_INLINE void -glm_mat4x3_zero(mat4x3 mat) { +glm_mat4x3_zero(mat4x3 m) { CGLM_ALIGN_MAT mat4x3 t = GLM_MAT4X3_ZERO_INIT; - glm_mat4x3_copy(t, mat); + glm_mat4x3_copy(t, m); } /*! - * @brief Create mat4x3 matrix from pointer + * @brief Create mat4x3 (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, mat4x3) */ CGLM_INLINE void @@ -96,15 +85,15 @@ glm_mat4x3_make(const float * __restrict src, mat4x3 dest) { } /*! - * @brief multiply m1 and m2 to dest + * @brief Multiply mat4x3 (m1) by mat3x4 (m2) and store in mat3 (dest). * * @code * glm_mat4x3_mul(mat4x3, mat3x4, mat3); * @endcode * - * @param[in] m1 left matrix (mat4x3) - * @param[in] m2 right matrix (mat3x4) - * @param[out] dest destination matrix (mat3) + * @param[in] m1 mat4x3 (left) + * @param[in] m2 mat3x4 (right) + * @param[out] dest destination (result, mat3) */ CGLM_INLINE void @@ -132,11 +121,11 @@ glm_mat4x3_mul(mat4x3 m1, mat3x4 m2, mat3 dest) { } /*! - * @brief multiply matrix with column vector and store in dest column vector + * @brief Multiply mat4x3 (m) by vec4 (v) and store in vec3 (dest). * - * @param[in] m matrix (left) - * @param[in] v vector (right, column vector) - * @param[out] dest result vector + * @param[in] m mat4x3 (left) + * @param[in] v vec3 (right, column vector) + * @param[out] dest destination (result, column vector) */ CGLM_INLINE void @@ -149,37 +138,24 @@ glm_mat4x3_mulv(mat4x3 m, vec4 v, vec3 dest) { } /*! - * @brief transpose matrix and store in dest + * @brief Transpose mat4x3 (src) and store in mat3x4 (dest). * - * @param[in] m matrix - * @param[out] dest result + * @param[in] src mat4x3 (left) + * @param[out] dest destination (result, mat3x4) */ CGLM_INLINE void -glm_mat4x3_transpose(mat4x3 m, mat3x4 dest) { - dest[0][0] = m[0][0]; - dest[0][1] = m[1][0]; - dest[0][2] = m[2][0]; - dest[0][3] = m[3][0]; - - dest[1][0] = m[0][1]; - dest[1][1] = m[1][1]; - dest[1][2] = m[2][1]; - dest[1][3] = m[3][1]; - - dest[2][0] = m[0][2]; - dest[2][1] = m[1][2]; - dest[2][2] = m[2][2]; - dest[2][3] = m[3][2]; +glm_mat4x3_transpose(mat4x3 src, mat3x4 dest) { + dest[0][0] = src[0][0]; dest[0][1] = src[1][0]; dest[0][2] = src[2][0]; dest[0][3] = src[3][0]; + dest[1][0] = src[0][1]; dest[1][1] = src[1][1]; dest[1][2] = src[2][1]; dest[1][3] = src[3][1]; + dest[2][0] = src[0][2]; dest[2][1] = src[1][2]; dest[2][2] = src[2][2]; dest[2][3] = src[3][2]; } /*! - * @brief scale (multiply with scalar) matrix + * @brief Multiply mat4x3 (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 @@ -189,4 +165,4 @@ glm_mat4x3_scale(mat4x3 m, float s) { m[2][2] *= s; m[3][0] *= s; m[3][1] *= s; m[3][2] *= s; } -#endif +#endif /* cglm_mat4x3_h */ diff --git a/include/cglm/struct/mat4x3.h b/include/cglm/struct/mat4x3.h index 37a68e1..b398f98 100644 --- a/include/cglm/struct/mat4x3.h +++ b/include/cglm/struct/mat4x3.h @@ -35,87 +35,85 @@ #define GLMS_MAT4X3_ZERO ((mat4x3s)GLMS_MAT4X3_ZERO_INIT) /*! - * @brief make given matrix zero. + * @brief Zero out the mat4x3s (dest). * - * @param[in, out] mat matrix + * @return[out] dest constructed mat4x3s from raw pointer */ CGLM_INLINE mat4x3s glms_mat4x3_(zero)(void) { - mat4x3s r; - glm_mat4x3_zero(r.raw); - return r; + mat4x3s dest; + glm_mat4x3_zero(dest.raw); + return dest; } /*! - * @brief Create mat4x3 matrix from pointer + * @brief Create mat4x3s (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 mat4x3s from raw pointer */ CGLM_INLINE mat4x3s glms_mat4x3_(make)(const float * __restrict src) { - mat4x3s r; - glm_mat4x3_make(src, r.raw); - return r; + mat4x3s dest; + glm_mat4x3_make(src, dest.raw); + return dest; } /*! - * @brief multiply m1 and m2 to dest + * @brief Multiply mat4x3s (m1) by mat3x4s (m2) and store in mat3s (dest). * * @code * r = glms_mat4x3_mul(mat4x3s, mat3x4s); * @endcode * - * @param[in] m1 left matrix (mat4x3s) - * @param[in] m2 right matrix (mat3x4s) - * @returns destination matrix (mat3s) + * @param[in] m1 mat4x3s (left) + * @param[in] m2 mat3x4s (right) + * @return[out] dest constructed mat3s from raw pointers */ CGLM_INLINE mat3s glms_mat4x3_(mul)(mat4x3s m1, mat3x4s m2) { - mat3s r; - glm_mat4x3_mul(m1.raw, m2.raw, r.raw); - return r; + mat3s dest; + glm_mat4x3_mul(m1.raw, m2.raw, dest.raw); + return dest; } /*! - * @brief multiply matrix with column vector and store in dest vector + * @brief Multiply mat4x3s (m) by vec4s (v) and store in vec3s (dest). * - * @param[in] m matrix (left) - * @param[in] v vector (right, column vector) - * @returns destination vector (vec3s) + * @param[in] m mat4x3s (left) + * @param[in] v vec4s (right, column vector) + * @return[out] dest constructed vec3s from raw pointers */ CGLM_INLINE vec3s glms_mat4x3_(mulv)(mat4x3s m, vec4s v) { - vec3s r; - glm_mat4x3_mulv(m.raw, v.raw, r.raw); - return r; + vec3s dest; + glm_mat4x3_mulv(m.raw, v.raw, dest.raw); + return dest; } /*! - * @brief transpose matrix and store in dest + * @brief Transpose mat4x3s (m) and store in mat3x4s (dest). * - * @param[in] m matrix - * @param[out] dest result + * @param[in] m mat4x3s (left) + * @return[out] dest constructed mat3x4s from raw pointers */ CGLM_INLINE mat3x4s glms_mat4x3_(transpose)(mat4x3s m) { - mat3x4s r; - glm_mat4x3_transpose(m.raw, r.raw); - return r; + mat3x4s dest; + glm_mat4x3_transpose(m.raw, dest.raw); + return dest; } /*! - * @brief scale (multiply with scalar) matrix + * @brief Multiply mat4x3s (m) by scalar constant (s). * - * multiply matrix with scalar - * - * @param[in, out] m matrix - * @param[in] s scalar + * @param[in, out] m mat4x3s (src, dest) + * @param[in] s float (scalar) */ CGLM_INLINE mat4x3s diff --git a/src/mat4x3.c b/src/mat4x3.c index 8285424..b399c15 100644 --- a/src/mat4x3.c +++ b/src/mat4x3.c @@ -10,14 +10,14 @@ CGLM_EXPORT void -glmc_mat4x3_copy(mat4x3 mat, mat4x3 dest) { - glm_mat4x3_copy(mat, dest); +glmc_mat4x3_copy(mat4x3 src, mat4x3 dest) { + glm_mat4x3_copy(src, dest); } CGLM_EXPORT void -glmc_mat4x3_zero(mat4x3 mat) { - glm_mat4x3_zero(mat); +glmc_mat4x3_zero(mat4x3 m) { + glm_mat4x3_zero(m); } CGLM_EXPORT @@ -40,8 +40,8 @@ glmc_mat4x3_mulv(mat4x3 m, vec4 v, vec3 dest) { CGLM_EXPORT void -glmc_mat4x3_transpose(mat4x3 m, mat3x4 dest) { - glm_mat4x3_transpose(m, dest); +glmc_mat4x3_transpose(mat4x3 src, mat3x4 dest) { + glm_mat4x3_transpose(src, dest); } CGLM_EXPORT