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

@ -3,122 +3,174 @@
#include "aabb.h"
#include "math_internal.h"
#include "box3d/math_functions.h"
#include <float.h>
// From Real-time Collision Detection, p179.
b3CastOutput b3RayCastAABB( b3AABB a, b3Vec3 p1, b3Vec3 p2 )
// Similar to Real-time Collision Detection, p179.
// todo try
// https://www.scratchapixel.com/lessons/3d-basic-rendering/minimal-ray-tracer-rendering-simple-shapes/ray-box-intersection.html
bool b3RayCastAABB( b3AABB a, b3Vec3 p1, b3Vec3 p2, float* minFraction, float* maxFraction )
{
// Radius not handled
b3CastOutput output = { 0 };
float tmin = -FLT_MAX;
float tmax = FLT_MAX;
b3Vec3 p = p1;
// Ray direction and length
b3Vec3 d = b3Sub( p2, p1 );
b3Vec3 absD = b3Abs( d );
float rayLength = b3Length( d );
b3Vec3 normal = b3Vec3_zero;
// x-coordinate
if ( absD.x < FLT_EPSILON )
// Handle degenerate ray
if ( rayLength < FLT_EPSILON )
{
// parallel
if ( p.x < a.lowerBound.x || a.upperBound.x < p.x )
// Check if point is inside AABB
if ( p1.x >= a.lowerBound.x && p1.x <= a.upperBound.x && p1.y >= a.lowerBound.y && p1.y <= a.upperBound.y &&
p1.z >= a.lowerBound.z && p1.z <= a.upperBound.z )
{
return output;
*minFraction = 0.0f;
*maxFraction = 0.0f;
return true;
}
return false;
}
b3Vec3 rayDir = b3MulSV( 1.0f / rayLength, d );
// Slab method for ray-AABB intersection
float tMin = 0.0f;
float tMax = rayLength;
// x-axis
{
float rayComponent = rayDir.x;
float rayStart = p1.x;
float boxMin = a.lowerBound.x;
float boxMax = a.upperBound.x;
if ( b3AbsFloat( rayComponent ) < FLT_EPSILON )
{
// Ray is parallel to slab, check if ray origin is within slab
if ( rayStart < boxMin || rayStart > boxMax )
{
return false;
}
}
else
{
// Compute intersection distances
float t1 = ( boxMin - rayStart ) / rayComponent;
float t2 = ( boxMax - rayStart ) / rayComponent;
// Ensure t1 <= t2
if ( t1 > t2 )
{
float temp = t1;
t1 = t2;
t2 = temp;
}
// Update intersection interval
tMin = b3MaxFloat( tMin, t1 );
tMax = b3MinFloat( tMax, t2 );
// Check for no intersection
if ( tMin > tMax )
{
return false;
}
}
}
else
// y-axis
{
float inv_d = 1.0f / d.x;
float t1 = ( a.lowerBound.x - p.x ) * inv_d;
float t2 = ( a.upperBound.x - p.x ) * inv_d;
float rayComponent = rayDir.y;
float rayStart = p1.y;
float boxMin = a.lowerBound.y;
float boxMax = a.upperBound.y;
// Sign of the normal vector.
float s = -1.0f;
if ( t1 > t2 )
if ( b3AbsFloat( rayComponent ) < FLT_EPSILON )
{
float tmp = t1;
t1 = t2;
t2 = tmp;
s = 1.0f;
// Ray is parallel to slab, check if ray origin is within slab
if ( rayStart < boxMin || rayStart > boxMax )
{
return false;
}
}
// Push the min up
if ( t1 > tmin )
else
{
normal.y = 0.0f;
normal.x = s;
tmin = t1;
}
// Compute intersection distances
float t1 = ( boxMin - rayStart ) / rayComponent;
float t2 = ( boxMax - rayStart ) / rayComponent;
// Pull the max down
tmax = b3MinFloat( tmax, t2 );
// Ensure t1 <= t2
if ( t1 > t2 )
{
float temp = t1;
t1 = t2;
t2 = temp;
}
if ( tmin > tmax )
{
return output;
// Update intersection interval
tMin = b3MaxFloat( tMin, t1 );
tMax = b3MinFloat( tMax, t2 );
// Check for no intersection
if ( tMin > tMax )
{
return false;
}
}
}
// y-coordinate
if ( absD.y < FLT_EPSILON )
// z-axis
{
// parallel
if ( p.y < a.lowerBound.y || a.upperBound.y < p.y )
float rayComponent = rayDir.z;
float rayStart = p1.z;
float boxMin = a.lowerBound.z;
float boxMax = a.upperBound.z;
if ( b3AbsFloat( rayComponent ) < FLT_EPSILON )
{
return output;
// Ray is parallel to slab, check if ray origin is within slab
if ( rayStart < boxMin || rayStart > boxMax )
{
return false;
}
}
}
else
{
float inv_d = 1.0f / d.y;
float t1 = ( a.lowerBound.y - p.y ) * inv_d;
float t2 = ( a.upperBound.y - p.y ) * inv_d;
// Sign of the normal vector.
float s = -1.0f;
if ( t1 > t2 )
else
{
float tmp = t1;
t1 = t2;
t2 = tmp;
s = 1.0f;
}
// Compute intersection distances
float t1 = ( boxMin - rayStart ) / rayComponent;
float t2 = ( boxMax - rayStart ) / rayComponent;
// Push the min up
if ( t1 > tmin )
{
normal.x = 0.0f;
normal.y = s;
tmin = t1;
}
// Ensure t1 <= t2
if ( t1 > t2 )
{
float temp = t1;
t1 = t2;
t2 = temp;
}
// Pull the max down
tmax = b3MinFloat( tmax, t2 );
// Update intersection interval
tMin = b3MaxFloat( tMin, t1 );
tMax = b3MinFloat( tMax, t2 );
if ( tmin > tmax )
{
return output;
// Check for no intersection
if ( tMin > tMax )
{
return false;
}
}
}
// Does the ray start inside the box?
// Does the ray intersect beyond the max fraction?
if ( tmin < 0.0f || 1.0f < tmin )
// Check if intersection is behind ray start
if ( tMax < 0.0f )
{
return output;
return false;
}
// Intersection.
output.fraction = tmin;
output.normal = normal;
output.point = b3Lerp( p1, p2, tmin );
output.hit = true;
return output;
// Convert distances to fractions
*minFraction = b3ClampFloat( tMin / rayLength, 0.0f, 1.0f );
*maxFraction = b3ClampFloat( tMax / rayLength, 0.0f, 1.0f );
return true;
}