From b694c9720472d812155a2e7e0c75bd4c4c5cff26 Mon Sep 17 00:00:00 2001 From: Vincent Davis Jr Date: Wed, 2 Apr 2025 18:29:22 -0400 Subject: [PATCH] mat2x4: add tables to docs & fix comments Signed-off-by: Vincent Davis Jr --- docs/source/mat2x4.rst | 176 +++++++++++++++++++++++++---------- include/cglm/call/mat2x4.h | 6 +- include/cglm/mat2x4.h | 72 +++++++------- include/cglm/struct/mat2x4.h | 70 +++++++------- src/mat2x4.c | 12 +-- 5 files changed, 203 insertions(+), 133 deletions(-) diff --git a/docs/source/mat2x4.rst b/docs/source/mat2x4.rst index 0acc643..8e825f6 100644 --- a/docs/source/mat2x4.rst +++ b/docs/source/mat2x4.rst @@ -37,45 +37,15 @@ Represented Functions documentation ~~~~~~~~~~~~~~~~~~~~~~~ -.. c:function:: void glm_mat2x4_copy(mat2x4 mat, mat2x4 dest) +.. c:function:: void glm_mat2x4_copy(mat2x4 src, mat2x4 dest) - copy mat2x4 to another one (dest). + Copy mat2x4 (src) to mat2x4 (dest). Parameters: - | *[in]* **mat** source - | *[out]* **dest** destination + | *[in]* **src** mat2x4 (left) + | *[out]* **dest** destination (result, mat2x4) -.. c:function:: void glm_mat2x4_zero(mat2x4 mat) - - make given matrix zero - - Parameters: - | *[in,out]* **mat** matrix - -.. c:function:: void glm_mat2x4_make(const float * __restrict src, mat2x4 dest) - - Create mat2x4 matrix from pointer - - .. note:: **@src** must contain at least 8 elements. - - Parameters: - | *[in]* **src** pointer to an array of floats - | *[out]* **dest** destination matrix2x4 - -.. c:function:: void glm_mat2x4_mul(mat2x4 m1, mat4x2 m2, mat4 dest) - - multiply m1 and m2 to dest - - .. code-block:: c - - glm_mat2x4_mul(mat2x4, mat4x2, mat4); - - Parameters: - | *[in]* **m1** left matrix (mat2x4) - | *[in]* **m2** right matrix (mat4x2) - | *[out]* **dest** destination matrix (mat4) - - .. csv-table:: mat2x4 + .. csv-table:: mat2x4 **(src)** :header: "", "column 1", "column 2" "row 1", "a00", "a10" @@ -83,13 +53,95 @@ Functions documentation "row 3", "a02", "a12" "row 4", "a03", "a13" - .. csv-table:: mat4x2 + .. csv-table:: mat2x4 **(dest)** + :header: "", "column 1", "column 2" + + "row 1", "b00 = a00", "b10 = a10" + "row 2", "b01 = a01", "b11 = a11" + "row 3", "b02 = a02", "b12 = a12" + "row 4", "b03 = a03", "b13 = a13" + +.. c:function:: void glm_mat2x4_zero(mat2x4 m) + + Zero out the mat2x4 (m). + + Parameters: + | *[in, out]* **m** mat2x4 (src, dest) + + .. csv-table:: mat2x4 **(m)** + :header: "", "column 1", "column 2" + + "row 1", "0.00", "2.00" + "row 2", "5.00", "4.00" + "row 3", "7.00", "6.00" + "row 4", "23.00", "1.00" + + .. csv-table:: mat2x4 **(m)** + :header: "", "column 1", "column 2" + + "row 1", "0.00", "0.00" + "row 2", "0.00", "0.00" + "row 3", "0.00", "0.00" + "row 4", "0.00", "0.00" + +.. c:function:: void glm_mat2x4_make(const float * __restrict src, mat2x4 dest) + + Create mat2x4 (dest) from pointer (src). + + .. note:: **@src** must contain at least 8 elements. + + Parameters: + | *[in]* **src** pointer to an array of floats (left) + | *[out]* **dest** destination (result, mat2x4) + + .. csv-table:: float array (1x8) **(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" + + .. csv-table:: mat2x4 **(dest)** + :header: "", "column 1", "column 2" + + "row 1", "v0", "v4" + "row 2", "v1", "v5" + "row 3", "v2", "v6" + "row 4", "v3", "v7" + +.. c:function:: void glm_mat2x4_mul(mat2x4 m1, mat4x2 m2, mat4 dest) + + Multiply mat2x4 (m1) by mat4x2 (m2) and store in mat4 (dest). + + .. code-block:: c + + glm_mat2x4_mul(mat2x4, mat4x2, mat4); + + Parameters: + | *[in]* **m1** mat2x4 (left) + | *[in]* **m2** mat4x2 (right) + | *[out]* **dest** destination (result, mat4) + + .. csv-table:: mat2x4 **(m1)** + :header: "", "column 1", "column 2" + + "row 1", "a00", "a10" + "row 2", "a01", "a11" + "row 3", "a02", "a12" + "row 4", "a03", "a13" + + .. csv-table:: mat4x2 **(m2)** :header: "", "column 1", "column 2", "column 3", "column 4" "row 1", "b00", "b10", "b20", "b30" "row 2", "b01", "b11", "b21", "b31" - .. csv-table:: mat4x4 + .. csv-table:: mat4x4 **(dest)** :header: "", "column 1", "column 2", "column 3", "column 4" "row 1", "a00 * b00 + a10 * b01", "a00 * b10 + a10 * b11", "a00 * b20 + a10 * b21", "a00 * b30 + a10 * b31" @@ -99,14 +151,14 @@ Functions documentation .. c:function:: void glm_mat2x4_mulv(mat2x4 m, vec2 v, vec4 dest) - multiply mat2x4 with vec2 (column vector) and store in dest column vector + Multiply mat2x4 (m) by vec2 (v) and store in vec4 (dest). Parameters: - | *[in]* **m** mat2x4 (left) - | *[in]* **v** vec2 (right, column vector) - | *[out]* **dest** destination (result, column vector) + | *[in]* **m** mat2x4 (left) + | *[in]* **v** vec2 (right, column vector) + | *[out]* **dest** destination (result, column vector) - .. csv-table:: mat2x4 + .. csv-table:: mat2x4 **(m)** :header: "", "column 1", "column 2" "row 1", "m00", "m10" @@ -114,13 +166,13 @@ Functions documentation "row 3", "m02", "m12" "row 4", "m03", "m13" - .. csv-table:: column vec2 (1x2) + .. csv-table:: column vec2 (1x2) **(v)** :header: "", "column 1" "row 1", "v0" "row 2", "v1" - .. csv-table:: column vec4 (1x4) + .. csv-table:: column vec4 (1x4) **(dest)** :header: "", "column 1" "row 1", "m00 * v0 + m10 * v1" @@ -128,18 +180,40 @@ Functions documentation "row 3", "m02 * v0 + m12 * v1" "row 4", "m03 * v0 + m13 * v1" -.. c:function:: void glm_mat2x4_transpose(mat2x4 m, mat4x2 dest) +.. c:function:: void glm_mat2x4_transpose(mat2x4 src, mat4x2 dest) - transpose matrix and store in dest + Transpose mat2x4 (src) and store in mat4x2 (dest). Parameters: - | *[in]* **m** matrix - | *[out]* **dest** destination + | *[in]* **src** mat2x4 (left) + | *[out]* **dest** destination (result, mat4x2) + + .. csv-table:: mat2x4 **(src)** + :header: "", "column 1", "column 2" + + "row 1", "a00", "a10" + "row 2", "a01", "a11" + "row 3", "a02", "a12" + "row 4", "a03", "a13" + + .. csv-table:: mat4x2 **(dest)** + :header: "", "column 1", "column 2", "column 3", "column 4" + + "row 1", "b00 = a00", "b10 = a01", "b20 = a02", "b30 = a03" + "row 2", "b01 = a10", "b11 = a11", "b21 = a12", "b31 = a13" .. c:function:: void glm_mat2x4_scale(mat2x4 m, float s) - multiply matrix with scalar + Multiply mat2x4 (m) by scalar constant (s). Parameters: - | *[in, out]* **m** matrix - | *[in]* **s** scalar + | *[in, out]* **m** mat2x4 (src, dest) + | *[in]* **s** float (scalar) + + .. csv-table:: mat2x4 **(m)** + :header: "", "column 1", "column 2" + + "row 1", "m00 = m00 * s", "m10 = m10 * s" + "row 2", "m01 = m01 * s", "m11 = m11 * s" + "row 3", "m02 = m02 * s", "m12 = m12 * s" + "row 4", "m03 = m03 * s", "m13 = m13 * s" diff --git a/include/cglm/call/mat2x4.h b/include/cglm/call/mat2x4.h index 84e805b..e2775a4 100644 --- a/include/cglm/call/mat2x4.h +++ b/include/cglm/call/mat2x4.h @@ -15,11 +15,11 @@ extern "C" { CGLM_EXPORT void -glmc_mat2x4_copy(mat2x4 mat, mat2x4 dest); +glmc_mat2x4_copy(mat2x4 src, mat2x4 dest); CGLM_EXPORT void -glmc_mat2x4_zero(mat2x4 mat); +glmc_mat2x4_zero(mat2x4 m); CGLM_EXPORT void @@ -35,7 +35,7 @@ glmc_mat2x4_mulv(mat2x4 m, vec2 v, vec4 dest); CGLM_EXPORT void -glmc_mat2x4_transpose(mat2x4 m, mat4x2 dest); +glmc_mat2x4_transpose(mat2x4 src, mat4x2 dest); CGLM_EXPORT void diff --git a/include/cglm/mat2x4.h b/include/cglm/mat2x4.h index e5c1281..fa9adf3 100644 --- a/include/cglm/mat2x4.h +++ b/include/cglm/mat2x4.h @@ -11,12 +11,12 @@ GLM_MAT2X4_ZERO Functions: - CGLM_INLINE void glm_mat2x4_copy(mat2x4 mat, mat2x4 dest); - CGLM_INLINE void glm_mat2x4_zero(mat2x4 mat); + CGLM_INLINE void glm_mat2x4_copy(mat2x4 src, mat2x4 dest); + CGLM_INLINE void glm_mat2x4_zero(mat2x4 m); CGLM_INLINE void glm_mat2x4_make(const float * __restrict src, mat2x4 dest); CGLM_INLINE void glm_mat2x4_mul(mat2x4 m1, mat4x2 m2, mat4 dest); CGLM_INLINE void glm_mat2x4_mulv(mat2x4 m, vec2 v, vec4 dest); - CGLM_INLINE void glm_mat2x4_transpose(mat2x4 m, mat4x2 dest); + CGLM_INLINE void glm_mat2x4_transpose(mat2x4 src, mat4x2 dest); CGLM_INLINE void glm_mat2x4_scale(mat2x4 m, float s); */ @@ -32,35 +32,35 @@ #define GLM_MAT2X4_ZERO GLM_MAT2X4_ZERO_INIT /*! - * @brief copy all members of [mat] to [dest] + * @brief Copy mat2x4 (src) to mat2x4 (dest). * - * @param[in] mat source - * @param[out] dest destination + * @param[in] src mat2x4 (left) + * @param[out] dest destination (result, mat2x4) */ CGLM_INLINE void -glm_mat2x4_copy(mat2x4 mat, mat2x4 dest) { - glm_vec4_ucopy(mat[0], dest[0]); - glm_vec4_ucopy(mat[1], dest[1]); +glm_mat2x4_copy(mat2x4 src, mat2x4 dest) { + glm_vec4_ucopy(src[0], dest[0]); + glm_vec4_ucopy(src[1], dest[1]); } /*! - * @brief make given matrix zero. + * @brief Zero out the mat2x4 (m). * - * @param[in, out] mat matrix + * @param[in, out] mat2x4 (src, dest) */ CGLM_INLINE void -glm_mat2x4_zero(mat2x4 mat) { +glm_mat2x4_zero(mat2x4 m) { CGLM_ALIGN_MAT mat2x4 t = GLM_MAT2X4_ZERO_INIT; - glm_mat2x4_copy(t, mat); + glm_mat2x4_copy(t, m); } /*! - * @brief Create mat2x4 matrix from pointer + * @brief Create mat2x4 (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, mat2x4) */ CGLM_INLINE void @@ -77,15 +77,15 @@ glm_mat2x4_make(const float * __restrict src, mat2x4 dest) { } /*! - * @brief multiply m1 and m2 to dest + * @brief Multiply mat2x4 (m1) by mat4x2 (m2) and store in mat4 (dest). * * @code * glm_mat2x4_mul(mat2x4, mat4x2, mat4); * @endcode * - * @param[in] m1 left matrix (mat2x4) - * @param[in] m2 right matrix (mat4x2) - * @param[out] dest destination matrix (mat4) + * @param[in] m1 mat2x4 (left) + * @param[in] m2 mat4x2 (right) + * @param[out] dest destination (result, mat4) */ CGLM_INLINE void @@ -120,11 +120,11 @@ glm_mat2x4_mul(mat2x4 m1, mat4x2 m2, mat4 dest) { } /*! - * @brief multiply matrix with column vector and store in dest column vector + * @brief Multiply mat2x4 (m) by vec2 (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 mat2x4 (left) + * @param[in] v vec2 (right, column vector) + * @param[out] dest destination (result, column vector) */ CGLM_INLINE void @@ -138,27 +138,25 @@ glm_mat2x4_mulv(mat2x4 m, vec2 v, vec4 dest) { } /*! - * @brief transpose matrix and store in dest + * @brief Transpose mat2x4 (src) and store in mat4x2 (dest). * - * @param[in] m matrix - * @param[out] dest result + * @param[in] src mat2x4 (left) + * @param[out] dest destination (result, mat4x2) */ CGLM_INLINE void -glm_mat2x4_transpose(mat2x4 m, mat4x2 dest) { - dest[0][0] = m[0][0]; dest[0][1] = m[1][0]; - dest[1][0] = m[0][1]; dest[1][1] = m[1][1]; - dest[2][0] = m[0][2]; dest[2][1] = m[1][2]; - dest[3][0] = m[0][3]; dest[3][1] = m[1][3]; +glm_mat2x4_transpose(mat2x4 src, mat4x2 dest) { + dest[0][0] = src[0][0]; dest[0][1] = src[1][0]; + dest[1][0] = src[0][1]; dest[1][1] = src[1][1]; + dest[2][0] = src[0][2]; dest[2][1] = src[1][2]; + dest[3][0] = src[0][3]; dest[3][1] = src[1][3]; } /*! - * @brief scale (multiply with scalar) matrix + * @brief Multiply mat2x4 (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 diff --git a/include/cglm/struct/mat2x4.h b/include/cglm/struct/mat2x4.h index afeedc1..7e3e75a 100644 --- a/include/cglm/struct/mat2x4.h +++ b/include/cglm/struct/mat2x4.h @@ -35,87 +35,85 @@ #define GLMS_MAT2X4_ZERO ((mat2x4s)GLMS_MAT2X4_ZERO_INIT) /*! - * @brief make given matrix zero. + * @brief Zero out the mat2x4s (dest). * - * @param[in, out] mat matrix + * @return[out] dest constructed mat2x4s from raw pointer */ CGLM_INLINE mat2x4s glms_mat2x4_(zero)(void) { - mat2x4s r; - glm_mat2x4_zero(r.raw); - return r; + mat2x4s dest; + glm_mat2x4_zero(dest.raw); + return dest; } /*! - * @brief Create mat2x4 matrix from pointer + * @brief Create mat2x4s (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 mat2x4s from raw pointer */ CGLM_INLINE mat2x4s glms_mat2x4_(make)(const float * __restrict src) { - mat2x4s r; - glm_mat2x4_make(src, r.raw); - return r; + mat2x4s dest; + glm_mat2x4_make(src, dest.raw); + return dest; } /*! - * @brief multiply m1 and m2 to dest + * @brief Multiply mat2x4s (m1) by mat4x2s (m2) and store in mat4s (dest). * * @code * r = glms_mat2x4_mul(mat2x4s, mat4x2s); * @endcode * - * @param[in] m1 left matrix (mat2x4s) - * @param[in] m2 right matrix (mat4x2s) - * @returns destination matrix (mat2s) + * @param[in] m1 mat2x4s (left) + * @param[in] m2 mat4x2s (right) + * @return[out] dest constructed mat4s from raw pointers */ CGLM_INLINE mat4s glms_mat2x4_(mul)(mat2x4s m1, mat4x2s m2) { - mat4s r; - glm_mat2x4_mul(m1.raw, m2.raw, r.raw); - return r; + mat4s dest; + glm_mat2x4_mul(m1.raw, m2.raw, dest.raw); + return dest; } /*! - * @brief multiply matrix with column vector and store in dest column vector + * @brief Multiply mat2x4s (m) by vec2s (v) and store in vec4s (dest). * - * @param[in] m matrix (left) - * @param[in] v vector (right, column vector) - * @param[out] dest result vector + * @param[in] m mat2x4s (left) + * @param[in] v vec2s (right, column vector) + * @return[out] dest constructed vec4s from raw pointers */ CGLM_INLINE vec4s glms_mat2x4_(mulv)(mat2x4s m, vec2s v) { - vec4s r; - glm_mat2x4_mulv(m.raw, v.raw, r.raw); - return r; + vec4s dest; + glm_mat2x4_mulv(m.raw, v.raw, dest.raw); + return dest; } /*! - * @brief transpose matrix and store in dest + * @brief Transpose mat2x4s (m) and store in mat4x2s (dest). * - * @param[in] m matrix - * @param[out] dest result + * @param[in] m mat2x4s (left) + * @return[out] dest constructed mat4x2s from raw pointers */ CGLM_INLINE mat4x2s glms_mat2x4_(transpose)(mat2x4s m) { - mat4x2s r; - glm_mat2x4_transpose(m.raw, r.raw); - return r; + mat4x2s dest; + glm_mat2x4_transpose(m.raw, dest.raw); + return dest; } /*! - * @brief scale (multiply with scalar) matrix + * @brief Multiply mat2x4s (m) by scalar constant (s). * - * multiply matrix with scalar - * - * @param[in, out] m matrix - * @param[in] s scalar + * @param[in, out] m mat2x4s (src, dest) + * @param[in] s float (scalar) */ CGLM_INLINE mat2x4s diff --git a/src/mat2x4.c b/src/mat2x4.c index a221ed3..ca13171 100644 --- a/src/mat2x4.c +++ b/src/mat2x4.c @@ -10,14 +10,14 @@ CGLM_EXPORT void -glmc_mat2x4_copy(mat2x4 mat, mat2x4 dest) { - glm_mat2x4_copy(mat, dest); +glmc_mat2x4_copy(mat2x4 src, mat2x4 dest) { + glm_mat2x4_copy(src, dest); } CGLM_EXPORT void -glmc_mat2x4_zero(mat2x4 mat) { - glm_mat2x4_zero(mat); +glmc_mat2x4_zero(mat2x4 m) { + glm_mat2x4_zero(m); } CGLM_EXPORT @@ -40,8 +40,8 @@ glmc_mat2x4_mulv(mat2x4 m, vec2 v, vec4 dest) { CGLM_EXPORT void -glmc_mat2x4_transpose(mat2x4 m, mat4x2 dest) { - glm_mat2x4_transpose(m, dest); +glmc_mat2x4_transpose(mat2x4 src, mat4x2 dest) { + glm_mat2x4_transpose(src, dest); } CGLM_EXPORT