From 0d2ebbb7416c2d14806b0b2f6250a143c5780b28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20GUEZO?= Date: Fri, 21 Mar 2025 08:44:50 +0100 Subject: [PATCH] docs: rework docs --- include/math/vector.h | 4 +- include/math/vector3.h | 142 +++++++++++++++-------------------------- include/math/vector4.h | 119 +++++++++++++--------------------- 3 files changed, 98 insertions(+), 167 deletions(-) diff --git a/include/math/vector.h b/include/math/vector.h index f59a029..171c79a 100644 --- a/include/math/vector.h +++ b/include/math/vector.h @@ -11,7 +11,7 @@ * the first three components of the 4D vector (x, y, z). * Returns NULL if the input vector is NULL or allocation fails. */ -Vec3* Vec4ToVec3(Vec4* v); +Vec3 Vec4ToVec3(Vec4 v); /** * @brief Converts a 3D vector to a 4D vector. @@ -21,6 +21,6 @@ Vec3* Vec4ToVec3(Vec4* v); * a default w component (1.0 for position, 0.0 for direction). * Returns NULL if the input vector is NULL or allocation fails. */ -Vec4* Vec3ToVec4(Vec3* v); +Vec4 Vec3ToVec4(Vec3 v); #endif // VECTOR_H \ No newline at end of file diff --git a/include/math/vector3.h b/include/math/vector3.h index a3d4d8b..74da70a 100644 --- a/include/math/vector3.h +++ b/include/math/vector3.h @@ -10,159 +10,121 @@ typedef struct { * @param x X-axis coordinate. * @param y Y-axis coordinate. * @param z Z-axis coordinate. - * @return A pointer to the newly allocated 3D vector if - * successful, or NULL if the allocation fails. + * @return A 3D vector with the specified coordinates. */ Vec3 vec3(float x, float y, float z); /** - * @brief Adds two 3D vectors in a new 3D vector. - * @param v1 First vector pointer. - * @param v2 Second vector pointer. - * @return A pointer to a newly allocated 3D vector - * representing the sum of v1 and v2. - * Returns NULL if the allocation fails. + * @brief Adds two 3D vectors and returns a new 3D vector. + * @param v1 First vector. + * @param v2 Second vector. + * @return A 3D vector representing the sum of v1 and v2. */ Vec3 vec3Add(Vec3 v1, Vec3 v2); /** - * @brief Subtracts two 3D vectors in a new 3D - * vector. - * @param v1 First vector pointer. - * @param v2 Second vector pointer. - * @return A pointer to a newly allocated 3D vector - * representing the subtraction of v1 and v2. - * Returns NULL if the allocation fails. + * @brief Subtracts two 3D vectors and returns a new 3D vector. + * @param v1 First vector. + * @param v2 Second vector. + * @return A 3D vector representing the result of v1 minus v2. */ Vec3 vec3Sub(Vec3 v1, Vec3 v2); /** - * @brief Scales a 3D vector by a constant scalar in a - * new 3D vector. - * @param v 3D vector pointer. - * @param scalar Constant. - * @return A pointer to a newly allocated 3D vector - * representing the multiplication of v1 and a - * scalar. Returns NULL if the allocation - * fails. + * @brief Scales a 3D vector by a constant scalar and returns a new 3D vector. + * @param v 3D vector. + * @param scalar Scalar value. + * @return A 3D vector representing the multiplication of v by the scalar. */ Vec3 vec3Scale(Vec3 v, float scalar); /** - * @brief Computes the dot product of two 3D vectors - * @param a First vector pointer. - * @param b Second vector pointer. - * @return The dot product of a and b as a scalar value. - * - scalar value > 0.f: Both vectors have the same orientation - * (the angle between them is acute). - * - scalar value = 0.f: Both vectors are orthogonal (the angle - * between them is 90 degrees). - * - scalar value < 0.f: Both vectors have opposite orientations - * (the angle between them is obtuse). - * Returns NAN if one of the input vectors are - * NULL. + * @brief Computes the dot product of two 3D vectors. + * @param a First vector. + * @param b Second vector. + * @return A scalar value representing the dot product of a and b. + * - scalar > 0: Both vectors have the same orientation (the angle between them is acute). + * - scalar = 0: Vectors are orthogonal (the angle between them is 90 degrees). + * - scalar < 0: Vectors have opposite orientations (the angle between them is obtuse). */ float vec3Dot(Vec3 a, Vec3 b); /** - * @brief Computes the Length (magnitude) of a 3D - * vector - * @param v 3D vector pointer. - * @return The length (magnitude) of the vector v as - * a scalar value. Returns NAN if input vector - * is NULL. + * @brief Computes the length (magnitude) of a 3D vector. + * @param v 3D vector. + * @return A scalar value representing the length (magnitude) of the vector v. */ float vec3Len(Vec3 v); /** - * @brief Normalizes the 3D vector. - * @param v Pointer to the 3D vector. - * @return A pointer to a newly allocated 3D vector that - * is normalized. Returns a zero vector (0, 0, 0) - * if the input vector is a zero vector. Returns - * NULL if the input pointer is invalid. + * @brief Normalizes a 3D vector (scales it to unit length). + * @param v 3D vector. + * @return A 3D vector representing the normalized version of v. + * Returns a zero vector (0, 0, 0) if the input vector is a zero vector. */ Vec3 vec3Norm(Vec3 v); /** - * @brief Performs linear interpolation between two 3D - * vectors to determine a new 3D vector. - * @param a Pointer to the first 3D vector (start vector). - * @param b Pointer to the second 3D vector (end vector). - * @param t Interpolation factor (0.0 to 1.0): + * @brief Performs linear interpolation between two 3D vectors. + * @param a Start vector. + * @param b End vector. + * @param t Interpolation factor (0.0 to 1.0). * - t = 0 returns the vector a. * - t = 1 returns the vector b. - * - t between 0 and 1 returns a point between - * a and b. - * @return A pointer to a newly allocated 3D vector - * representing the interpolated result between - * a and b. Returns NULL if any of the input vectors - * is NULL. + * - t between 0 and 1 returns a point between a and b. + * @return A 3D vector representing the interpolated result between a and b. */ Vec3 vec3Lerp(Vec3 a, Vec3 b, float t); /** * @brief Computes the cross product of two 3D vectors. - * The cross product produces a new vector that is - * orthogonal (perpendicular) to both input vectors. - * The direction of the resulting vector follows the - * right-hand rule. - * @param a Pointer to the first vector. - * @param b Pointer to the second vector. - * @return A pointer to a newly allocated 3D vector representing - * the cross product of vectors a and b. - * Returns NULL if the allocation fails. + * The cross product produces a new vector that is orthogonal (perpendicular) to both input vectors. + * The direction of the resulting vector follows the right-hand rule. + * @param a First vector. + * @param b Second vector. + * @return A 3D vector representing the cross product of vectors a and b. */ Vec3 vec3Cross(Vec3 a, Vec3 b); /** * @brief Computes the angle between two 3D vectors. - * @param a Pointer to the first vector. - * @param b Pointer to the second vector. - * @return The angle between a and b in radians. + * @param a First vector. + * @param b Second vector. + * @return The angle between vectors a and b in radians. */ float vec3Angle(Vec3 a, Vec3 b); /** * @brief Computes the projection of vector a onto vector b. - * @param a Pointer to the vector to be projected. - * @param b Pointer to the vector onto which a is projected. - * @return A pointer to a newly allocated 3D vector representing - * the projection of a onto b. - * Returns NULL if b is a zero vector. + * @param a The vector to be projected. + * @param b The vector onto which a is projected. + * @return A 3D vector representing the projection of a onto b. */ Vec3 vec3Proj(Vec3 a, Vec3 b); /** * @brief Computes the reflection of a vector v against a normal. - * @param v Pointer to the incident vector. - * @param normal Pointer to the normal vector of the surface. - * @return A pointer to a newly allocated 3D vector representing - * the reflection of v across normal. - * Returns NULL if normal is a zero vector. + * @param v The incident vector. + * @param normal The normal vector of the surface. + * @return A 3D vector representing the reflection of v across normal. */ Vec3 vec3Refl(Vec3 v, Vec3 normal); /** * @brief Computes the Euclidean distance between two 3D vectors. - * @param a Pointer to the first vector. - * @param b Pointer to the second vector. + * @param a The first vector. + * @param b The second vector. * @return The scalar distance between a and b. - * Returns NAN if either vector is NULL. */ float vec3Dist(Vec3 a, Vec3 b); /** * @brief Rotates a 3D vector around a given axis by a specified angle. - * @param v Pointer to the vector to rotate. - * @param axis Pointer to the rotation axis (must be normalized). + * @param v The vector to rotate. + * @param axis The rotation axis (must be normalized). * @param angle Rotation angle in radians. - * @return A pointer to a newly allocated 3D vector representing - * the rotated vector. - * Returns NULL if axis is a zero vector. + * @return A 3D vector representing the rotated vector. */ Vec3 vec3Rotate(Vec3 v, Vec3 axis, float angle); -void vec3Free(Vec3 v); - #endif // VEC3_H \ No newline at end of file diff --git a/include/math/vector4.h b/include/math/vector4.h index 8f33f25..92dee6b 100644 --- a/include/math/vector4.h +++ b/include/math/vector4.h @@ -11,133 +11,102 @@ typedef struct { * @param y Y-axis coordinate. * @param z Z-axis coordinate. * @param w W-axis coordinate. - * @return A pointer to the newly allocated 4D vector if - * successful, or NULL if the allocation fails. + * @return A 4D vector with the specified coordinates. */ Vec4 vec4(float x, float y, float z, float w); /** - * @brief Adds two 4D vectors in a new 4D vector. - * @param v1 First vector pointer. - * @param v2 Second vector pointer. - * @return A pointer to a newly allocated 4D vector - * representing the sum of v1 and v2. - * Returns NULL if the allocation fails. + * @brief Adds two 4D vectors and returns a new 4D vector. + * @param v1 First vector. + * @param v2 Second vector. + * @return A 4D vector representing the sum of v1 and v2. */ Vec4 vec4Add(Vec4 v1, Vec4 v2); /** - * @brief Subtracts two 4D vectors in a new 4D - * vector. - * @param v1 First vector pointer. - * @param v2 Second vector pointer. - * @return A pointer to a newly allocated 4D vector - * representing the subtraction of v1 and v2. - * Returns NULL if the allocation fails. + * @brief Subtracts two 4D vectors and returns a new 4D vector. + * @param v1 First vector. + * @param v2 Second vector. + * @return A 4D vector representing the result of v1 minus v2. */ Vec4 vec4Sub(Vec4 v1, Vec4 v2); /** - * @brief Scales a 4D vector by a constant scalar in a - * new 4D vector. - * @param v 4D vector pointer. - * @param scalar Constant. - * @return A pointer to a newly allocated 4D vector - * representing the multiplication of v1 and a - * scalar. Returns NULL if the allocation - * fails. + * @brief Scales a 4D vector by a constant scalar and returns a new 4D vector. + * @param v 4D vector. + * @param scalar Scalar value. + * @return A 4D vector representing the multiplication of v by the scalar. */ Vec4 vec4Scale(Vec4 v, float scalar); /** - * @brief Computes the dot product of two 4D vectors - * @param a First vector pointer. - * @param b Second vector pointer. - * @return The dot product of a and b as a scalar value. - * - scalar value > 0.f: Both vectors have the same orientation - * (the angle between them is acute). - * - scalar value = 0.f: Both vectors are orthogonal (the angle - * between them is 90 degrees). - * - scalar value < 0.f: Both vectors have opposite orientations - * (the angle between them is obtuse). - * Returns NAN if one of the input vectors are - * NULL. + * @brief Computes the dot product of two 4D vectors. + * @param a First vector. + * @param b Second vector. + * @return A scalar value representing the dot product of a and b. + * - scalar > 0: Both vectors have the same orientation (the angle between them is acute). + * - scalar = 0: Vectors are orthogonal (the angle between them is 90 degrees). + * - scalar < 0: Vectors have opposite orientations (the angle between them is obtuse). */ float vec4Dot(Vec4 a, Vec4 b); /** - * @brief Computes the Length (magnitude) of a 4D - * vector - * @param v 4D vector pointer. - * @return The length (magnitude) of the vector v as - * a scalar value. Returns NAN if input vector - * is NULL. + * @brief Computes the length (magnitude) of a 4D vector. + * @param v 4D vector. + * @return A scalar value representing the length (magnitude) of the vector v. */ float vec4Len(Vec4 v); /** - * @brief Normalizes the 4D vector. - * @param v Pointer to the 4D vector. - * @return A pointer to a newly allocated 4D vector that - * is normalized. Returns a zero vector (0, 0, 0) - * if the input vector is a zero vector. Returns - * NULL if the input pointer is invalid. + * @brief Normalizes a 4D vector (scales it to unit length). + * @param v 4D vector. + * @return A 4D vector representing the normalized version of v. + * Returns a zero vector (0, 0, 0) if the input vector is a zero vector. */ Vec4 vec4Norm(Vec4 v); /** - * @brief Performs linear interpolation between two 4D - * vectors to determine a new 4D vector. - * @param a Pointer to the first 4D vector (start vector). - * @param b Pointer to the second 4D vector (end vector). - * @param t Interpolation factor (0.0 to 1.0): + * @brief Performs linear interpolation between two 4D vectors. + * @param a Start vector. + * @param b End vector. + * @param t Interpolation factor (0.0 to 1.0). * - t = 0 returns the vector a. * - t = 1 returns the vector b. - * - t between 0 and 1 returns a point between - * a and b. - * @return A pointer to a newly allocated 4D vector - * representing the interpolated result between - * a and b. Returns NULL if any of the input vectors - * is NULL. + * - t between 0 and 1 returns a point between a and b. + * @return A 4D vector representing the interpolated result between a and b. */ Vec4 vec4Lerp(Vec4 a, Vec4 b, float t); /** * @brief Computes the angle between two 4D vectors. - * @param a Pointer to the first vector. - * @param b Pointer to the second vector. - * @return The angle between a and b in radians. + * @param a First vector. + * @param b Second vector. + * @return The angle between vectors a and b in radians. */ float vec4Angle(Vec4 a, Vec4 b); /** * @brief Computes the projection of vector a onto vector b. - * @param a Pointer to the vector to be projected. - * @param b Pointer to the vector onto which a is projected. - * @return A pointer to a newly allocated 4D vector representing - * the projection of a onto b. - * Returns NULL if b is a zero vector. + * @param a The vector to be projected. + * @param b The vector onto which a is projected. + * @return A 4D vector representing the projection of a onto b. */ Vec4 vec4Proj(Vec4 a, Vec4 b); /** * @brief Computes the reflection of a vector v against a normal. - * @param v Pointer to the incident vector. - * @param normal Pointer to the normal vector of the surface. - * @return A pointer to a newly allocated 4D vector representing - * the reflection of v across normal. - * Returns NULL if normal is a zero vector. + * @param v The incident vector. + * @param normal The normal vector of the surface. + * @return A 4D vector representing the reflection of v across normal. */ Vec4 vec4Refl(Vec4 v, Vec4 normal); /** * @brief Computes the Euclidean distance between two 4D vectors. - * @param a Pointer to the first vector. - * @param b Pointer to the second vector. + * @param a The first vector. + * @param b The second vector. * @return The scalar distance between a and b. - * Returns NAN if either vector is NULL. */ float vec4Dist(Vec4 a, Vec4 b); - #endif // VECTOR4_H \ No newline at end of file