guezoloic/t3dsr
1
0
Fork 0
mirror of https://github.com/guezoloic/t3dsr.git synced 2026-01-25 12: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

142
include/math/vector3.h
View File

@@ -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