Build polish (#18)

Improve build process and documentation.
Improved ray versus capsule accuracy.
UI improvements
This commit is contained in:
Erin Catto 2026-06-28 10:44:34 -07:00 • committed by GitHub
commit 69037feaba
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 1719 additions and 158 deletions

View file

@ -234,7 +234,7 @@ install(
)
install(
FILES ${BOX3D_API_FILES}
FILES ${BOX3D_INCLUDE_FILES}
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/box3d
)
@ -242,7 +242,7 @@ include(CMakePackageConfigHelpers)
write_basic_package_version_file(
"${CMAKE_CURRENT_BINARY_DIR}/box3dConfigVersion.cmake"
VERSION ${BOX3D_VERSION}
VERSION ${PROJECT_VERSION}
COMPATIBILITY SameMajorVersion
)

View file

@ -81,27 +81,6 @@ b3AABB b3ComputeSweptCapsuleAABB( const b3Capsule* shape, b3Transform xf1, b3Tra
return aabb;
}
static b3CastOutput b3CastRayAgainstCap( b3Vec3 p, b3Vec3 q, b3Vec3 c, float r, float maxFraction )
{
b3Sphere sphere = { c, r };
b3RayCastInput input = {
.origin = p,
.translation = b3Sub( q, p ),
.maxFraction = maxFraction,
};
b3CastOutput output = b3RayCastSphere( &sphere, &input );
return output;
}
static b3CastOutput b3TransformCapsuleResult( b3CastOutput result, b3Quat rotation, b3Vec3 translation )
{
b3CastOutput out = result;
out.point = b3Add( b3RotateVector( rotation, result.point ), translation );
out.normal = b3RotateVector( rotation, result.normal );
return out;
}
bool b3OverlapCapsule( const b3Capsule* shape, b3Transform shapeTransform, const b3ShapeProxy* proxy )
{
b3DistanceInput input;
@ -115,11 +94,12 @@ bool b3OverlapCapsule( const b3Capsule* shape, b3Transform shapeTransform, const
return output.distance < B3_OVERLAP_SLOP;
}
// todo_erin implement precision improvement
// Precision Improvements for Ray / Sphere Intersection - Ray Tracing Gems 2019
// http://www.codercorner.com/blog/?p=321
b3CastOutput b3RayCastCapsule( const b3Capsule* shape, const b3RayCastInput* input )
{
B3_ASSERT( b3IsValidRay( input ) );
b3Vec3 c1 = shape->center1;
b3Vec3 c2 = shape->center2;
float r = shape->radius;
@ -127,127 +107,231 @@ b3CastOutput b3RayCastCapsule( const b3Capsule* shape, const b3RayCastInput* inp
// Initialize result structure
b3CastOutput output = { 0 };
// Compute height and handle degenerate capsules
float height = b3Distance( c1, c2 );
if ( height < 1000.0f * FLT_MIN )
b3Vec3 d = b3Sub( c2, c1 );
// Fall back to sphere if the capsule is short
float tol = 0.01f * B3_LINEAR_SLOP;
float lengthSquared = b3LengthSquared( d );
if ( lengthSquared < tol * tol )
{
b3Vec3 sphereCenter = b3MulSV( 0.5f, b3Add( shape->center1, shape->center2 ) );
b3Sphere sphere = { sphereCenter, shape->radius };
return b3RayCastSphere( &sphere, input );
}
// Transform ray and capsule into local space capsule space
b3Quat rotation = b3ComputeQuatBetweenUnitVectors( b3Vec3_axisY, b3MulSV( 1.0f / height, b3Sub( c2, c1 ) ) );
b3Vec3 offset = c1;
// Vector from first center to ray origin.
b3Vec3 s = b3Sub( input->origin, c1 );
// Capsule starts at the origin and is along the y-axis
b3Vec3 a = b3Vec3_zero;
b3Vec3 b = { 0.0f, height, 0.0f };
b3Vec3 ab = b3Sub( b, a );
// Capsule axis
float length = sqrtf( lengthSquared );
b3Vec3 axis = b3MulSV( 1.0f / length, d );
// Ray expressed relative to capsule space (capsule along y-axis)
b3Vec3 p = b3InvRotateVector( rotation, b3Sub( input->origin, offset ) );
b3Vec3 q = b3Add( p, b3InvRotateVector( rotation, input->translation ) );
b3Vec3 pq = b3Sub( q, p );
// Project ray origin onto capsule axis.
float u = b3Dot( s, axis );
// Ray 2D translation length squared
float k1 = pq.x * pq.x + pq.z * pq.z;
// Closest point on infinite capsule axis, relative to c1.
b3Vec3 c = b3MulSV( u, axis );
// Ray start point 2D separation squared from circle
float k3 = p.x * p.x + p.z * p.z - r * r;
// Vector from closest point to ray origin
b3Vec3 sc = b3Sub( s, c );
// Parallel case (2D ray translation is zero)
if ( k1 < 1000.0f * FLT_MIN )
// Squared distance from ray origin to capsule axis
float sc2 = b3LengthSquared( sc );
// Is the ray origin within the infinite cylinder along the capsule axis?
if ( sc2 < r * r )
{
if ( k3 > 0.0f )
{
// Parallel and outside
return output;
}
// Clamped barycentric coordinate of ray origin projected onto capsule axis.
float uClamped = b3ClampFloat( u, 0.0f, length );
if ( 0.0f <= p.y && p.y <= height )
// The closest point on the bounded capsule segment, relative to c1.
b3Vec3 cp = b3MulSV( uClamped, axis );
// Vector from ray origin to closest point on segment.
b3Vec3 scp = b3Sub( s, cp );
// Squared distance of ray origin from capsule segment.
float scp2 = b3LengthSquared( scp );
// Is the ray origin within the capsule?
if ( scp2 < r * r )
{
// Parallel and inside
output.hit = true;
output.point = input->origin;
return output;
}
// Below cylinder and casting upwards
if ( p.y < 0.0f && pq.y > 0.0f )
// The ray can hit an endcap.
b3Sphere sphere = {
.center = b3Add( c1, cp ),
.radius = r,
};
return b3RayCastSphere( &sphere, input );
}
// Ray axis. A zero length ray reaching here starts outside the capsule, so it misses.
// Same zero length convention as b3RayCastSphere.
b3Vec3 dr = input->translation;
float rayLength;
b3Vec3 rayAxis = b3GetLengthAndNormalize( &rayLength, dr );
if ( rayLength == 0.0f )
{
return output;
}
// Barycentric coordinate of ray end point.
float v = u + input->maxFraction * b3Dot( dr, axis );
// Early out: does the projected ray fall outside the capsule?
if ( ( u < -r && v < -r ) || ( length + r < u && length + r < v ) )
{
return output;
}
// Compute the closest point between the ray segment and the capsule segment.
// See Real-Time Collision Detection, section 5.1.9
// Closest point on capsule : a1 = segment unit axis, t1 = unknown fraction
// p1 = t1 * a1
// Closet point on ray : a2 = ray unit axis, t2 = unknown fraction
// p2 = s + t2 * a2
// Closest point perpendicularity conditions.
// dot(p2 - p1, a1) = 0
// dot(p2 - p1, a2) = 0
// Expand
// dot(t1 * a1 - s - t2 * a2, a1) = 0
// dot(t1 * a1 - s - t2 * a2, a2) = 0
// Expand
// t1 - dot(s, a1) - t2 * dot(a1, a2) = 0
// t1 * dot(a1, a2) - dot(s, a2) - t2 = 0
// Group : a12 = dot(a1, a2), sa1 = dot(s, a1), sa2 = dot(s, a2)
// t1 - a12 * t2 = sa1
// a12 * t1 - t2 = sa2
// Solve
// https://en.wikipedia.org/wiki/Cramer%27s_rule
// I've flipped the signs of the numerator and denominator to give a positive determinant.
// det = 1 - a12 * a12
// t1 = (sa1 - a12 * sa2) / det
// t2 = (a12 * sa1 - sa2) / det
b3Vec3 a1 = axis;
b3Vec3 a2 = rayAxis;
float a12 = b3Dot( a1, a2 );
// Ray distance to the near intersection with the infinite cylinder. Length units.
float tr;
float det = 1.0f - a12 * a12;
if ( det < FLT_EPSILON )
{
// Ray nearly parallel to the capsule axis. The closest point solve below divides by det,
// so it loses all precision here and a slowly converging ray would be missed. Intersect the
// ray with the infinite cylinder directly using the components perpendicular to the axis.
// The origin is outside the cylinder, so a hit needs the ray to close in on it.
// Instead of a cross product, subtract the parallel part to get a perpendicular vector. Non-dimensional.
b3Vec3 perp = b3MulSub( a2, a12, a1 );
float perp2 = b3LengthSquared( perp );
// Project to origin to c1 vector onto the perpendicular vector. beta has length units.
float beta = b3Dot( sc, perp );
float gamma = sc2 - r * r;
// Casting away from the axis, or the perpendicular gap never closes to the radius.
float disc = beta * beta - perp2 * gamma;
if ( beta >= 0.0f || disc < 0.0f )
{
output = b3CastRayAgainstCap( p, q, a, r, input->maxFraction );
return b3TransformCapsuleResult( output, rotation, offset );
return output;
}
// Above cylinder and casting downwards
if ( p.y > height && pq.y < 0.0f )
// Near root, written to dodge the (-beta - sqrt) cancellation as the ray nears parallel.
tr = gamma / ( -beta + sqrtf( disc ) );
}
else
{
// Closest points between the infinite ray and the infinite capsule axis.
float invDet = 1.0f / det;
float sa1 = u;
float sa2 = b3Dot( s, a2 );
float t1 = ( sa1 - a12 * sa2 ) * invDet;
float t2 = ( a12 * sa1 - sa2 ) * invDet;
// Closest points
b3Vec3 p1 = b3MulSV( t1, a1 );
b3Vec3 p2 = b3MulAdd( s, t2, a2 );
// Vector from closest point on infinite capsule to infinite ray.
b3Vec3 g = b3Sub( p2, p1 );
float g2 = b3LengthSquared( g );
if ( g2 > r * r )
{
output = b3CastRayAgainstCap( p, q, b, r, input->maxFraction );
return b3TransformCapsuleResult( output, rotation, offset );
// Early out: closest point on infinite ray is outside infinite cylinder.
return output;
}
// Above or below and casting away from cylinder
// Intersect the infinite ray with the infinite cylinder. Like ray versus sphere this is done
// relative to the closest point to avoid round-off errors. Length units, not a fraction.
// https://en.wikipedia.org/wiki/Line-cylinder_intersection
float h = sqrtf( ( r * r - g2 ) * invDet );
tr = t2 - h;
}
// Outside ray?
if ( tr < 0.0f || input->maxFraction * rayLength < tr )
{
return output;
}
// Non-parallel case
float k2 = pq.x * p.x + pq.z * p.z;
// The corresponding distance on the capsule axis. Length units.
float tc = u + tr * a12;
float discriminant = k2 * k2 - k1 * k3;
if ( discriminant < 0.0f )
// Outside c1 end?
if ( tc < 0.0f )
{
// No real roots - no intersection
return output;
// Ray cast sphere 1.
b3Sphere sphere = {
.center = c1,
.radius = r,
};
return b3RayCastSphere( &sphere, input );
}
float t = ( -k2 - sqrtf( discriminant ) ) / k1;
if ( t > input->maxFraction )
// Outside c2 end?
if (length < tc)
{
// Segment approaching cylinder, but not quite getting there.
return output;
// Ray cast sphere 2.
b3Sphere sphere = {
.center = c2,
.radius = r,
};
return b3RayCastSphere( &sphere, input );
}
// Don't skip t < 0. This means that we start in the *infinite* cylinder and still might hit a cap
// Hit point on capsule side, relative to c1.
b3Vec3 p = b3MulAdd( s, tr, rayAxis );
// This is the point on the ray that hits the infinite cylinder
b3Vec3 c = b3MulAdd( p, t, pq );
// Hit normal.
b3Vec3 normal = b3MulSub( p, tc, axis );
normal = b3Normalize( normal );
// This is the cylinder hit point relative to the capsule base
b3Vec3 ac = b3Sub( c, a );
// Fraction of the cylinder hit point along the capsule axis
float s = b3Dot( ac, ab ) / ( height * height );
if ( s < 0.0f )
{
// X projects outside A, run test through sphere at A
output = b3CastRayAgainstCap( p, q, a, r, input->maxFraction );
return b3TransformCapsuleResult( output, rotation, offset );
}
if ( s > 1.0f )
{
// X projects outside B, run test through sphere at B
output = b3CastRayAgainstCap( p, q, b, r, input->maxFraction );
return b3TransformCapsuleResult( output, rotation, offset );
}
if ( t < 0.0f )
{
// Ray starts inside
output.hit = true;
output.point = input->origin;
return output;
}
// Ray hits cylinder inside segment AB
output.fraction = t;
output.point = c;
output.normal = b3Normalize( (b3Vec3){ c.x, 0.0f, c.z } );
output.point = b3Add( c1, p );
output.normal = normal;
output.fraction = b3ClampFloat( tr / rayLength, 0.0f, input->maxFraction );
output.hit = true;
return b3TransformCapsuleResult( output, rotation, offset );
return output;
}
b3CastOutput b3ShapeCastCapsule( const b3Capsule* capsule, const b3ShapeCastInput* input )
@ -268,8 +352,7 @@ int b3CollideMoverAndCapsule( b3PlaneResult* result, const b3Capsule* shape, con
{
float totalRadius = mover->radius + shape->radius;
b3SegmentDistanceResult approach =
b3SegmentDistance( shape->center1, shape->center2, mover->center1, mover->center2 );
b3SegmentDistanceResult approach = b3SegmentDistance( shape->center1, shape->center2, mover->center1, mover->center2 );
// The normal points from the shape toward the mover.
float distance;

View file

@ -115,7 +115,7 @@ void b3Log( const char* format, ... )
b3Version b3GetVersion( void )
{
return (b3Version){ 0, 2, 0 };
return (b3Version){ 0, 1, 0 };
}
bool b3IsDoublePrecision( void )