Doxygen comments (#12)

- organized headers.
- added comments to headers.
- fixed a solver determinism bug.
- removed some un-used math functions
This commit is contained in:
Erin Catto 2026-06-10 13:21:14 -07:00 • committed by GitHub
commit d8fbeb444e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
53 changed files with 8973 additions and 1812 deletions

View file

@ -45,6 +45,24 @@ typedef struct b3ShapeExtent
b3TrianglePoint b3ClosestPointOnTriangle( b3Vec3 a, b3Vec3 b, b3Vec3 c, b3Vec3 q );
// The closest points between to segments or infinite lines.
typedef struct b3ClosestApproachResult
{
b3Vec3 point1;
float fraction1;
b3Vec3 point2;
float fraction2;
} b3ClosestApproachResult;
// Compute the closest point on the segment a-b to the target q
b3Vec3 b3ClosestPointOnSegment( b3Vec3 a, b3Vec3 b, b3Vec3 q );
// Compute the closest points on two infinite lines
b3ClosestApproachResult b3ClosestApproachLines( b3Vec3 p1, b3Vec3 d1, b3Vec3 p2, b3Vec3 d2 );
// Compute the closest points on two line segments
b3ClosestApproachResult b3ClosestApproachSegments( b3Vec3 p1, b3Vec3 q1, b3Vec3 p2, b3Vec3 q2 );
float b3IntersectSegmentTriangle( b3Vec3 p, b3Vec3 q, b3Vec3 a, b3Vec3 b, b3Vec3 c );
float b3IntersectSegmentSphere( b3Vec3 p, b3Vec3 q, b3Vec3 c, float r );
@ -62,8 +80,6 @@ b3Matrix3 b3Steiner( float mass, b3Vec3 origin );
int b3GetProxySupport( const b3ShapeProxy* proxy, b3Vec3 axis );
int b3GetPointSupport( const b3Vec3* points, int count, b3Vec3 axis );
bool b3IntersectRayAndAABB( b3Vec3 lowerBound, b3Vec3 upperBound, b3Vec3 p1, b3Vec3 p2, float* minFraction, float* maxFraction );
static inline size_t b3AlignUp8( size_t x )
{
return ( x + 7u ) & ~(size_t)7u;
@ -218,10 +234,10 @@ static inline b3Quat b3IntegrateRotation( b3Quat q1, b3Vec3 deltaRotation )
// Pseudo angular velocity from a quaternion target
// w = 2 * (target - q) * conj(q)
static inline b3Vec3 b3DeltaQuatToRotation(b3Quat q, b3Quat target)
static inline b3Vec3 b3DeltaQuatToRotation( b3Quat q, b3Quat target )
{
b3Quat s = q;
if (b3DotQuat(q, target) < 0.0f)
if ( b3DotQuat( q, target ) < 0.0f )
{
// Correct polarity
s = b3NegateQuat( q );
@ -244,7 +260,7 @@ static inline float b3ScalarTripleProduct( b3Vec3 a, b3Vec3 b, b3Vec3 c )
// Get a value by index. Avoid undefined behavior of code like (&v.x)[2].
static inline float b3GetByIndex( b3Vec3 v, int index )
{
B3_ASSERT( 0 <= index && index < 3 );
B3_VALIDATE( 0 <= index && index < 3 );
float temp[3] = { v.x, v.y, v.z };
return temp[index];
}
@ -369,7 +385,18 @@ static inline b3Vec2 b3Solve2( b3Matrix2 m, b3Vec2 b )
return B3_LITERAL( b3Vec2 ){ 0.0f, 0.0f };
}
static inline b3Vec3 b3ModifiedCross(b3Vec3 a, b3Vec3 b)
// Convenience function: s * a + t * b + u * c
static inline b3Vec3 b3Blend3( float s, b3Vec3 a, float t, b3Vec3 b, float u, b3Vec3 c )
{
b3Vec3 d = {
s * a.x + t * b.x + u * c.x,
s * a.y + t * b.y + u * c.y,
s * a.z + t * b.z + u * c.z,
};
return d;
}
static inline b3Vec3 b3ModifiedCross( b3Vec3 a, b3Vec3 b )
{
b3Vec3 c;
c.x = a.y * b.z + a.z * b.y;
@ -378,15 +405,30 @@ static inline b3Vec3 b3ModifiedCross(b3Vec3 a, b3Vec3 b)
return c;
}
static inline b3Matrix3 b3MakeDiagonalMatrix( float a, float b, float c )
{
return (b3Matrix3){ { a, 0.0f, 0.0f }, { 0.0f, b, 0.0f }, { 0.0f, 0.0f, c } };
}
static inline b3Matrix3 b3Skew( b3Vec3 v )
{
b3Matrix3 out;
out.cx = (b3Vec3){ 0, v.z, -v.y };
out.cy = (b3Vec3){ -v.z, 0, v.x };
out.cz = (b3Vec3){ v.y, -v.x, 0 };
return out;
}
static inline b3Plane b3NormalizePlane( b3Plane plane )
{
float invLength = 1.0f / b3Length( plane.normal );
return B3_LITERAL( b3Plane ){ b3MulSV( invLength, plane.normal ), invLength * plane.offset };
return (b3Plane){ b3MulSV( invLength, plane.normal ), invLength * plane.offset };
}
static inline b3Plane b3MakePlaneFromNormalAndPoint( b3Vec3 normal, b3Vec3 point )
{
return B3_LITERAL( b3Plane ){ normal, b3Dot( normal, point ) };
return (b3Plane){ normal, b3Dot( normal, point ) };
}
static inline b3Plane b3MakePlaneFromPoints( b3Vec3 point1, b3Vec3 point2, b3Vec3 point3 )
@ -430,7 +472,8 @@ static inline float b3SignedVolume( b3Vec3 v1, b3Vec3 v2, b3Vec3 v3, b3Vec3 p )
// todo eliminate this
static inline bool b3IsWithinSegments( const b3ClosestApproachResult* result )
{
return ( 0.0f <= result->lambda1 && result->lambda1 <= 1.0f ) && ( 0.0f <= result->lambda2 && result->lambda2 <= 1.0f );
return ( 0.0f <= result->fraction1 && result->fraction1 <= 1.0f ) &&
( 0.0f <= result->fraction2 && result->fraction2 <= 1.0f );
}
static inline b3Matrix3 b3RotateInertia( b3Quat q, b3Matrix3 centralInertia )
@ -446,3 +489,31 @@ static inline b3Matrix3 b3TransformInertia( b3Transform transform, b3Matrix3 cen
inertia = b3AddMM( inertia, b3Steiner( mass, transform.p ) );
return inertia;
}
// Twist angle around the z-axis, used for twist limit and revolute angle limit
static inline float b3GetTwistAngle( b3Quat q )
{
// Account for polarity to keep the twist angle in range.
// This is simpler than asking the user to check polarity or unwinding.
float twist = q.s < 0.0f ? b3Atan2( -q.v.z, -q.s ) : b3Atan2( q.v.z, q.s );
twist *= 2.0f;
B3_ASSERT( -B3_PI <= twist && twist <= B3_PI );
return twist;
}
// Swing angle used for cone limit
static inline float b3GetSwingAngle( b3Quat q )
{
// Polarity should not matter because all terms are squared.
float x = sqrtf( q.v.z * q.v.z + q.s * q.s );
float y = sqrtf( q.v.x * q.v.x + q.v.y * q.v.y );
float swing = 2.0f * b3Atan2( y, x );
B3_ASSERT( 0.0f <= swing && swing <= B3_PI );
return swing;
}
// Add a point to an AABB.
static inline b3AABB b3AABB_AddPoint( b3AABB a, b3Vec3 point )
{
return (b3AABB){ b3Min( a.lowerBound, point ), b3Max( a.upperBound, point ) };
}