guezoloic/t3dsr
1
0
Fork 0
mirror of https://github.com/guezoloic/t3dsr.git synced 2026-01-25 09:34:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: rework docs

Browse Source
This commit is contained in:
Loïc GUEZO
2025-03-21 08:44:50 +01:00
committed by Loïc GUEZO
parent b613081224
commit 0d2ebbb741
3 changed files with 98 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
include/math/vector.h
View File

@@ -11,7 +11,7 @@
* the first three components of the 4D vector (x, y, z). * the first three components of the 4D vector (x, y, z).
* Returns NULL if the input vector is NULL or allocation fails. * 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. * @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). * a default w component (1.0 for position, 0.0 for direction).
* Returns NULL if the input vector is NULL or allocation fails. * Returns NULL if the input vector is NULL or allocation fails.
*/ */
Vec4* Vec3ToVec4(Vec3* v); Vec4 Vec3ToVec4(Vec3 v);
#endif // VECTOR_H #endif // VECTOR_H

142
include/math/vector3.h
View File

@@ -10,159 +10,121 @@ typedef struct {
* @param x X-axis coordinate. * @param x X-axis coordinate.
* @param y Y-axis coordinate. * @param y Y-axis coordinate.
* @param z Z-axis coordinate. * @param z Z-axis coordinate.
* @return A pointer to the newly allocated 3D vector if * @return A 3D vector with the specified coordinates.
* successful, or NULL if the allocation fails.
*/ */
Vec3 vec3(float x, float y, float z); Vec3 vec3(float x, float y, float z);
/** /**
* @brief Adds two 3D vectors in a new 3D vector. * @brief Adds two 3D vectors and returns a new 3D vector.
* @param v1 First vector pointer. * @param v1 First vector.
* @param v2 Second vector pointer. * @param v2 Second vector.
* @return A pointer to a newly allocated 3D vector * @return A 3D vector representing the sum of v1 and v2.
* representing the sum of v1 and v2.
* Returns NULL if the allocation fails.
*/ */
Vec3 vec3Add(Vec3 v1, Vec3 v2); Vec3 vec3Add(Vec3 v1, Vec3 v2);
/** /**
* @brief Subtracts two 3D vectors in a new 3D * @brief Subtracts two 3D vectors and returns a new 3D vector.
* vector. * @param v1 First vector.
* @param v1 First vector pointer. * @param v2 Second vector.
* @param v2 Second vector pointer. * @return A 3D vector representing the result of v1 minus v2.
* @return A pointer to a newly allocated 3D vector
* representing the subtraction of v1 and v2.
* Returns NULL if the allocation fails.
*/ */
Vec3 vec3Sub(Vec3 v1, Vec3 v2); Vec3 vec3Sub(Vec3 v1, Vec3 v2);
/** /**
* @brief Scales a 3D vector by a constant scalar in a * @brief Scales a 3D vector by a constant scalar and returns a new 3D vector.
* new 3D vector. * @param v 3D vector.
* @param v 3D vector pointer. * @param scalar Scalar value.
* @param scalar Constant. * @return A 3D vector representing the multiplication of v by the scalar.
* @return A pointer to a newly allocated 3D vector
* representing the multiplication of v1 and a
* scalar. Returns NULL if the allocation
* fails.
*/ */
Vec3 vec3Scale(Vec3 v, float scalar); Vec3 vec3Scale(Vec3 v, float scalar);
/** /**
* @brief Computes the dot product of two 3D vectors * @brief Computes the dot product of two 3D vectors.
* @param a First vector pointer. * @param a First vector.
* @param b Second vector pointer. * @param b Second vector.
* @return The dot product of a and b as a scalar value. * @return A scalar value representing the dot product of a and b.
* - scalar value > 0.f: Both vectors have the same orientation * - scalar > 0: Both vectors have the same orientation (the angle between them is acute).
* (the angle between them is acute). * - scalar = 0: Vectors are orthogonal (the angle between them is 90 degrees).
* - scalar value = 0.f: Both vectors are orthogonal (the angle * - scalar < 0: Vectors have opposite orientations (the angle between them is obtuse).
* 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.
*/ */
float vec3Dot(Vec3 a, Vec3 b); float vec3Dot(Vec3 a, Vec3 b);
/** /**
* @brief Computes the Length (magnitude) of a 3D * @brief Computes the length (magnitude) of a 3D vector.
* vector * @param v 3D vector.
* @param v 3D vector pointer. * @return A scalar value representing the length (magnitude) of the vector v.
* @return The length (magnitude) of the vector v as
* a scalar value. Returns NAN if input vector
* is NULL.
*/ */
float vec3Len(Vec3 v); float vec3Len(Vec3 v);
/** /**
* @brief Normalizes the 3D vector. * @brief Normalizes a 3D vector (scales it to unit length).
* @param v Pointer to the 3D vector. * @param v 3D vector.
* @return A pointer to a newly allocated 3D vector that * @return A 3D vector representing the normalized version of v.
* is normalized. Returns a zero vector (0, 0, 0) * Returns a zero vector (0, 0, 0) if the input vector is a zero vector.
* if the input vector is a zero vector. Returns
* NULL if the input pointer is invalid.
*/ */
Vec3 vec3Norm(Vec3 v); Vec3 vec3Norm(Vec3 v);
/** /**
* @brief Performs linear interpolation between two 3D * @brief Performs linear interpolation between two 3D vectors.
* vectors to determine a new 3D vector. * @param a Start vector.
* @param a Pointer to the first 3D vector (start vector). * @param b End vector.
* @param b Pointer to the second 3D vector (end vector). * @param t Interpolation factor (0.0 to 1.0).
* @param t Interpolation factor (0.0 to 1.0):
* - t = 0 returns the vector a. * - t = 0 returns the vector a.
* - t = 1 returns the vector b. * - t = 1 returns the vector b.
* - t between 0 and 1 returns a point between * - t between 0 and 1 returns a point between a and b.
* a and b. * @return A 3D vector representing the interpolated result 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.
*/ */
Vec3 vec3Lerp(Vec3 a, Vec3 b, float t); Vec3 vec3Lerp(Vec3 a, Vec3 b, float t);
/** /**
* @brief Computes the cross product of two 3D vectors. * @brief Computes the cross product of two 3D vectors.
* The cross product produces a new vector that is * The cross product produces a new vector that is orthogonal (perpendicular) to both input vectors.
* orthogonal (perpendicular) to both input vectors. * The direction of the resulting vector follows the right-hand rule.
* The direction of the resulting vector follows the * @param a First vector.
* right-hand rule. * @param b Second vector.
* @param a Pointer to the first vector. * @return A 3D vector representing the cross product of vectors a and b.
* @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.
*/ */
Vec3 vec3Cross(Vec3 a, Vec3 b); Vec3 vec3Cross(Vec3 a, Vec3 b);
/** /**
* @brief Computes the angle between two 3D vectors. * @brief Computes the angle between two 3D vectors.
* @param a Pointer to the first vector. * @param a First vector.
* @param b Pointer to the second vector. * @param b Second vector.
* @return The angle between a and b in radians. * @return The angle between vectors a and b in radians.
*/ */
float vec3Angle(Vec3 a, Vec3 b); float vec3Angle(Vec3 a, Vec3 b);
/** /**
* @brief Computes the projection of vector a onto vector b. * @brief Computes the projection of vector a onto vector b.
* @param a Pointer to the vector to be projected. * @param a The vector to be projected.
* @param b Pointer to the vector onto which a is projected. * @param b The vector onto which a is projected.
* @return A pointer to a newly allocated 3D vector representing * @return A 3D vector representing the projection of a onto b.
* the projection of a onto b.
* Returns NULL if b is a zero vector.
*/ */
Vec3 vec3Proj(Vec3 a, Vec3 b); Vec3 vec3Proj(Vec3 a, Vec3 b);
/** /**
* @brief Computes the reflection of a vector v against a normal. * @brief Computes the reflection of a vector v against a normal.
* @param v Pointer to the incident vector. * @param v The incident vector.
* @param normal Pointer to the normal vector of the surface. * @param normal The normal vector of the surface.
* @return A pointer to a newly allocated 3D vector representing * @return A 3D vector representing the reflection of v across normal.
* the reflection of v across normal.
* Returns NULL if normal is a zero vector.
*/ */
Vec3 vec3Refl(Vec3 v, Vec3 normal); Vec3 vec3Refl(Vec3 v, Vec3 normal);
/** /**
* @brief Computes the Euclidean distance between two 3D vectors. * @brief Computes the Euclidean distance between two 3D vectors.
* @param a Pointer to the first vector. * @param a The first vector.
* @param b Pointer to the second vector. * @param b The second vector.
* @return The scalar distance between a and b. * @return The scalar distance between a and b.
* Returns NAN if either vector is NULL.
*/ */
float vec3Dist(Vec3 a, Vec3 b); float vec3Dist(Vec3 a, Vec3 b);
/** /**
* @brief Rotates a 3D vector around a given axis by a specified angle. * @brief Rotates a 3D vector around a given axis by a specified angle.
* @param v Pointer to the vector to rotate. * @param v The vector to rotate.
* @param axis Pointer to the rotation axis (must be normalized). * @param axis The rotation axis (must be normalized).
* @param angle Rotation angle in radians. * @param angle Rotation angle in radians.
* @return A pointer to a newly allocated 3D vector representing * @return A 3D vector representing the rotated vector.
* the rotated vector.
* Returns NULL if axis is a zero vector.
*/ */
Vec3 vec3Rotate(Vec3 v, Vec3 axis, float angle); Vec3 vec3Rotate(Vec3 v, Vec3 axis, float angle);
void vec3Free(Vec3 v);
#endif // VEC3_H #endif // VEC3_H

119
include/math/vector4.h
View File

@@ -11,133 +11,102 @@ typedef struct {
* @param y Y-axis coordinate. * @param y Y-axis coordinate.
* @param z Z-axis coordinate. * @param z Z-axis coordinate.
* @param w W-axis coordinate. * @param w W-axis coordinate.
* @return A pointer to the newly allocated 4D vector if * @return A 4D vector with the specified coordinates.
* successful, or NULL if the allocation fails.
*/ */
Vec4 vec4(float x, float y, float z, float w); Vec4 vec4(float x, float y, float z, float w);
/** /**
* @brief Adds two 4D vectors in a new 4D vector. * @brief Adds two 4D vectors and returns a new 4D vector.
* @param v1 First vector pointer. * @param v1 First vector.
* @param v2 Second vector pointer. * @param v2 Second vector.
* @return A pointer to a newly allocated 4D vector * @return A 4D vector representing the sum of v1 and v2.
* representing the sum of v1 and v2.
* Returns NULL if the allocation fails.
*/ */
Vec4 vec4Add(Vec4 v1, Vec4 v2); Vec4 vec4Add(Vec4 v1, Vec4 v2);
/** /**
* @brief Subtracts two 4D vectors in a new 4D * @brief Subtracts two 4D vectors and returns a new 4D vector.
* vector. * @param v1 First vector.
* @param v1 First vector pointer. * @param v2 Second vector.
* @param v2 Second vector pointer. * @return A 4D vector representing the result of v1 minus v2.
* @return A pointer to a newly allocated 4D vector
* representing the subtraction of v1 and v2.
* Returns NULL if the allocation fails.
*/ */
Vec4 vec4Sub(Vec4 v1, Vec4 v2); Vec4 vec4Sub(Vec4 v1, Vec4 v2);
/** /**
* @brief Scales a 4D vector by a constant scalar in a * @brief Scales a 4D vector by a constant scalar and returns a new 4D vector.
* new 4D vector. * @param v 4D vector.
* @param v 4D vector pointer. * @param scalar Scalar value.
* @param scalar Constant. * @return A 4D vector representing the multiplication of v by the scalar.
* @return A pointer to a newly allocated 4D vector
* representing the multiplication of v1 and a
* scalar. Returns NULL if the allocation
* fails.
*/ */
Vec4 vec4Scale(Vec4 v, float scalar); Vec4 vec4Scale(Vec4 v, float scalar);
/** /**
* @brief Computes the dot product of two 4D vectors * @brief Computes the dot product of two 4D vectors.
* @param a First vector pointer. * @param a First vector.
* @param b Second vector pointer. * @param b Second vector.
* @return The dot product of a and b as a scalar value. * @return A scalar value representing the dot product of a and b.
* - scalar value > 0.f: Both vectors have the same orientation * - scalar > 0: Both vectors have the same orientation (the angle between them is acute).
* (the angle between them is acute). * - scalar = 0: Vectors are orthogonal (the angle between them is 90 degrees).
* - scalar value = 0.f: Both vectors are orthogonal (the angle * - scalar < 0: Vectors have opposite orientations (the angle between them is obtuse).
* 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.
*/ */
float vec4Dot(Vec4 a, Vec4 b); float vec4Dot(Vec4 a, Vec4 b);
/** /**
* @brief Computes the Length (magnitude) of a 4D * @brief Computes the length (magnitude) of a 4D vector.
* vector * @param v 4D vector.
* @param v 4D vector pointer. * @return A scalar value representing the length (magnitude) of the vector v.
* @return The length (magnitude) of the vector v as
* a scalar value. Returns NAN if input vector
* is NULL.
*/ */
float vec4Len(Vec4 v); float vec4Len(Vec4 v);
/** /**
* @brief Normalizes the 4D vector. * @brief Normalizes a 4D vector (scales it to unit length).
* @param v Pointer to the 4D vector. * @param v 4D vector.
* @return A pointer to a newly allocated 4D vector that * @return A 4D vector representing the normalized version of v.
* is normalized. Returns a zero vector (0, 0, 0) * Returns a zero vector (0, 0, 0) if the input vector is a zero vector.
* if the input vector is a zero vector. Returns
* NULL if the input pointer is invalid.
*/ */
Vec4 vec4Norm(Vec4 v); Vec4 vec4Norm(Vec4 v);
/** /**
* @brief Performs linear interpolation between two 4D * @brief Performs linear interpolation between two 4D vectors.
* vectors to determine a new 4D vector. * @param a Start vector.
* @param a Pointer to the first 4D vector (start vector). * @param b End vector.
* @param b Pointer to the second 4D vector (end vector). * @param t Interpolation factor (0.0 to 1.0).
* @param t Interpolation factor (0.0 to 1.0):
* - t = 0 returns the vector a. * - t = 0 returns the vector a.
* - t = 1 returns the vector b. * - t = 1 returns the vector b.
* - t between 0 and 1 returns a point between * - t between 0 and 1 returns a point between a and b.
* a and b. * @return A 4D vector representing the interpolated result 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.
*/ */
Vec4 vec4Lerp(Vec4 a, Vec4 b, float t); Vec4 vec4Lerp(Vec4 a, Vec4 b, float t);
/** /**
* @brief Computes the angle between two 4D vectors. * @brief Computes the angle between two 4D vectors.
* @param a Pointer to the first vector. * @param a First vector.
* @param b Pointer to the second vector. * @param b Second vector.
* @return The angle between a and b in radians. * @return The angle between vectors a and b in radians.
*/ */
float vec4Angle(Vec4 a, Vec4 b); float vec4Angle(Vec4 a, Vec4 b);
/** /**
* @brief Computes the projection of vector a onto vector b. * @brief Computes the projection of vector a onto vector b.
* @param a Pointer to the vector to be projected. * @param a The vector to be projected.
* @param b Pointer to the vector onto which a is projected. * @param b The vector onto which a is projected.
* @return A pointer to a newly allocated 4D vector representing * @return A 4D vector representing the projection of a onto b.
* the projection of a onto b.
* Returns NULL if b is a zero vector.
*/ */
Vec4 vec4Proj(Vec4 a, Vec4 b); Vec4 vec4Proj(Vec4 a, Vec4 b);
/** /**
* @brief Computes the reflection of a vector v against a normal. * @brief Computes the reflection of a vector v against a normal.
* @param v Pointer to the incident vector. * @param v The incident vector.
* @param normal Pointer to the normal vector of the surface. * @param normal The normal vector of the surface.
* @return A pointer to a newly allocated 4D vector representing * @return A 4D vector representing the reflection of v across normal.
* the reflection of v across normal.
* Returns NULL if normal is a zero vector.
*/ */
Vec4 vec4Refl(Vec4 v, Vec4 normal); Vec4 vec4Refl(Vec4 v, Vec4 normal);
/** /**
* @brief Computes the Euclidean distance between two 4D vectors. * @brief Computes the Euclidean distance between two 4D vectors.
* @param a Pointer to the first vector. * @param a The first vector.
* @param b Pointer to the second vector. * @param b The second vector.
* @return The scalar distance between a and b. * @return The scalar distance between a and b.
* Returns NAN if either vector is NULL.
*/ */
float vec4Dist(Vec4 a, Vec4 b); float vec4Dist(Vec4 a, Vec4 b);
#endif // VECTOR4_H #endif // VECTOR4_H