From d8fbeb444eddfec46ea363bc36cbae8d84533f84 Mon Sep 17 00:00:00 2001 From: Erin Catto Date: Wed, 10 Jun 2026 13:21:14 -0700 Subject: [PATCH] Doxygen comments (#12) - organized headers. - added comments to headers. - fixed a solver determinism bug. - removed some un-used math functions --- CMakeLists.txt | 3 +- README.md | 2 +- deploy_docs.sh | 4 + docs/CMakeLists.txt | 59 + docs/character.md | 207 ++++ docs/collision.md | 502 ++++++++ docs/compound.md | 157 +++ docs/extra.css | 85 ++ docs/faq.md | 140 +++ docs/foundation.md | 230 ++++ docs/hello.md | 208 ++++ docs/images/capsule.svg | 243 ++++ docs/images/captured_toi.svg | 124 ++ docs/images/center_of_mass.svg | 183 +++ docs/images/distance.svg | 178 +++ docs/images/logo.svg | 126 ++ docs/images/manifolds.svg | 256 ++++ docs/images/missed_toi.svg | 153 +++ docs/images/mover.png | Bin 0 -> 108143 bytes docs/images/overlap_test.svg | 148 +++ docs/images/raycast.svg | 151 +++ docs/images/samples.png | Bin 0 -> 333746 bytes docs/images/simulation_loop.svg | 396 ++++++ docs/images/skin_collision.svg | 140 +++ docs/images/tunneling1.svg | 162 +++ docs/images/tunneling2.svg | 140 +++ docs/layout.xml | 269 +++++ docs/loose_ends.md | 152 +++ docs/overview.md | 262 ++++ docs/reading.md | 5 + docs/recording.md | 14 + docs/samples.md | 21 + docs/simulation.md | 2002 +++++++++++++++++++++++++++++++ include/box3d/base.h | 14 +- include/box3d/box3d.h | 154 ++- include/box3d/collision.h | 1259 +++---------------- include/box3d/constants.h | 14 +- include/box3d/id.h | 20 +- include/box3d/math_functions.h | 387 +++--- include/box3d/types.h | 1721 +++++++++++++++++++++++--- samples/sample.cpp | 6 +- samples/sample_bodies.cpp | 2 +- shared/human.c | 12 +- src/aabb.c | 220 ++-- src/aabb.h | 4 +- src/distance.c | 87 -- src/height_field.c | 4 +- src/math_functions.c | 26 +- src/math_internal.h | 89 +- src/mesh_contact.c | 9 +- src/solver.c | 7 +- src/triangle_manifold.c | 4 +- test/test_collision.c | 66 +- 53 files changed, 8994 insertions(+), 1833 deletions(-) create mode 100644 deploy_docs.sh create mode 100644 docs/CMakeLists.txt create mode 100644 docs/character.md create mode 100644 docs/collision.md create mode 100644 docs/compound.md create mode 100644 docs/extra.css create mode 100644 docs/faq.md create mode 100644 docs/foundation.md create mode 100644 docs/hello.md create mode 100644 docs/images/capsule.svg create mode 100644 docs/images/captured_toi.svg create mode 100644 docs/images/center_of_mass.svg create mode 100644 docs/images/distance.svg create mode 100644 docs/images/logo.svg create mode 100644 docs/images/manifolds.svg create mode 100644 docs/images/missed_toi.svg create mode 100644 docs/images/mover.png create mode 100644 docs/images/overlap_test.svg create mode 100644 docs/images/raycast.svg create mode 100644 docs/images/samples.png create mode 100644 docs/images/simulation_loop.svg create mode 100644 docs/images/skin_collision.svg create mode 100644 docs/images/tunneling1.svg create mode 100644 docs/images/tunneling2.svg create mode 100644 docs/layout.xml create mode 100644 docs/loose_ends.md create mode 100644 docs/overview.md create mode 100644 docs/reading.md create mode 100644 docs/recording.md create mode 100644 docs/samples.md create mode 100644 docs/simulation.md diff --git a/CMakeLists.txt b/CMakeLists.txt index f7441a1..851a0d5 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -164,8 +164,7 @@ if(PROJECT_IS_TOP_LEVEL) endif() if(BOX3D_DOCS) - # todo - # add_subdirectory(docs) + add_subdirectory(docs) endif() endif() diff --git a/README.md b/README.md index 03141e7..cf0a31f 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ Box3D uses SSE2 and Neon SIMD math to improve performance. This can be disabled ## Documentation -- [Manual](https://box2d.org/documentation/) +The user manual lives in [`docs/`](docs/) and is built with Doxygen. Enable the `BOX3D_DOCS` CMake option and build the `doc` target. ## Community diff --git a/deploy_docs.sh b/deploy_docs.sh new file mode 100644 index 0000000..69bb6ea --- /dev/null +++ b/deploy_docs.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash + +# Copies documentation to blog +cp -R build/docs/html/. ../box2d_blog/public/documentation3d/ diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 0000000..23ea432 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,59 @@ +find_package(Doxygen REQUIRED dot) + +set(DOXYGEN_PROJECT_NAME "Box3D") +set(DOXYGEN_GENERATE_HTML YES) +set(DOXYGEN_GENERATE_XML YES) +set(DOXYGEN_USE_MATHJAX YES) +set(DOXYGEN_MATHJAX_VERSION MathJax_3) +set(DOXYGEN_MATHJAX_FORMAT SVG) +set(DOXYGEN_EXTRACT_ALL NO) +set(DOXYGEN_FILE_PATTERNS *.h) +set(DOXYGEN_ENABLE_PREPROCESSING YES) +set(DOXYGEN_MACRO_EXPANSION YES) +set(DOXYGEN_EXPAND_ONLY_PREDEF YES) +set(DOXYGEN_PREDEFINED B3_API= B3_INLINE= B3_BREAKPOINT= B3_ASSERT= B3_VALIDATE=) +set(DOXYGEN_WARN_IF_UNDOCUMENTED YES) + +# In multiline comments, this takes the first line/sentence as a brief description to use in the table of functions. +# So I don't need to use @brief tags to separate the short description from the full description. +set(DOXYGEN_JAVADOC_AUTOBRIEF YES) + +set(DOXYGEN_IMAGE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/images") +set(DOXYGEN_HTML_EXTRA_STYLESHEET "${CMAKE_CURRENT_SOURCE_DIR}/extra.css") +set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_CURRENT_SOURCE_DIR}/overview.md") +set(DOXYGEN_PROJECT_LOGO "${CMAKE_CURRENT_SOURCE_DIR}/images/logo.svg") +set(DOXYGEN_LAYOUT_FILE "${CMAKE_CURRENT_SOURCE_DIR}/layout.xml") + +set(DOXYGEN_INLINE_SIMPLE_STRUCTS YES) +set(DOXYGEN_TYPEDEF_HIDES_STRUCT YES) +# Drop the top tab bar, the tree carries the same navigation +set(DOXYGEN_DISABLE_INDEX YES) +set(DOXYGEN_GENERATE_TREEVIEW YES) +set(DOXYGEN_FULL_SIDEBAR NO) + +# No per-page outline panel on the right +set(DOXYGEN_PAGE_OUTLINE_PANEL NO) + +# Dark theme baked by doxygen, extra.css only adds the Box3D accent +set(DOXYGEN_HTML_COLORSTYLE DARK) + +# this tells doxygen to label structs as structs instead of classes +set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) +set(DOXYGEN_WARN_IF_INCOMPLETE_DOC NO) + +doxygen_add_docs(doc + "${CMAKE_SOURCE_DIR}/include/box3d" + "overview.md" + "hello.md" + "samples.md" + "foundation.md" + "collision.md" + "compound.md" + "simulation.md" + "loose_ends.md" + "recording.md" + "character.md" + "reading.md" + ALL + COMMENT "Generate HTML documentation") + \ No newline at end of file diff --git a/docs/character.md b/docs/character.md new file mode 100644 index 0000000..9809a18 --- /dev/null +++ b/docs/character.md @@ -0,0 +1,207 @@ +# Character Mover + +> **Caution**: The character mover API is experimental. + +Box3D provides a geometric character mover: a capsule that exists outside the +rigid body simulation and is driven entirely by application code. Because it is +not a simulated body, you have full control over movement without fighting the +solver, at the cost of having to resolve collisions yourself. This is the style +of mover common in first-person shooters and games with precise platforming. + +![Character Mover](images/mover.png) + +## The Mover Capsule + +The mover is represented by a `b3Capsule` in world space. A capsule is a good +shape for movement because its round profile slides smoothly along edges and +corners without snagging. Give the capsule a meaningful radius — a very thin +capsule behaves poorly with the encroachment handling described below. + +```c +b3Capsule mover; +mover.center1 = (b3Vec3){ 0.0f, 0.35f, 0.0f }; // bottom sphere center +mover.center2 = (b3Vec3){ 0.0f, 1.45f, 0.0f }; // top sphere center +mover.radius = 0.35f; +``` + +The mover has no explicit rotation handling. Slow rotation can be made to work +by updating the capsule each frame, but rapid spinning is not supported. + +## Workflow + +Each frame: + +1. Compute a desired translation from input and physics (gravity, velocity). +2. Call `b3World_CastMover` to find how far the mover can actually travel. +3. Move the capsule by the returned fraction of the desired translation. +4. Call `b3World_CollideMover` to gather all contact planes at the new position. +5. Filter and assemble the planes into a `b3CollisionPlane` array. +6. Call `b3SolvePlanes` to compute a corrected position delta. +7. Apply the delta and call `b3ClipVector` to remove velocity components that + push into surfaces. + +## Swept Motion: b3World_CastMover + +```c +float b3World_CastMover( + b3WorldId worldId, + const b3Capsule* mover, + b3Vec3 translation, + b3QueryFilter filter, + b3MoverFilterFcn* fcn, // optional, may be NULL + void* context +); +``` + +This casts the capsule through the world and returns the fraction `[0, 1]` of +`translation` that can be traveled before hitting something. Multiply the +translation by this fraction to get the safe displacement. + +The cast handles *encroachment*: when the mover starts out touching a surface, +the inner line segment of the capsule may move slightly into that surface without +the full capsule generating an overlap. This lets the mover slide along walls +and floors it is already resting against without stopping dead at the first +frame. + +The optional `b3MoverFilterFcn` callback lets you exclude specific shapes from +the cast (e.g., ignore triggers, teammates, or one-way platforms): + +```c +typedef bool b3MoverFilterFcn(b3ShapeId shapeId, void* context); +// Return true to accept the shape, false to skip it. +``` + +`b3World_CastMover` is intended for movement, not for gathering contact +information. Use `b3World_CollideMover` for that. + +## Contact Planes: b3World_CollideMover + +```c +void b3World_CollideMover( + b3WorldId worldId, + const b3Capsule* mover, + b3QueryFilter filter, + b3PlaneResultFcn* fcn, + void* context +); +``` + +This gathers all surfaces the mover is touching or overlapping and delivers them +via the callback: + +```c +typedef bool b3PlaneResultFcn( + b3ShapeId shapeId, + const b3PlaneResult* plane, + int planeCount, + void* context +); +// Return true to continue gathering planes. +``` + +`b3PlaneResult` carries the contact plane and a world-space contact point: + +```c +typedef struct b3PlaneResult { + b3Plane plane; // normal + offset: separation = dot(normal, p) - offset + b3Vec3 point; +} b3PlaneResult; +``` + +The mover is treated as having fixed rotation, so only planes are needed — no +full contact manifolds. + +### Per-Body Query: b3Body_CollideMover + +When you need to test the mover against a single specific body (useful for +moving platforms or elevators): + +```c +int b3Body_CollideMover( + b3BodyId bodyId, + b3BodyPlaneResult* bodyPlanes, + int planeCapacity, + const b3Capsule* mover, + b3QueryFilter filter, + b3Transform bodyTransform +); +``` + +Returns the number of planes written into `bodyPlanes`. Each entry pairs the +originating `b3ShapeId` with a `b3PlaneResult`. + +## Resolving Overlap: b3SolvePlanes + +Convert the raw `b3PlaneResult` values from `b3World_CollideMover` into +`b3CollisionPlane` entries and call: + +```c +typedef struct b3CollisionPlane { + b3Plane plane; + float pushLimit; // FLT_MAX for rigid; smaller values allow soft penetration + float push; // output: how much the solver pushed along this plane + bool clipVelocity; // set true to clip velocity against this plane +} b3CollisionPlane; + +b3PlaneSolverResult b3SolvePlanes( + b3Vec3 targetDelta, + b3CollisionPlane* planes, + int count +); +``` + +`b3SolvePlanes` finds the position delta closest to `targetDelta` that satisfies +all planes. The result contains the corrected `delta` and an `iterationCount`. + +`pushLimit` controls softness. `FLT_MAX` gives a rigid surface. A smaller value +allows the mover to push through — useful for other players, enemies, or doors +that should yield but not fully block. + +## Velocity Clipping: b3ClipVector + +After resolving position, clip the mover's velocity so it does not keep +accelerating into blocked directions: + +```c +b3Vec3 b3ClipVector(b3Vec3 vector, const b3CollisionPlane* planes, int count); +``` + +This removes the components of `vector` that push into any plane where +`clipVelocity` is true. Without this, velocity accumulates every frame the +mover is pressed against a surface. + +## Putting It Together + +```c +// 1. Desired translation from input + gravity integration +b3Vec3 translation = b3MulSV(timeStep, velocity); + +// 2. Swept cast +float fraction = b3World_CastMover(worldId, &mover, translation, filter, NULL, NULL); +b3Vec3 safeDelta = b3MulSV(fraction, translation); + +// 3. Move the capsule +mover.center1 = b3Add(mover.center1, safeDelta); +mover.center2 = b3Add(mover.center2, safeDelta); + +// 4. Gather contact planes +#define MAX_PLANES 16 +b3CollisionPlane collisionPlanes[MAX_PLANES]; +int planeCount = 0; + +// (user callback stores planes into collisionPlanes / planeCount) +b3World_CollideMover(worldId, &mover, filter, MyPlaneCallback, &planeCtx); + +// 5. Solve planes +b3PlaneSolverResult result = b3SolvePlanes(b3Vec3_zero, collisionPlanes, planeCount); + +// 6. Apply correction +mover.center1 = b3Add(mover.center1, result.delta); +mover.center2 = b3Add(mover.center2, result.delta); + +// 7. Clip velocity +velocity = b3ClipVector(velocity, collisionPlanes, planeCount); +``` + +The `Mover` sample in the samples application shows a complete implementation +including acceleration, friction, jumping, and a pogo stick. diff --git a/docs/collision.md b/docs/collision.md new file mode 100644 index 0000000..b36611a --- /dev/null +++ b/docs/collision.md @@ -0,0 +1,502 @@ +# Collision + +Box3D provides geometric types and functions. These include: +- primitives: spheres, capsules, and convex hulls +- triangle meshes and height fields for static terrain +- convex hull construction from point clouds +- mass and bounding box computation +- local ray and shape casts +- contact manifolds +- shape distance (GJK) +- time of impact +- dynamic bounding volume tree + +The collision interface is designed to be usable outside of rigid body simulation. +For example, you can use the dynamic tree for other aspects of your game besides physics. + +The main purpose of Box3D is rigid body simulation, so the collision module only +contains features that are also useful in the physics engine. + +## Shape Primitives + +Shape primitives describe collision geometry and may be used independently of +physics simulation. At a minimum, you should understand how to create primitives +that can later be attached to rigid bodies. + +Box3D shape primitives support several operations: +- Test a point or proxy for overlap with the primitive +- Perform a ray cast against the primitive +- Compute the primitive's bounding box +- Compute the mass properties of the primitive + +### Spheres + +Spheres have a center and radius. Spheres are solid. + + + +```c +b3Sphere sphere; +sphere.center = (b3Vec3){2.0f, 3.0f, 0.0f}; +sphere.radius = 0.5f; +``` + +You can also initialize a sphere inline: + +```c +b3Sphere sphere = {{2.0f, 3.0f, 0.0f}, 0.5f}; +``` + +### Capsules + +Capsules have two center points and a radius. The center points are the centers of two +hemispheres connected by a cylinder. + +![Capsule](images/capsule.svg) + +```c +b3Capsule capsule; +capsule.center1 = (b3Vec3){0.0f, -1.0f, 0.0f}; +capsule.center2 = (b3Vec3){0.0f, 1.0f, 0.0f}; +capsule.radius = 0.25f; +``` + +### Convex Hulls + +Box3D convex hulls are solid convex polyhedra represented by the `b3Hull` type. A shape is +convex when all line segments connecting two interior points remain inside the shape. + + + +The most common hull is a box. Use `b3MakeBoxHull` for an axis-aligned box and +`b3MakeCubeHull` for a cube. The values are half-extents (half-widths): + +```c +b3BoxHull box = b3MakeBoxHull(0.5f, 1.0f, 0.5f); // half-widths hx, hy, hz +b3BoxHull cube = b3MakeCubeHull(0.5f); // uniform half-width +``` + +`b3BoxHull` stores everything inline — do not call `b3DestroyHull` on one. +Its `.base` member is a `b3Hull` that you pass to shape creation functions. + +For a box that is offset or rotated from the body origin: + +```c +b3Transform localTransform = { offset, rotation }; +b3BoxHull rotatedBox = b3MakeTransformedBoxHull(0.5f, 1.0f, 0.5f, localTransform); +``` + +For arbitrary convex geometry, provide a point cloud and let Box3D compute the hull: + +```c +b3Hull* hull = b3CreateHull(points, pointCount, maxVertexCount); +if (hull == NULL) +{ + // degenerate input: coincident or coplanar points, or insufficient volume +} +// ... use hull ... +b3DestroyHull(hull); +``` + +`maxVertexCount` limits the output complexity; pass the same value as `pointCount` +to allow the full hull. `b3CreateHull` returns `NULL` on degenerate input (e.g. fewer +than four non-coplanar points, or nearly-zero volume). Always check before using it. + +Box3D also provides helpers to create cylindrical and conical hulls: + +```c +b3Hull* cylinder = b3CreateCylinder(height, radius, yOffset, sides); +b3Hull* cone = b3CreateCone(height, radius1, radius2, slices); +b3DestroyHull(cylinder); +b3DestroyHull(cone); +``` + +Hulls created with `b3CreateCylinder`, `b3CreateCone`, and `b3CreateHull` are +heap-allocated and must be freed with `b3DestroyHull`. `b3BoxHull` values are +stack/struct-allocated and must not be freed. + +### Triangle Meshes + +Triangle meshes let you describe concave or open surfaces using a triangle soup. +They are intended for static geometry: `b3CreateMeshShape` only creates contacts +on static bodies. + +The mesh is built from a `b3MeshDef` and cooked into a `b3MeshData` that contains +an internal BVH for efficient collision queries: + +```c +b3MeshDef def = {0}; +def.vertices = myVerts; +def.vertexCount = myVertCount; +def.indices = myIndices; // 3 per triangle +def.triangleCount = myTriCount; +def.weldVertices = true; +def.identifyEdges = true; // adjacency info for smooth inter-triangle normals + +b3MeshData* mesh = b3CreateMesh(&def, NULL, 0); +``` + +Pass `identifyEdges = true` when triangles share edges so Box3D can suppress +internal-edge collisions between adjacent triangles (the 3D equivalent of ghost +collision handling on polygon chains). + +The `b3Mesh` struct pairs a `b3MeshData` pointer with a scale vector: + +```c +b3Mesh meshShape; +meshShape.data = mesh; +meshShape.scale = (b3Vec3){1.0f, 1.0f, 1.0f}; +``` + +Scale may be non-uniform and may have negative components, but no component may +be zero. + +Per-triangle surface materials are supported. Provide a `b3SurfaceMaterial` array +in `b3ShapeDef::materials` and an index array in `b3MeshDef::materialIndices`: + +```c +b3SurfaceMaterial materials[2] = { ... }; +def.materialIndices = perTriangleMaterialIndex; // uint8_t, 1 per triangle + +b3ShapeDef shapeDef = b3DefaultShapeDef(); +shapeDef.materials = materials; +shapeDef.materialCount = 2; + +b3ShapeId id = b3CreateMeshShape(bodyId, &shapeDef, mesh, scale); +``` + +Destroy the mesh data when no longer needed, after the shape referencing it has +been destroyed: + +```c +b3DestroyMesh(mesh); +``` + +Box3D provides factory helpers for common mesh configurations: +`b3CreateGridMesh`, `b3CreateWaveMesh`, `b3CreateBoxMesh`, and others. + +### Height Fields + +Height fields describe terrain as a regular grid of sample heights. Like meshes, +they are only valid on static bodies. + +```c +b3HeightFieldDef def = {0}; +def.heights = heightSamples; // float[countX * countZ] +def.countX = 256; +def.countZ = 256; +def.scale = (b3Vec3){1.0f, 1.0f, 1.0f}; +def.globalMinimumHeight = -10.0f; +def.globalMaximumHeight = 50.0f; + +b3HeightField* hf = b3CreateHeightField(&def); +b3ShapeId id = b3CreateHeightFieldShape(bodyId, &shapeDef, hf); +``` + +`scale` controls cell spacing (x/z) and height scale (y). Setting a material index +to `B3_HEIGHT_FIELD_HOLE` (0xFF) punches a hole in that grid cell, useful for +cave entrances and tunnels. + +When placing multiple height fields side by side, give all of them the same +`globalMinimumHeight` and `globalMaximumHeight` so compressed heights quantize +identically and the seams line up. + +Destroy the height field after the shape referencing it has been destroyed: + +```c +b3DestroyHeightField(hf); +``` + +### Compound Shapes + +A compound shape aggregates spheres, capsules, hulls, and meshes into a single +static collision shape. Compounds are only allowed on static bodies. They are +designed for offline baking and open-world streaming — see the dedicated +[compound](compound.md) page for the full API and usage pattern. + +## Geometric Queries + +### Shape Point Test + +Box3D does not expose standalone `b3PointInShape` functions. Point overlap is +expressed through the `b3ShapeProxy` abstraction that GJK uses. A degenerate +proxy — a single point with zero radius — serves as a point test: + +```c +b3Vec3 queryPoint = {5.0f, 2.0f, 1.0f}; +b3ShapeProxy proxy; +proxy.points = &queryPoint; +proxy.count = 1; +proxy.radius = 0.0f; + +b3Transform shapeTransform = b3Transform_identity; +bool hit = b3OverlapHull(&myHull, shapeTransform, &proxy); +``` + +The same pattern works with `b3OverlapSphere`, `b3OverlapCapsule`, +`b3OverlapMesh`, and `b3OverlapHeightField`. + +### Ray Cast + +Cast a ray at a shape to get the point of first intersection and the surface normal. + +> **Caution**: No hit will register if the ray starts inside a convex shape such +> as a sphere or hull. Convex shapes are treated as solid. + +![Ray cast](images/raycast.svg) + +```c +b3RayCastInput input = {0}; +input.origin = (b3Vec3){0.0f, 10.0f, 0.0f}; +input.translation = (b3Vec3){0.0f, -20.0f, 0.0f}; +input.maxFraction = 1.0f; + +b3CastOutput output = b3RayCastHull(&myHull, &input); +if (output.hit) +{ + // output.point, output.normal, output.fraction +} +``` + +Per-shape ray cast functions: `b3RayCastSphere`, `b3RayCastCapsule`, +`b3RayCastHull`, `b3RayCastMesh`, `b3RayCastHeightField`, `b3RayCastCompound`. +All operate in the shape's local space. Use `b3IsValidRay` to validate input +before calling. + +To cast against the full simulation world, use `b3World_CastRay` or the +convenience function `b3World_CastRayClosest`. + +### Shape Cast + +A shape cast sweeps an abstract point cloud (a `b3ShapeProxy`) through space and +finds where it first contacts another shape. A sphere is a single point with +a non-zero radius; a capsule is two points with a radius; a box is eight points +with zero radius. + +```c +b3Vec3 proxyPoints[] = {{-0.5f, -0.5f, -0.5f}, {0.5f, 0.5f, 0.5f}}; + +b3ShapeCastInput input = {0}; +input.proxy.points = proxyPoints; +input.proxy.count = 2; +input.proxy.radius = 0.1f; +input.translation = (b3Vec3){0.0f, -5.0f, 0.0f}; +input.maxFraction = 1.0f; + +b3CastOutput output = b3ShapeCastHull(&myHull, &input); +if (output.hit) +{ + // output.point, output.normal, output.fraction +} +``` + +Per-shape cast functions: `b3ShapeCastSphere`, `b3ShapeCastCapsule`, +`b3ShapeCastHull`, `b3ShapeCastMesh`, `b3ShapeCastHeightField`, +`b3ShapeCastCompound`. + +For the most general form — sweeping one proxy against another — use +`b3ShapeCast` with a `b3ShapeCastPairInput`. All shape cast functions call this +internally. + +### Distance + +`b3ShapeDistance` computes the closest points and separation distance between two +shapes, each expressed as a `b3ShapeProxy`. It uses the GJK algorithm. + +![Distance function](images/distance.svg) + +```c +b3DistanceInput input = {0}; +input.proxyA = proxyA; // b3ShapeProxy for shape A +input.proxyB = proxyB; // b3ShapeProxy for shape B +input.transformA = transformA; +input.transformB = transformB; +input.useRadii = true; + +b3SimplexCache cache = b3_emptyDistanceCache; +b3DistanceOutput output = b3ShapeDistance(&input, &cache, NULL, 0); +// output.distance, output.pointA, output.pointB, output.normal +``` + +The simplex cache warm-starts the algorithm when shapes move by small amounts +between calls. On the first call zero-initialize the cache (or use +`b3_emptyDistanceCache`). + +### Time of Impact + +If two shapes move fast they may tunnel through each other in a single time step. + +![Tunneling](images/tunneling2.svg) + +`b3TimeOfImpact` finds the earliest time at which two swept shapes touch. Box3D +uses this internally to prevent dynamic bodies from tunneling through static geometry. + +![Captured collision](images/captured_toi.svg) + +![Missed collision](images/missed_toi.svg) + +The algorithm identifies an initial separating axis and advances the shapes along +it until they touch or pass each other. It may miss collisions that only become +apparent at the final positions, but those tend to be glancing contacts that rarely +matter in practice. + +```c +b3TOIInput input = {0}; +input.proxyA = proxyA; +input.proxyB = proxyB; +input.sweepA = sweepA; // b3Sweep: localCenter, c1, c2, q1, q2 +input.sweepB = sweepB; +input.maxFraction = 1.0f; + +b3TOIOutput output = b3TimeOfImpact(&input); +if (output.state == b3_toiStateHit) +{ + // output.fraction is the time of impact in [0, maxFraction] + // output.point and output.normal give the contact geometry +} +``` + +`b3Sweep` describes a rigid body's motion as a translation of the center of mass +plus a quaternion rotation, interpolated from `(c1, q1)` to `(c2, q2)`. Use +`b3GetSweepTransform` to evaluate the transform at any fraction. + +### Contact Manifolds + +Box3D computes contact points for overlapping shapes. In 3D, hull-hull contact +can produce up to `B3_MAX_MANIFOLD_POINTS` (4) points. All points share the same +contact normal so Box3D groups them into a manifold. The contact solver uses +this for stable stacking. + +![Contact manifold](images/manifolds.svg) + +Normally you do not compute manifolds directly — you use the contact data +returned by the simulation. The `b3Manifold` struct contains: +- `normal`: unit normal from shape A toward shape B +- `points[B3_MAX_MANIFOLD_POINTS]`: contact points with separation, impulses, + and feature ids +- `pointCount`: 0–4 valid points +- `frictionImpulse`, `twistImpulse`, `rollingImpulse`: accumulated friction state + +For direct use, the low-level collide functions produce a `b3LocalManifold` in +the frame of shape A: + +```c +b3LocalManifoldPoint points[B3_MAX_MANIFOLD_POINTS]; +b3LocalManifold manifold; +manifold.points = points; + +b3SATCache cache = {0}; +b3CollideHulls(&manifold, B3_MAX_MANIFOLD_POINTS, + &hullA, &hullB, transformBtoA, &cache); +``` + +Available collide functions: +- `b3CollideSpheres` +- `b3CollideCapsuleAndSphere` +- `b3CollideCapsules` +- `b3CollideHullAndSphere` +- `b3CollideHullAndCapsule` +- `b3CollideHulls` +- `b3CollideCapsuleAndTriangle` +- `b3CollideHullAndTriangle` +- `b3CollideSphereAndTriangle` + +The SAT cache in `b3CollideHulls` warm-starts the separating axis search between +frames, the same idea as the simplex cache for GJK distance. + +Box3D uses speculative collision: some contact points in a `b3Manifold` may +report a positive (separated) `separation`. Check `totalNormalImpulse` to +determine whether a speculative point actually had an interaction during the step. + +![Skin collision](images/skin_collision.svg) + +## Dynamic Tree + +`b3DynamicTree` organizes large numbers of AABBs into a hierarchical binary tree +for fast ray casts and region queries. Box3D uses it internally to manage the +broad phase, but it is also available for organizing spatial game data unrelated +to physics. + +Each tree node stores a `b3AABB` and a 64-bit `userData` value. Internal nodes +have two children; leaf nodes are proxies you manage directly. + +```c +// Create a tree with an initial proxy capacity +b3DynamicTree tree = b3DynamicTree_Create(256); + +// Insert a proxy +b3AABB aabb = { lowerBound, upperBound }; +int proxyId = b3DynamicTree_CreateProxy(&tree, aabb, categoryBits, userData); + +// Move it +b3DynamicTree_MoveProxy(&tree, proxyId, newAabb); + +// Remove it +b3DynamicTree_DestroyProxy(&tree, proxyId); + +// Done +b3DynamicTree_Destroy(&tree); +``` + +**Category bits** allow broad-phase filtering without invoking the callback. +A proxy is only visited if `(maskBits & node->categoryBits) != 0` (or if +`requireAllBits` is set, the AND must equal `maskBits`). + +### AABB Query + +Find all proxies whose AABBs overlap a query box: + +```c +b3TreeStats stats = b3DynamicTree_Query( + &tree, queryAabb, maskBits, requireAllBits, myQueryCallback, context); +``` + +The callback receives `proxyId` and `userData` and returns `true` to continue. + +### Closest Query + +Find the proxy closest to a point: + +```c +float minDistSqr = FLT_MAX; +b3TreeStats stats = b3DynamicTree_QueryClosest( + &tree, point, maskBits, requireAllBits, + myClosestCallback, context, &minDistSqr); +``` + +The callback receives the current minimum squared distance and returns the +squared distance to the user object inside the proxy, allowing the tree to +prune distant branches. + +### Ray Cast + +```c +b3TreeStats stats = b3DynamicTree_RayCast( + &tree, &rayInput, maskBits, requireAllBits, + myRayCastCallback, context); +``` + +The callback returns a new `maxFraction`. Return 0 to stop, a fraction less +than `input->maxFraction` to clip the ray (e.g. for closest-hit semantics), +or `input->maxFraction` to continue unclipped. + +### Shape Cast + +```c +b3TreeStats stats = b3DynamicTree_ShapeCast( + &tree, &shapeCastInput, maskBits, requireAllBits, + myShapeCastCallback, context); +``` + +![Ray cast](images/raycast.svg) + +![Overlap test](images/overlap_test.svg) + +`b3TreeStats` reports `nodeVisits` and `leafVisits` for performance profiling. +The tree can be rebuilt with `b3DynamicTree_Rebuild` to reclaim quality after +many insertions, and saved/loaded with `b3DynamicTree_Save` / `b3DynamicTree_Load` +for debugging. + +Normally you will not use `b3DynamicTree` directly. For world-level ray casts and +overlap queries use `b3World_CastRay`, `b3World_OverlapAABB`, and +`b3World_OverlapShape`. See the `DynamicTree` sample for direct usage examples. diff --git a/docs/compound.md b/docs/compound.md new file mode 100644 index 0000000..82d79fe --- /dev/null +++ b/docs/compound.md @@ -0,0 +1,157 @@ +# Compound Shapes + +A compound is a single immutable shape that aggregates many child primitives — +spheres, capsules, convex hulls, and triangle meshes — under one internal AABB +tree. To the simulation it appears as one shape, but collision queries descend +the internal tree and test individual children, so the cost scales with what is +actually touched rather than the total child count. + +## Design Intent + +Compounds are **static-body only** and **immutable after creation**. They are +not a runtime mutation primitive. The intended workflow is: + +1. Author geometry offline (level mesh, terrain tile, building shell). +2. Bake the compound once with `b3CreateCompound`. +3. Serialize it to a byte buffer with `b3ConvertCompoundToBytes` and store it on + disk or in a streaming cache. +4. At runtime, load the bytes and reconstruct the compound with + `b3ConvertBytesToCompound`, then attach it to a static body. + +This makes compounds well-suited to open-world streaming: tiles are baked +offline, kept in memory as flat byte buffers (which the engine uses directly +without copying), and attached to static bodies when a region loads, then +detached when it unloads. + +Do not use a compound on dynamic or kinematic bodies — `b3CreateCompoundShape` +enforces static-only attachment. + +## Building a Compound + +Fill a `b3CompoundDef` with arrays of child-shape descriptors: + +```c +// Child type descriptors +b3CompoundCapsuleDef capsuleDefs[N_CAPSULES]; +b3CompoundHullDef hullDefs[N_HULLS]; +b3CompoundMeshDef meshDefs[N_MESHES]; +b3CompoundSphereDef sphereDefs[N_SPHERES]; + +// Fill capsuleDefs[i].capsule, .material ... +// Fill hullDefs[i].hull, .transform, .material ... +// Fill meshDefs[i].meshData, .transform, .scale, .materials, .materialCount ... +// Fill sphereDefs[i].sphere, .material ... + +b3CompoundDef def; +def.capsules = capsuleDefs; def.capsuleCount = N_CAPSULES; +def.hulls = hullDefs; def.hullCount = N_HULLS; +def.meshes = meshDefs; def.meshCount = N_MESHES; +def.spheres = sphereDefs; def.sphereCount = N_SPHERES; + +b3Compound* compound = b3CreateCompound(&def); +``` + +`b3CreateCompound` clones all input data into the compound. The source arrays +can be freed immediately after the call. + +Mesh children share the mesh pointer rather than cloning triangle data — the +`b3MeshData` must remain valid for the lifetime of the compound. Triangle +materials are limited to `B3_MAX_COMPOUND_MESH_MATERIALS` (4) slots per mesh +child; if your mesh needs more materials, attach it as a standalone mesh shape +on the static body instead. + +## The b3Compound Structure + +```c +typedef struct b3Compound { + uint64_t version; // versioned against the tree/mesh/hull formats + int byteCount; // total size when serialized + // internal tree, child arrays, material table + // ... (treat as opaque) +} b3Compound; +``` + +`version` is a compile-time constant (`B3_COMPOUND_VERSION`) that incorporates +the dynamic tree, mesh, and hull format versions. A version mismatch at load +time means the bytes were baked with a different engine version and cannot be +used. + +## Serialization + +Convert a live compound to a self-contained byte buffer: + +```c +uint8_t* bytes = b3ConvertCompoundToBytes(compound); +// compound is now in an unusable state; its pointers have been nullified. +// Write bytes[0 .. compound->byteCount - 1] to disk. +``` + +Reconstruct from bytes at runtime (zero-copy; bytes must remain in scope): + +```c +b3Compound* compound = b3ConvertBytesToCompound(bytes, byteCount); +``` + +The bytes are mutated in place to fixup internal pointers. Multiple static +bodies can use the same byte buffer simultaneously (instancing), since the +compound itself holds no per-body state. + +## Attaching to a Static Body + +```c +b3BodyDef bodyDef = b3DefaultBodyDef(); +bodyDef.type = b3_staticBody; +bodyDef.position = tileOrigin; +b3BodyId bodyId = b3CreateBody(worldId, &bodyDef); + +b3ShapeDef shapeDef = b3DefaultShapeDef(); +b3ShapeId shapeId = b3CreateCompoundShape(bodyId, &shapeDef, compound); +``` + +`b3CreateCompoundShape` asserts that the body is static. + +## Querying a Compound + +Compute the world AABB: + +```c +b3AABB aabb = b3ComputeCompoundAABB(compound, bodyTransform); +``` + +Query child shapes by AABB: + +```c +typedef bool b3CompoundQueryFcn(const b3Compound* compound, int childIndex, void* context); + +b3QueryCompound(compound, queryAABB, MyChildCallback, ctx); +``` + +Access a specific child by index: + +```c +b3ChildShape child = b3GetCompoundChild(compound, childIndex); +// child.type tells you capsule / hull / mesh / sphere +// child.transform is the child's local transform within the compound +``` + +Individual typed accessors are also available: + +```c +b3CompoundCapsule cc = b3GetCompoundCapsule(compound, i); +b3CompoundHull ch = b3GetCompoundHull(compound, i); +b3CompoundMesh cm = b3GetCompoundMesh(compound, i); +b3CompoundSphere cs = b3GetCompoundSphere(compound, i); +const b3SurfaceMaterial* mats = b3GetCompoundMaterials(compound); +``` + +## Teardown + +Destroy a live compound (not needed if you are using the byte-buffer path, where +you manage the buffer lifetime yourself): + +```c +b3DestroyCompound(compound); +``` + +Do not call `b3DestroyCompound` on a compound reconstructed from bytes with +`b3ConvertBytesToCompound` — free the byte buffer instead. diff --git a/docs/extra.css b/docs/extra.css new file mode 100644 index 0000000..fb75491 --- /dev/null +++ b/docs/extra.css @@ -0,0 +1,85 @@ +/* +Box2D accents on top of doxygen's built-in dark theme (HTML_COLORSTYLE DARK). +Doxygen 1.17 bakes a complete dark palette, so this only restores the Box2D +cyan accent and backs the transparent SVG diagrams. Loaded after doxygen.css, +so plain overrides win by order. +*/ + +/* Box2D cyan for links, symbol cross references, and section headings */ +a, a:link, a:visited, +.contents a:visited, +a.el, a.el:visited, a.code, a.code:visited, a.line, a.line:visited, +a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited { + color: #67d8ef; +} + +h2.groupheader, +.memtitle { + color: #67d8ef; +} + +h1.glow, h2.glow, h3.glow, h4.glow, h5.glow, h6.glow { + text-shadow: 0 0 15px #67d8ef; +} + +/* SVG diagrams are transparent, so back them with a light plate to stay legible on a dark page */ +.image { + background-color: #CCCCCC; + border: 10px solid #CCCCCC; +} + +img.inline { + background-color: #CCCCCC; + border: 10px solid #CCCCCC; + margin: 0px; +} + +/* Caption sits on the light plate */ +.caption { + padding-top: 10px; + color: black; +} + +/* Cap line length for readability */ +div.contents { + max-width: 1000px; +} + +/* Soften contrast. doxygen 1.17's dark is near black, restore the Box2D grays */ +body { + background-color: #292a2d; + color: #D8D8D8; +} + +#titlearea, +div.header, +#side-nav, +#nav-tree { + background-color: #292a2d; +} + +/* Panels and selection sit one step lighter than the page */ +#nav-tree .selected, +div.fragment, pre.fragment, span.tt, +.memItemLeft, .memItemRight, .memTemplParams, +.memtitle, .memname, .memname td, +.memproto, dl.reflist dt, +div.toc, +table.doxtable th, .fieldtable th, +th.markdownTableHeadLeft, th.markdownTableHeadRight, th.markdownTableHeadCenter, th.markdownTableHeadNone, +table.doxtable tr:nth-child(even) td, +.directory tr.even { + background-color: #32363d; +} + +.directory tr.odd { + background-color: #292a2d; +} + +/* Caution callouts, filled olive box with a full border and real padding */ +blockquote.doxtable { + background-color: #456114; + border: 1px solid #000000; + padding: 12px 16px; + margin: 10px 24px 10px 4px; +} diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..d504ef7 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,140 @@ +# FAQ + +## What is Box3D? +Box3D is a feature rich 3D rigid body physics engine, written in C17 by Erin Catto. It has been used in games and game engines +as a 3D counterpart to the well-established Box2D engine. + +Box3D uses the [MIT license](https://en.wikipedia.org/wiki/MIT_License) and can be used free of charge. Credit +should be included if possible. Support is [appreciated](https://github.com/sponsors/erincatto). + +## What platforms does Box3D support? +Box3D is developed using C17. It is portable and can be compiled for any platform with a conforming C17 compiler. + +Erin Catto maintains the C version. Community ports and bindings for other languages are not officially supported. + +## Who makes it? +Erin Catto is the creator and primary author of Box3D. It is an open source project, and accepts community feedback via +[GitHub Issues](https://github.com/erincatto/box3d/issues) and +[GitHub Discussions](https://github.com/erincatto/box3d/discussions). + +## How do I get help? +You should read the documentation and the rest of this FAQ first. Also, you should study the examples included in the source +distribution. Then you can visit the [Discord](https://discord.gg/NKYgCBP) to ask any remaining questions. + +Please do not message or email Erin Catto directly for support. It is best to ask questions on the Discord server so that +everyone can benefit from the discussion. + +## Documentation + +### Why isn't a feature documented? +If you grab the latest code from the git main branch you will likely find features that are not documented in the manual. +New features are added to the manual after they are mature and a new point release is imminent. However, all major features +added to Box3D are accompanied by example code in the samples application to test the feature and show the intended usage. + +## Prerequisites + +### Programming +You should have a working knowledge of C before you use Box3D. You should understand functions, structures, and pointers. +There are plenty of resources on the web for learning C. You should also understand your development environment: +compilation, linking, and debugging. + +### Math and Physics +You should have a basic knowledge of rigid bodies, force, torque, and impulses. In 3D you will also encounter quaternions +for orientation and 3x3 inertia tensors for rotational dynamics. If you come across a math or physics concept you don't +understand, please read about it on Wikipedia. Visit this [page](https://box2d.org/publications/) if you want a deeper +knowledge of the algorithms used in Box3D. + +## API + +### What units does Box3D use? +Box3D is tuned for meters-kilograms-seconds (MKS). This is recommended as the unit system for your game. However, you may +use different units if you are careful. Call `b3SetLengthUnitsPerMeter()` at startup to change the length unit. + +### What coordinate system does Box3D use? +Box3D has no built-in notion of up. The gravity vector in `b3WorldDef` can point in any direction. The default is +`(0, -10, 0)` (negative Y is down) but you can set it to whatever suits your application. + +### Why don't you use this awesome language? +Box3D is designed to be portable and easy to wrap with other languages, so I decided to use C17. I used C17 to get +support for atomics. + +### Can I use Box3D in a DLL? +Yes. See the CMake option `BUILD_SHARED_LIBS`. + +### Is Box3D thread-safe? +No. Box3D will likely never be fully thread-safe from the outside. Box3D has a large API and trying to make such an API +thread-safe would have a large performance and complexity impact. However, you can call read-only functions from multiple +threads. For example, all the spatial query functions are read-only. + +Box3D does use multithreading internally during `b3World_Step`. You supply your own task system via the `enqueueTask` and +`finishTask` callbacks in `b3WorldDef`. + +## Build Issues + +### Why doesn't my code compile and/or link? +There are many reasons why a build can go bad. Here are a few that have come up: +* Using old Box3D headers with new code +* Not linking the Box3D library with your application +* Using old project files that don't include some new source files + +## Rendering + +### What are Box3D's rendering capabilities? +Box3D is only a physics engine. How you draw stuff is up to you. + +### But the samples application draws stuff +Visualization is very important for debugging collision and physics. The samples application helps test Box3D and gives +you examples of how to use Box3D. The samples are not part of the Box3D library. + +### How do I draw shapes? +Fill out a `b3DebugDraw` struct with your drawing callbacks and call `b3World_Draw(worldId, &draw, maskBits)`. +The mask bits let you filter which shape categories are drawn. + +## Accuracy +Box3D uses approximate methods for a few reasons. +* Performance +* Some differential equations don't have known solutions +* Some constraints cannot be determined uniquely + +What this means is that constraints are not perfectly rigid and sometimes you will see some bounce even when the restitution +is zero. Box3D uses [Gauss-Seidel](https://en.wikipedia.org/wiki/Gauss%E2%80%93Seidel_method) to approximately solve +constraints. Box3D also uses [Semi-implicit Euler](https://en.wikipedia.org/wiki/Semi-implicit_Euler_method) to +approximately solve the differential equations. Box3D also does not have exact collision between dynamic shapes. Slow +moving shapes may have small overlap for a few time steps. In extreme stacking scenarios, shapes may have sustained +overlap. + +## Making Games + +### Tile / Voxel Based Environments +Using many boxes for terrain may not work well because box-like characters can get snagged on internal corners. Box3D +provides capsules and convex hulls that may work better for characters. Consider the character mover API +(`b3World_CastMover`, `b3World_CollideMover`) for smooth first/third person movement. + +### Asteroid Type Coordinate Systems +Box3D does not have any support for coordinate frame wrapping. You would likely need to customize Box3D for this purpose. + +## Determinism + +### Is Box3D deterministic? +For the same input Box3D will reproduce any simulation. Box3D does not use any random numbers nor base any computation +on random events (such as timers, etc). + +Box3D is also deterministic under multithreading. A simulation using two threads will give the same result as eight threads. + +Box3D inherits cross-platform determinism from its design: floating-point contraction is disabled (`-ffp-contract=off`) +and IEEE 754 arithmetic is relied upon consistently. + +However, Box3D does not have rollback determinism. There is no mechanism to set a world back to a prior state and then +resume simulation expecting identical results. Box3D caches a lot of internal state to improve simulation stability and +performance. + +### But I really want determinism +This naturally leads to the question of fixed-point math. Box3D does not support fixed-point math. Fixed-point math is +slower and more tedious to develop, and I have chosen not to use it. + +## What are the common mistakes made by new users? +* Using non-metric units instead of meters +* Expecting Box3D to give pixel-perfect results +* Testing their code in release mode (always use Debug for testing — it enables assertions and validation) +* Not learning C before using Box3D +* Confusing b2 (Box2D) and b3 (Box3D) symbols when reading documentation diff --git a/docs/foundation.md b/docs/foundation.md new file mode 100644 index 0000000..71a5a17 --- /dev/null +++ b/docs/foundation.md @@ -0,0 +1,230 @@ +# Foundations +Box3D provides minimal base functionality for allocation hooks and vector math. The C interface +allows most runtime data and types to be defined internally in the `src` folder. + +## Assertions +Box3D will assert on bad input. This includes things like sending in NaN or infinity for values. +It will assert if you use negative values for things that should only be positive, such as density. + +Box3D will also assert if an internal bug is detected. For this reason, it is advisable to build +Box3D from source. The library compiles in about a second. + +You may wish to capture assertions in your application. In that case use `b3SetAssertFcn()`. This +lets you override the debugger break and/or perform your own error handling. + +## Allocation +Box3D uses memory efficiently and minimizes per-frame allocations by pooling memory. The engine +quickly adapts to the simulation size. After the first step or two of simulation there should be +no further per-frame allocations. + +As bodies, shapes, and joints are created and destroyed, their memory is recycled. Internally all +this data is stored in contiguous arrays. When an object is destroyed, the array element is marked +empty. When an object is created it fills an empty slot via an efficient free list. + +Once the internal memory pools are initially filled, the only allocations should be for sleeping +islands, since their data is copied out of the main simulation. Those allocations are generally +infrequent. + +You can provide a custom allocator using `b3SetAllocator()` and query the total bytes currently +allocated using `b3GetByteCount()`. + +## Version +The `b3Version` structure holds the current version so you can query it at run-time using +`b3GetVersion()`. + +```c +b3Version version = b3GetVersion(); +printf("Box3D version %d.%d.%d\n", version.major, version.minor, version.revision); +``` + +## Vector Math +Box3D includes a vector math library covering types `b3Vec3`, `b3Quat`, `b3Transform`, +`b3Matrix3`, and `b3AABB`. The library is designed to suit the internal needs of Box3D +and its interface. All members are exposed, so you can use them freely in your application. + +### b3Vec3 +Three-component float vector with fields `x`, `y`, `z`. Useful constants and operations: + +```c +b3Vec3 a = {1.0f, 0.0f, 0.0f}; // inline init +b3Vec3 z = b3Vec3_zero; // {0,0,0} +b3Vec3 c = b3Add(a, b); // component-wise add +b3Vec3 d = b3Sub(a, b); // subtract +b3Vec3 e = b3MulSV(2.0f, a); // scalar * vector +float f = b3Dot(a, b); // dot product +b3Vec3 g = b3Cross(a, b); // cross product +float h = b3Length(a); // Euclidean length +b3Vec3 n = b3Normalize(a); // unit vector +b3Vec3 p = b3Perp(a); // any perpendicular unit vector +b3Vec3 q = b3Lerp(a, b, 0.5f); // linear interpolation +``` + +### b3Quat +Unit quaternion representing orientation. Stored as a vector part `q.v` (x, y, z) and a +scalar part `q.s`. The identity quaternion is `b3Quat_identity`. + +Useful operations: + +```c +// Construct from axis (must be unit) and angle in radians +b3Quat q = b3MakeQuatFromAxisAngle(axis, radians); + +// Rotate a vector +b3Vec3 r = b3RotateVector(q, v); + +// Inverse-rotate a vector (equivalent to rotating by the conjugate) +b3Vec3 s = b3InvRotateVector(q, v); + +// Compose two rotations: apply q2 first, then q1 +b3Quat qc = b3MulQuat(q1, q2); + +// Conjugate (same as inverse for a unit quaternion) +b3Quat qi = b3Conjugate(q); + +// Extract axis-angle +float angle; +b3Vec3 axis = b3GetAxisAngle(&angle, q); + +// Total rotation angle (ignoring axis) +float totalAngle = b3GetQuatAngle(q); + +// Convert to rotation matrix +b3Matrix3 m = b3MakeMatrixFromQuat(q); + +// Normalized linear interpolation +b3Quat qi = b3NLerp(q1, q2, alpha); +``` + +Because orientation in 3D is three-dimensional, there is no single scalar angle as there was +in 2D. Always work with the full quaternion or the derived matrix. + +### b3Transform +A rigid transform: a position vector `t.p` (`b3Vec3`) combined with an orientation `t.q` +(`b3Quat`). The identity transform is `b3Transform_identity`. + +```c +// Apply transform to a point in the transform's local frame -> world frame +b3Vec3 world = b3TransformPoint(t, localPoint); + +// Inverse: world frame -> local frame +b3Vec3 local = b3InvTransformPoint(t, worldPoint); + +// Compose: t_child expressed in t_parent's frame +b3Transform combined = b3MulTransforms(t_parent, t_child); + +// Relative transform: t_b expressed in t_a's frame +b3Transform rel = b3InvMulTransforms(t_a, t_b); + +// Invert a transform +b3Transform inv = b3InvertTransform(t); +``` + +### b3Matrix3 +3×3 matrix stored as three column vectors `cx`, `cy`, `cz`. Primarily used for inertia +tensors and rotation matrices. Useful operations include `b3MulMV` (matrix-vector multiply), +`b3MulMM` (matrix-matrix multiply), `b3Transpose`, `b3InvertMatrix`, and `b3MakeMatrixFromQuat`. + +### b3AABB +Axis-aligned bounding box with `lowerBound` and `upperBound` as `b3Vec3`. Helpers include +`b3AABB_Overlaps`, `b3AABB_Contains`, `b3AABB_ContainsPoint`, `b3AABB_Union`, +`b3AABB_Center`, `b3AABB_Extents`, `b3AABB_Inflate`, and `b3AABB_Transform`. + +## Multithreading {#multi} +Box3D has been highly optimized for multithreading. Multithreading is not required and by +default Box3D runs single-threaded. If performance matters, you should consider wiring up +the multithreading interface. + +Box3D does **not** create threads itself. You supply your own thread pool and hook it up through +the world definition before calling `b3CreateWorld`. See `b3EnqueueTaskCallback`, +`b3FinishTaskCallback`, `b3WorldDef::workerCount`, `b3WorldDef::enqueueTask`, and +`b3WorldDef::finishTask`: + +```c +b3WorldDef worldDef = b3DefaultWorldDef(); +worldDef.workerCount = myThreadCount; +worldDef.enqueueTask = MyEnqueueTask; +worldDef.finishTask = MyFinishTask; +worldDef.userTaskContext = myScheduler; + +b3WorldId worldId = b3CreateWorld(&worldDef); +``` + +Your `MyEnqueueTask` callback receives a `b3TaskCallback*` function pointer plus a context +pointer that must be forwarded to the task exactly once on a worker thread. Return a non-null +`void*` handle representing your pending task object, or null if the work was executed +serially inside the callback (Box3D then skips the corresponding `b3FinishTaskCallback`). + +```c +// Enqueue callback signature +void* MyEnqueueTask(b3TaskCallback* task, void* taskContext, + void* userContext, const char* taskName) +{ + MyTask* t = AllocTask(); + t->task = task; + t->taskContext = taskContext; + SubmitToThreadPool(t); // runs task(taskContext) on a worker + return t; // non-null => Box3D will call MyFinishTask(t, ...) +} + +// Finish callback signature +void MyFinishTask(void* userTask, void* userContext) +{ + MyTask* t = (MyTask*)userTask; + WaitForCompletion(t); + FreeTask(t); +} +``` + +Box3D ships an in-tree scheduler (`src/scheduler.h`) used by the test suite and samples. +You can adapt it or use it directly: + +```c +#include "scheduler.h" + +b3Scheduler* scheduler = b3CreateScheduler(workerCount); + +b3WorldDef worldDef = b3DefaultWorldDef(); +worldDef.workerCount = workerCount; +worldDef.enqueueTask = b3SchedulerEnqueueTask; +worldDef.finishTask = b3SchedulerFinishTask; +worldDef.userTaskContext = scheduler; + +b3WorldId worldId = b3CreateWorld(&worldDef); +// ... simulate ... +b3DestroyWorld(worldId); +b3DestroyScheduler(scheduler); +``` + +The multithreading design for Box3D is focused on [data parallelism](https://en.wikipedia.org/wiki/Data_parallelism). +The goal is to use multiple cores to finish the world simulation as fast as possible. +Box3D multithreading is not designed for [task parallelism](https://en.wikipedia.org/wiki/Task_parallelism). +Often in games you have a render thread or an audio thread doing work in isolation from the +main thread. Those are examples of task parallelism. + +So when you design your game loop, you should let Box3D *go wide* and use multiple cores to +finish its work quickly, without other threads interacting with the Box3D world at the same time. + +In a multithreaded environment you must be careful to avoid [race conditions](https://en.wikipedia.org/wiki/Race_condition). +Modifying the world while it is simulating will lead to unpredictable behavior and is never safe. +It is also not safe to read data from a Box3D world while it is simulating; Box3D may move data +structures to improve cache performance, so you could easily read garbage. + +> **Caution**: +> Do not perform read or write operations on a Box3D world during `b3World_Step()` + +> **Caution**: +> Do not write to the Box3D world from multiple threads + +It *is safe* to do ray-casts, shape-casts, and overlap tests from multiple threads outside of +`b3World_Step()`. Generally any read-only operation is safe to do multithreaded outside of +`b3World_Step()`. This can be very useful if you have multithreaded game logic. + +## Multithreading Multiple Worlds +Some applications may wish to create multiple Box3D worlds and simulate them on different threads. +This works fine because Box3D has very limited use of globals. + +There are a few caveats: +- You will get a race condition if you create or destroy Box3D worlds from multiple threads. Use a mutex to guard those operations. +- If you simulate multiple Box3D worlds simultaneously, they should probably not share a task system. Otherwise you risk preemption between worlds competing for the same workers. +- Any callbacks you hook up to Box3D must be thread-safe, including memory allocators. +- All the limitations for single-world simulation still apply. diff --git a/docs/hello.md b/docs/hello.md new file mode 100644 index 0000000..43ca4c1 --- /dev/null +++ b/docs/hello.md @@ -0,0 +1,208 @@ +# Hello Box3D {#hello} +The Box3D distribution includes a Hello World unit test written in C. The test +creates a large static ground box and a small dynamic box. This code does not +contain any graphics. All you will see is text output in the console showing +the box's position over time. + +This is a good example of how to get up and running with Box3D. + +## Creating a World +Every Box3D program begins with the creation of a world object. +The world is the physics hub that manages memory, objects, and simulation. +The world is represented by an opaque handle called `b3WorldId`. + +It is easy to create a Box3D world. First, create the world definition: + +```c +b3WorldDef worldDef = b3DefaultWorldDef(); +``` + +The world definition is a temporary object you can create on the stack. The function +`b3DefaultWorldDef()` populates the world definition with default values. This is necessary +because C does not have constructors and zero-initializing `b3WorldDef` is not appropriate. + +Box3D has no built-in concept of *up*. The gravity vector is a `b3Vec3` and can point in +any direction. Convention in Box3D examples uses +Y as the up axis. The default gravity +is already `{0, -10, 0}`, but it can be set explicitly: + +```c +worldDef.gravity = (b3Vec3){ 0.0f, -10.0f, 0.0f }; +``` + +Now create the world: + +```c +b3WorldId worldId = b3CreateWorld(&worldDef); +``` + +World creation copies all the data it needs from the definition, so the definition can +go out of scope immediately afterward. + +## Creating a Ground Box +Bodies are built using the following steps: +1. Define a body with position, type, etc. +2. Use the world id to create the body. +3. Build a hull shape with the desired extents. +4. Create the shape on the body. + +For step 1, create the ground body definition and set its initial position: + +```c +b3BodyDef groundBodyDef = b3DefaultBodyDef(); +groundBodyDef.position = (b3Vec3){ 0.0f, -10.0f, 0.0f }; +``` + +For step 2, use the world id to create the ground body. Bodies are static by default, +meaning they have zero mass, never move, and do not collide with other static bodies. + +```c +b3BodyId groundId = b3CreateBody(worldId, &groundBodyDef); +``` + +Notice that `worldId` is passed by value. Ids are small structures and are always passed +by value. + +For steps 3 and 4, build a box hull and attach it. Box3D uses convex hulls for box +shapes. The `b3MakeBoxHull` helper takes three **half-extents** (hx, hy, hz), so the +ground slab below is 100 units wide in X, 20 units tall in Y, and 100 units deep in Z: + +```c +b3BoxHull groundBox = b3MakeBoxHull(50.0f, 10.0f, 50.0f); + +b3ShapeDef groundShapeDef = b3DefaultShapeDef(); +b3CreateHullShape(groundId, &groundShapeDef, &groundBox.base); +``` + +The `.base` field holds the `b3Hull` that `b3CreateHullShape` expects. Box3D copies the +hull data into its internal structures, so `groundBox` does not need to outlive the +call. Do not call `b3DestroyHull` on a `b3BoxHull`; it is stack-allocated. + +Box3D is tuned for meters, kilograms, and seconds, so the extents above are in meters. +The engine works best when objects are sized like real-world objects (a barrel is roughly +1 m tall). Simulating glaciers or dust particles would push the limits of single-precision +floating point. + +Every shape must have a parent body, even static shapes. You can attach multiple shapes +to one body. A shape's world transform is inherited from its parent body; there is no +independent shape transform. + +## Creating a Dynamic Body +Creating a dynamic body follows the same steps. The key difference is setting the body +type to `b3_dynamicBody` and giving the shape a non-zero density. + +```c +b3BodyDef bodyDef = b3DefaultBodyDef(); +bodyDef.type = b3_dynamicBody; +bodyDef.position = (b3Vec3){ 0.0f, 4.0f, 0.0f }; +b3BodyId bodyId = b3CreateBody(worldId, &bodyDef); +``` + +> **Caution**: +> You must set the body type to `b3_dynamicBody` if you want the body to +> move in response to forces such as gravity. + +Create a unit cube hull and a shape definition with density and friction: + +```c +b3BoxHull dynamicBox = b3MakeCubeHull(1.0f); + +b3ShapeDef shapeDef = b3DefaultShapeDef(); +shapeDef.density = 1.0f; +shapeDef.baseMaterial.friction = 0.3f; + +b3CreateHullShape(bodyId, &shapeDef, &dynamicBox.base); +``` + +`b3MakeCubeHull(r)` is a convenience that produces a cube with half-extent `r` on all +three axes, equivalent to `b3MakeBoxHull(r, r, r)`. + +> **Caution**: +> A dynamic body should have at least one shape with a non-zero density. +> Otherwise you will get unexpected behavior. + +That completes initialization. We are now ready to simulate. + +## Simulating the World +Box3D uses a numerical integrator that advances the simulation by discrete time steps. +A fixed time step of 1/60 seconds (60 Hz) is recommended for most games. Avoid tying +the time step to your frame rate; a variable time step produces variable results that +are hard to debug. + +```c +float timeStep = 1.0f / 60.0f; +``` + +In addition to integration, Box3D uses a constraint solver. Box3D advances through the +time step in several *sub-steps*, giving each constraint multiple chances to react. Four +sub-steps is the suggested value: + +```c +int subStepCount = 4; +``` + +At 60 Hz with 4 sub-steps the constraints run at 240 Hz internally. More sub-steps +improve accuracy at the cost of performance. + +The simulation loop calls `b3World_Step` once per game tick: + +```c +for (int i = 0; i < 90; ++i) +{ + b3World_Step(worldId, timeStep, subStepCount); + + b3Vec3 position = b3Body_GetPosition(bodyId); + b3Quat rotation = b3Body_GetRotation(bodyId); + + printf("%4.2f %4.2f %4.2f %4.2f %4.2f %4.2f %4.2f\n", + position.x, position.y, position.z, + rotation.v.x, rotation.v.y, rotation.v.z, rotation.s); +} +``` + +`b3Body_GetPosition` returns a `b3Vec3` with the body origin in world space. +`b3Body_GetRotation` returns a `b3Quat` — a unit quaternion stored as a vector part +`q.v` (x, y, z) and a scalar part `q.s`. There is no single angle to extract as there +was in 2D; orientation in 3D requires the full quaternion. To convert to an axis-angle +representation use `b3GetAxisAngle`: + +```c +float angle; +b3Vec3 axis = b3GetAxisAngle(&angle, rotation); +``` + +`angle` is in radians and `axis` is the unit rotation axis. Use +`b3MakeMatrixFromQuat` when you need a 3×3 rotation matrix, for example to feed a +renderer. + +The output should show the box falling from y = 4 and coming to rest on the ground at +approximately y = 1 (the box half-height sits at y = 0 + 1 after the ground surface +at y = 0): + +``` +0.00 4.00 0.00 ... +0.00 3.99 0.00 ... +0.00 3.98 0.00 ... +... +0.00 1.25 0.00 ... +0.00 1.13 0.00 ... +0.00 1.01 0.00 ... +``` + +For advice on managing a fixed simulation rate alongside a variable render rate, see +[Fix Your Timestep!](https://gafferongames.com/post/fix_your_timestep/). + +## Multithreading (optional) +By default Box3D runs single-threaded. The `b3DefaultWorldDef` leaves `workerCount` +at 1 and the task callbacks null, which is fine for getting started. When performance +matters, Box3D can drive a task system. Supply `workerCount` plus `enqueueTask`, +`finishTask`, and `userTaskContext` on the world definition before calling +`b3CreateWorld`. See the Foundations page for details. + +## Cleanup +When you are done with the simulation, destroy the world: + +```c +b3DestroyWorld(worldId); +``` + +This efficiently destroys all bodies, shapes, and joints in the simulation. diff --git a/docs/images/capsule.svg b/docs/images/capsule.svg new file mode 100644 index 0000000..97d65c9 --- /dev/null +++ b/docs/images/capsule.svg @@ -0,0 +1,243 @@ + + + + + + + + + + + + + + + + + + x + y + radius + + + + + + + + + + + + + + + + + + + center2 + center1 + + diff --git a/docs/images/captured_toi.svg b/docs/images/captured_toi.svg new file mode 100644 index 0000000..e5d951d --- /dev/null +++ b/docs/images/captured_toi.svg @@ -0,0 +1,124 @@ + + + + + + + + + + + + image/svg+xml + + + + + + + + + + t=0 + t=1 + + + diff --git a/docs/images/center_of_mass.svg b/docs/images/center_of_mass.svg new file mode 100644 index 0000000..00afe13 --- /dev/null +++ b/docs/images/center_of_mass.svg @@ -0,0 +1,183 @@ + + + + + + + + + + + + + + body origin + + x + y + + + + + + + + + + + + + centerofmass + + diff --git a/docs/images/distance.svg b/docs/images/distance.svg new file mode 100644 index 0000000..afefe85 --- /dev/null +++ b/docs/images/distance.svg @@ -0,0 +1,178 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..f002689 --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,126 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + diff --git a/docs/images/manifolds.svg b/docs/images/manifolds.svg new file mode 100644 index 0000000..564fe9f --- /dev/null +++ b/docs/images/manifolds.svg @@ -0,0 +1,256 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + two points, one normal + one point, one normal + + diff --git a/docs/images/missed_toi.svg b/docs/images/missed_toi.svg new file mode 100644 index 0000000..a8fbbe4 --- /dev/null +++ b/docs/images/missed_toi.svg @@ -0,0 +1,153 @@ + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + t=0 + t=1 + + separating axis + + diff --git a/docs/images/mover.png b/docs/images/mover.png new file mode 100644 index 0000000000000000000000000000000000000000..e991384efb0869c67e81eaa7ec5878d8814c746f GIT binary patch literal 108143 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

rw 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

bmlHsP;BKw=7e($yl>w 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 WBK)i8K&%oB{1FZl@%M2g>VE*>#tP;D literal 0 HcmV?d00001 diff --git a/docs/images/overlap_test.svg b/docs/images/overlap_test.svg new file mode 100644 index 0000000..be78e9b --- /dev/null +++ b/docs/images/overlap_test.svg @@ -0,0 +1,148 @@ + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + diff --git a/docs/images/raycast.svg b/docs/images/raycast.svg new file mode 100644 index 0000000..78ac5df --- /dev/null +++ b/docs/images/raycast.svg @@ -0,0 +1,151 @@ + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + diff --git a/docs/images/samples.png b/docs/images/samples.png new file mode 100644 index 0000000000000000000000000000000000000000..8a19281e1121c1ba24e3d6d38cfbd5de470d9759 GIT binary patch literal 333746 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

P!B5dzp=SaFjVR!^Wxmm2KQAmkNF%i1gyn4EE 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 z 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�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 z z-jfVyV@`YtED3;Kz3cDHw_|mlcP|;WP^-L5rIF8AFm`OvRhzJFM9bm=MJ!1Ai2(KrM@SIICu6sbbaP7Xv*^qeKJe zl=&FQ#?26aVQ_+)#*3nk(`61hp`=&mtGyR#bC!+=t-Q0Cc{v-q@Cu!k*$+BU0l1y@ zliZh)yiEcRUK}qnwIVBpe@8)0+;-nDklXsnnzAhYVcM@-hZfdaEO8e%kIyj<^?jj= zA7jvu<=C3JX>vMF>k53y5OBxveJw&dyo$#kca|}2ekqtZSndPDEg2YYz0FV@p8C7S zi+usL6781iFm)9h0d@AX{FQEQJQnbb9uL(1(}}M!drj0gpxIV1Y+n;vv}yO!Tu<|v zaYS-EmT+BJ=!sPfEvjZ?T>J>ymiOs|yHc_ubtN-T*U?pQjeM3e0NomMof3!wG)$cp z^jqy<`3+Rpg+1fHZ7Uy`&1p#5F7O~gVpUxb{}pR|QXVFFV*}YASIi(?A@$qo_?;sNlbkWZ(?Xp5l0)3bIf!S8Bj5Z zfpY1jPICxl=uZcKYV}=lXkz3Xcg<+{HN5U<95`S$V68$0uP9I7OXZ|D{T~G- zrk2Md{}u}{c@F{09x$XRRLu<%EJ@iG)eB0+O)JwpO=`fL)7)}&6N-hUv2H2DBnVvU zF&+nRc=0XC+Go*G`O)&-&ZDG!R`CHCskTnW>|9aY9C6@pNRdX9fOphil7y^xb$OUK zq3Z^GK2pEvbzZ#C)iZ1Ze-4(gsG*yAH7Zu{X1wmFrO*BIh1RAt2B;PJpi zcn^Sa0|FnHj&tOxLW;&Ba~led%uQM5JF^fU0w_zbr?|#14+9Rg&9o^moy1+0wf9Jk zR$a}PbYq6>!oEy@*_^1R;M?epJH~Vj-jp=q6(9p?5EjL}nDCG|`AyccDc{^}#%pFd zkp$)tEIzSPoipP>xJ{zH86LG*pnSdlD;1SHN)c-*;3ghzyW`Ef`U~pS>+Ck!w!%F^ zf)D~W%heX5MvMO{^3RhRgYW`L_qnrw%LtyNUM5Xqy$#+_B0!ernA7$NQR+CXf#t?K zSgc7ZtxNQln=fuurW$J}w;f$!OOe`Td3+`UEt%IJOUlXIcWY7uJ&7i2kn-0n*;`28jUJ~xnaHyl4=cn1h|8bE|O(1153dG*)T IugpUK2TH<)HUIzs literal 0 HcmV?d00001 diff --git a/docs/images/simulation_loop.svg b/docs/images/simulation_loop.svg new file mode 100644 index 0000000..c898df0 --- /dev/null +++ b/docs/images/simulation_loop.svg @@ -0,0 +1,396 @@ + + + +findpairscreatecontactsnarrowphasesolveconstraintsmergeislandssplitislandupdatetransformshiteventsislandsleeptimesteprefitBVHbulletssensorsrebuildBVH diff --git a/docs/images/skin_collision.svg b/docs/images/skin_collision.svg new file mode 100644 index 0000000..29ac847 --- /dev/null +++ b/docs/images/skin_collision.svg @@ -0,0 +1,140 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + Polygons collidewith their skin + + diff --git a/docs/images/tunneling1.svg b/docs/images/tunneling1.svg new file mode 100644 index 0000000..b6d68b0 --- /dev/null +++ b/docs/images/tunneling1.svg @@ -0,0 +1,162 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + time0 + time1 + + diff --git a/docs/images/tunneling2.svg b/docs/images/tunneling2.svg new file mode 100644 index 0000000..fa6d609 --- /dev/null +++ b/docs/images/tunneling2.svg @@ -0,0 +1,140 @@ + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + t=0 + t=1 + + diff --git a/docs/layout.xml b/docs/layout.xml new file mode 100644 index 0000000..e93b6cf --- /dev/null +++ b/docs/layout.xml @@ -0,0 +1,269 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/loose_ends.md b/docs/loose_ends.md new file mode 100644 index 0000000..47892b9 --- /dev/null +++ b/docs/loose_ends.md @@ -0,0 +1,152 @@ +# Loose Ends + +## User Data + +Bodies, shapes, and joints allow you to attach user data as a `void*`. This is +useful when you receive a body, shape, or joint id from an event or query and +need to map it back to a game object. + +A common pattern is storing a game-entity pointer on the body: + +```c +GameEntity* entity = GameCreateEntity(); +b3BodyDef bodyDef = b3DefaultBodyDef(); +bodyDef.userData = entity; +entity->bodyId = b3CreateBody(myWorldId, &bodyDef); +``` + +The circular reference lets you go from entity to body and back. Some typical +uses: + +- Applying damage to an entity from a contact event. +- Triggering a scripted event when a body enters a region. +- Cleaning up game state when a joint is destroyed. + +Keep the type consistent. If one body stores a `GameEntity*`, all bodies should. +Mixing pointer types and casting without a discriminant leads to crashes. + +Setters and getters: + +```c +// Body +b3Body_SetUserData(bodyId, ptr); +void* ptr = b3Body_GetUserData(bodyId); + +// Shape +b3Shape_SetUserData(shapeId, ptr); +void* ptr = b3Shape_GetUserData(shapeId); + +// Joint +b3Joint_SetUserData(jointId, ptr); +void* ptr = b3Joint_GetUserData(jointId); + +// World +b3World_SetUserData(worldId, ptr); +void* ptr = b3World_GetUserData(worldId); +``` + +## Coordinate Systems + +Box3D uses a right-handed coordinate system. Positive Y is up by default, +meaning the default gravity vector points in the negative Y direction +(`{0, -9.8f, 0}`). Nothing in the engine hard-codes this — gravity is just a +`b3Vec3` set on the world and you can orient it however your application +requires. + +Use MKS units: meters, kilograms, seconds, and radians. The solver is tuned for +objects in the range of roughly 0.1 to 10 meters. Very small or very large +objects relative to this range can degrade numerical stability. If your content +is authored at a different unit scale, apply a single conversion factor at the +boundary between your asset pipeline and Box3D, not scattered throughout the +simulation code. + +Bodies in Box3D have 6 degrees of freedom. Position is a `b3Vec3`, orientation +is a `b3Quat`, angular velocity and torque are `b3Vec3` values. The rotational +inertia tensor is a `b3Matrix3`. + +## Debug Drawing + +Implement the function pointers in `b3DebugDraw` to get detailed drawing of the +Box3D world. The struct lives in `types.h` and has slots for: + +- `DrawShapeFcn` — draws a shape; receives a user-shape object created by + `b3WorldDef::createDebugShape` and the current transform and color. +- `DrawSegmentFcn` — draws a line segment. +- `DrawTransformFcn` — draws a coordinate frame. +- `DrawPointFcn` — draws a point. +- `DrawBoundsFcn` — draws an AABB as a wireframe box. +- `DrawBoxFcn` — draws an oriented box by extents and transform. +- `DrawStringFcn` — draws a world-space label. + +Category flags on the struct control what gets drawn: + +| Flag | What it shows | +|---|---| +| `drawShapes` | Shape geometry | +| `drawJoints` | Joint frames and constraints | +| `drawJointExtras` | Extra joint information (limits, motors) | +| `drawBounds` | Shape AABBs | +| `drawMass` | Center-of-mass marker and mass value for dynamic bodies | +| `drawBodyNames` | Body name strings | +| `drawContacts` | Contact points and anchors | +| `drawContactNormals` | Contact normal directions | +| `drawContactForces` | Normal impulse magnitudes | +| `drawFrictionForces` | Friction impulse magnitudes | +| `drawGraphColors` | Constraint-graph color assignment | +| `drawContactFeatures` | Raw contact feature indices | +| `drawIslands` | Island bounding boxes | + +Call the draw function after stepping the world: + +```c +b3DebugDraw draw = b3DefaultDebugDraw(); +draw.DrawShapeFcn = MyDrawShape; +draw.DrawSegmentFcn = MyDrawSegment; +// ... fill remaining callbacks ... +draw.drawShapes = true; +draw.drawingBounds = myViewAABB; + +b3World_Draw(worldId, &draw, UINT64_MAX); +``` + +The `maskBits` argument is tested against each shape's `categoryBits` in the +broad-phase tree. Only shapes where `(maskBits & shape->categoryBits) != 0` are +visited. Pass `UINT64_MAX` to draw everything, or use a subset of your category +bits to limit drawing to specific layers (e.g. skip debris for a clean overhead +view). + +The shape draw path uses a two-callback model set on `b3WorldDef`: +`createDebugShape` is called once when a shape is first drawn, giving you a +chance to upload GPU geometry; `destroyDebugShape` is called when the shape is +modified or destroyed so you can release it. The `DrawShapeFcn` callback +receives the opaque handle returned by `createDebugShape`, which enables +efficient multi-pass rendering without re-uploading geometry every frame. + +The samples application demonstrates a complete `b3DebugDraw` implementation. + +## Limitations + +Box3D uses several approximations to simulate rigid body physics efficiently. +As a v0.1 engine it is still maturing, so expect rougher edges than Box2D. + +Current limitations: + +1. Extreme mass ratios between connected bodies can cause joint stretching and + contact overlap. +2. Soft constraints improve robustness but allow a small amount of flexing in + joints and contacts. +3. Continuous collision handles fast-moving dynamic bodies against static + geometry (and bullets against dynamic bodies), but not general + dynamic-versus-dynamic continuous collision. +4. Continuous collision does not propagate through joints, so fast-moving + articulated chains may momentarily stretch. +5. The integrator is semi-implicit Euler, which gives first-order accuracy. + Projectile arcs are approximate. Increasing `subStepCount` in + `b3World_Step` improves accuracy at a proportional cost. +6. Constraint resolution uses an iterative Gauss-Seidel solver for real-time + performance. Collisions are not perfectly rigid and contacts are not + pixel-accurate. More sub-steps tighten the result. +7. Mesh and height-field shapes are static-only. They do not participate in + dynamic-versus-dynamic contact. +8. The compound shape type is static-body only and immutable after creation. +9. The character mover API is experimental. diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..6d7473d --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,262 @@ +# Overview {#mainpage} +Box3D is a 3D rigid body simulation library for games. Programmers can +use it in their games to make objects move in realistic ways and make +the game world more interactive. From the game engine's point of view, +a physics engine is a system for procedural animation. + +Box3D also provides many collision routines that can be used even when +rigid body simulation is not used. There are functions for overlap and +cast queries. There is also a bounding volume hierarchy (dynamic tree) +that can be used for game specific spatial sorting needs. + +Box3D is written in portable C17. Most of the types defined in the +engine begin with the `b3` prefix. Hopefully this is sufficient to avoid +name clashing with your application. + +## Prerequisites +In this manual I'll assume you are familiar with basic physics +concepts, such as mass, force, torque, and impulses. If not, please +first consult Google search and Wikipedia. + +Box2D (the 2D sibling of Box3D) was created as part of a physics tutorial +at the Game Developer Conference. You can get those tutorials from the +publications section of [box2d.org](https://box2d.org/publications/), +which cover the underlying algorithms shared by both engines. + +Since Box3D is written in C, you are expected to be experienced in C +programming. Box3D should not be your first C programming project. You +should be comfortable with compiling, linking, and debugging. + +> **Caution**: +> Box3D should not be your first C project. Please learn C +> programming, compiling, linking, and debugging before working with +> Box3D. There are many resources for this online. + +## Scope +This manual covers the majority of the Box3D API. However, not every +aspect is covered. Please look at the Reference section and samples +application included with Box3D to learn more. + +This manual is only updated with new releases. The latest version of +Box3D may be out of sync with this manual. + +> **Caution**: +> This manual applies to the associated release and not necessarily the +> latest version on the main branch. + +## Feedback and Bugs +Please file bugs and feature requests here: +[Box3D Issues](https://github.com/erincatto/box3d/issues) + +You can help to ensure your issue gets fixed if you provide sufficient +detail. A testbed example that reproduces the problem is ideal. You can +read about the testbed later in this document. + +There is also a [Discord server](https://discord.gg/NKYgCBP) and +[GitHub Discussions](https://github.com/erincatto/box3d/discussions). + +## Core Concepts +Box3D works with several fundamental concepts and objects. I briefly +define these objects here and more details are given later in this +document. + +### rigid body +A chunk of matter that is so strong that the distance between any two +bits of matter on the chunk is constant. They are hard like a diamond. +In the following discussion I use *body* interchangeably with rigid body. + +### shape +A shape binds collision geometry to a body and adds material properties such as +density, friction, and restitution. A shape puts collision geometry into the +collision system (broad-phase) so that it can collide with other shapes. + +### constraint +A constraint is a physical connection that removes degrees of freedom +from bodies. A 3D body has 6 degrees of freedom (three translation +coordinates and three rotation coordinates). If I take a body and pin it +to the wall (like a pendulum) I have constrained the body to the wall. +At this point the body can only rotate about the pin, so the constraint +has removed 3 translational degrees of freedom, leaving the body free +to swing in 3D about the fixed anchor. + +### contact constraint +A special constraint designed to prevent penetration of rigid bodies and +to simulate friction and restitution. You do not create contact +constraints; they are created automatically by Box3D. + +### joint constraint +This is a constraint used to hold two or more bodies together. Box3D +supports several joint types: revolute, prismatic, distance, spherical, +weld, wheel, motor, parallel, and filter. Joints may have limits, +motors, and/or springs. + +### joint limit +A joint limit restricts the range of motion of a joint. For example, the +human elbow only allows a certain range of angles. + +### joint motor +A joint motor drives the motion of the connected bodies according to the +joint's degrees of freedom. For example, you can use a motor to drive +the rotation of an elbow. Motors have a target speed and a maximum force +or torque. The simulation will apply the force or torque required to +achieve the desired speed. + +### joint spring +A joint spring has a stiffness and damping. In Box3D spring stiffness is +expressed in terms of Hertz or cycles per second. This lets you configure how +quickly a spring reacts regardless of the body masses. Joint springs also +have a damping ratio to let you specify how quickly the spring will come to +rest. + +### world +A physics world is a collection of bodies, shapes, joints, and contacts +that interact together. Box3D supports the creation of multiple worlds which +are completely independent. + +### solver +The physics world has a solver that is used to advance time and to +resolve contact and joint constraints. The Box3D solver is a high +performance sequential solver that operates in order N time, where N is +the number of constraints. + +### continuous collision +The solver advances bodies in time using discrete time steps. Without +intervention this can lead to tunneling. +![Tunneling Effect](images/tunneling1.svg) + +Box3D contains specialized algorithms to deal with tunneling. First, the +collision algorithms can interpolate the motion of two bodies to find +the first time of impact (TOI). Second, speculative collision is used to create +contact constraints between bodies before they touch. + +### events +World simulation leads to the creation of events that are available at the end +of the time step: + +- body movement events +- contact begin and end events +- sensor begin and end events +- contact hit events + +These events allow your application to react to changes in the simulation. + +## Modules +Box3D's primary purpose is to provide rigid body simulation. However, +there are math and collision features that may be useful apart from the +rigid body simulation. These are provided in the `include` directory. Anything +in the `include` directory is considered public, while everything in the `src` +directory is considered internal. + +Public features are supported and you can get help with these on the Discord +server. Using internal code directly is not supported. However, feel free to +study the code and ask questions. I'm happy to share all the details of how +Box3D works internally. + +## Units +Box3D works with floating point numbers and tolerances have to be used +to make Box3D perform well. These tolerances have been tuned to work +well with meters-kilogram-second (MKS) units. In particular, Box3D has +been tuned to work well with moving shapes between 0.1 and 10 meters. So +this means objects between soup cans and buses in size should work well. + +Static shapes may be up to 50 meters long without trouble. If you have a +large world, you should split it up into multiple static bodies. This will +improve precision and simulation behavior. + +> **Caution**: +> Box3D is tuned for MKS units. Keep the size of moving objects larger than 1cm. +> You'll need to use some scaling system when you render your environment and +> actors. Do not use non-metric units unless you understand the implications. + +Another limitation to consider is overall world size. If your world units +become larger than 12 kilometers or so, then the lost precision can affect +stability. + +> **Caution**: +> Box3D works best with world sizes less than 12 kilometers. If you are +> careful with your simulation tuning, this can be pushed up to around 24 +> kilometers, which is much larger than most game worlds. + +Box3D uses radians for angles. Orientation is stored as a quaternion +(`b3Quat`), so there is no concept of a body angle clamped to a range; +the full 3D rotation is tracked continuously. + +> **Caution**: +> Box3D uses radians, not degrees. + +## Changing the length units +Advanced users may change the length unit by calling `b3SetLengthUnitsPerMeter()` +at application startup. If you keep Box3D in a shared library, you will need +to call this if the shared library is reloaded. + +It is harder to get support for using Box3D if you change the unit +system, because values are harder to communicate and may become non-intuitive. +One of the benefits of using MKS units for physics simulation is that you can +use real world values to get reasonable results. + +## Ids and Definitions +Fast memory management plays a central role in the design of the Box3D +interface. When you create a world, body, shape or joint, you will receive +a handle called an *id*. These ids are opaque and are passed to various functions +to access the underlying data. + +These ids provide some safety. If you use an id after it has been freed you will +usually get an assertion. All ids support 64k generations of safety. All ids +also have a corresponding function you can call to check if it is valid. + +When you create a world, body, shape, or joint, you need to provide a definition structure. +These definitions contain all the information needed to build the Box3D object. By using +this approach I can prevent construction errors, keep the number of function parameters +small, provide sensible defaults, and reduce the number of accessors. + +Here is an example of body creation: + +```c +b3BodyDef bodyDef = b3DefaultBodyDef(); +bodyDef.position = (b3Vec3){10.0f, 0.0f, 5.0f}; +b3BodyId myBodyId = b3CreateBody(myWorldId, &bodyDef); +``` + +Notice the body definition is initialized by calling `b3DefaultBodyDef()`. This is needed +because C does not have constructors and zero initialization is generally not suitable for the +definitions used in Box3D. + +Also notice that the body definition is a temporary object that is fully copied into the internal +body data structures. Definitions should usually be created on the stack as temporaries. + +This is how a body is destroyed: + +```c +b3DestroyBody(myBodyId); +myBodyId = b3_nullBodyId; +``` + +Notice that the body id is set to null using the constant `b3_nullBodyId`. You should treat +ids as opaque data, however you may zero initialize all Box3D ids and they will be considered +*null*. + +Shapes are created in a similar way. For example, here is how a box shape is created: + +```c +b3ShapeDef shapeDef = b3DefaultShapeDef(); +shapeDef.baseMaterial.friction = 0.42f; +b3BoxHull boxHull = b3MakeBoxHull(0.5f, 0.25f, 0.5f); +b3ShapeId myShapeId = b3CreateHullShape(myBodyId, &shapeDef, &boxHull.base); +``` + +And the shape may be destroyed as follows: + +```c +b3DestroyShape(myShapeId, true); +myShapeId = b3_nullShapeId; +``` + +For convenience, Box3D will destroy all shapes on a body when the body is destroyed. You don't need to store the shape id. + +There are some macros to assist using ids in logical operations. + +```c +bool isNull = B3_IS_NULL(myBodyId); +bool isNonNull = B3_IS_NON_NULL(myJointId); +bool areEqual = B3_ID_EQUALS(myShapeIdA, myShapeIdB); +``` diff --git a/docs/reading.md b/docs/reading.md new file mode 100644 index 0000000..50f675e --- /dev/null +++ b/docs/reading.md @@ -0,0 +1,5 @@ +# Further Reading +- [Erin Catto's Publications](https://box2d.org/publications/) +- [Erin Catto's Blog Posts](https://box2d.org/posts/) +- Collision Detection in Interactive 3D Environments, Gino van den Bergen, 2004 +- Real-Time Collision Detection, Christer Ericson, 2005 diff --git a/docs/recording.md b/docs/recording.md new file mode 100644 index 0000000..3476187 --- /dev/null +++ b/docs/recording.md @@ -0,0 +1,14 @@ +# Recording and Replay + +Deterministic recording, replay, and world snapshots are planned features for Box3D but are not yet +available. Box3D's sister engine Box2D ships a full recording and snapshot API; a 3D equivalent +will follow once the simulation format stabilizes. + +In the meantime: + +- Box3D is deterministic given the same inputs and the same build. See the **Determinism** section + of the Simulation page for details on what "same inputs" means across platforms and thread counts. +- There is no API to serialize or restore a world state in the current release. +- There is no replay viewer in the current samples application. + +Check the [Box3D repository](https://github.com/erincatto/box3d) for updates on this feature. diff --git a/docs/samples.md b/docs/samples.md new file mode 100644 index 0000000..44e58c7 --- /dev/null +++ b/docs/samples.md @@ -0,0 +1,21 @@ +# Samples {#samples} +Once you have conquered the HelloWorld example, you should start looking +at Box3D's samples application. The samples application is a testing framework and demo +environment. Here are some of the features: +- Camera with pan and zoom +- Mouse dragging of dynamic bodies +- Many samples in a tree view +- GUI for selecting samples, parameter tuning, and debug drawing options +- Pause and single step simulation +- Multithreading and performance data + +![Box3D Samples](images/samples.png) + +The samples application has many examples of Box3D usage in the test cases and the +framework itself. I encourage you to explore and tinker with the samples +as you learn Box3D. + +Note: the sample application is written using [GLFW](https://www.glfw.org) and +[imgui](https://github.com/ocornut/imgui). +The samples app is not part of the Box3D library. The Box3D library is agnostic about rendering. +As shown by the HelloWorld example, you don't need a renderer to use Box3D. diff --git a/docs/simulation.md b/docs/simulation.md new file mode 100644 index 0000000..c288421 --- /dev/null +++ b/docs/simulation.md @@ -0,0 +1,2002 @@ +# Simulation +Rigid body simulation is the primary feature of Box3D. It is the most complex part of +Box3D and is the part you will likely interact with the most. Simulation sits on top of +the foundation and collision layers, so you should be somewhat familiar with those by now. + +Rigid body simulation contains: +- worlds +- bodies +- shapes +- contacts +- joints +- events + +There are many dependencies between these objects so it is difficult to +describe one without referring to another. In the following, you +may see some references to objects that have not been described yet. +Therefore, you may want to quickly skim this section before reading it +closely. + +## Ids +Box3D has a C interface. Typically in a C/C++ library when you create an object with a long lifetime +you will keep a pointer (or smart pointer) to the object. + +Box3D works differently. Instead of pointers, you are given an *id* when you create an object. +This *id* acts as a [handle](https://en.wikipedia.org/wiki/Handle_(computing)) which helps avoid +problems with [dangling pointers](https://en.wikipedia.org/wiki/Dangling_pointer). + +This also allows Box3D to use [data-oriented design](https://en.wikipedia.org/wiki/Data-oriented_design) internally. +This helps to reduce cache misses drastically and also allows for [SIMD](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data) optimizations. + +So you will be dealing with `b3WorldId`, `b3BodyId`, etc. These are small opaque structures that you +will pass around by value, just like pointers. Box3D creation functions return an id. Functions +that operate on Box3D objects take ids. + +```c +b3BodyId myBodyId = b3CreateBody(myWorldId, &myBodyDef); +``` + +There are functions to check if an id is valid. Box3D functions will assert if you use an invalid id. +This makes debugging easier than using dangling pointers. + +```c +if (b3Body_IsValid(myBodyId) == false) +{ + // oops +} +``` + +Null ids can be established in a couple of ways. You can use predefined constants or zero initialization. +```c +b3BodyId myNullBodyId = b3_nullBodyId; +b3BodyId otherNullBodyId = {0}; +``` + +You can test if an id is null using some helper macros: +```c +if (B3_IS_NULL(myBodyId)) +{ + // do something +} +``` + +```c +if (B3_IS_NON_NULL(myShapeId)) +{ + // do something +} +``` + +## World +The Box3D world contains the bodies and joints. It manages all aspects +of the simulation and allows for asynchronous queries (like AABB queries +and ray-casts). Much of your interactions with Box3D will be with a +world object, using `b3WorldId`. + +### World Definition +Worlds are created using a *definition* structure. This is a temporary structure that +you can use to configure options for world creation. You **must** initialize the world definition +using `b3DefaultWorldDef()`. + +```c +b3WorldDef worldDef = b3DefaultWorldDef(); +``` + +The world definition has lots of options, but for most you will use the defaults. You may want to set the gravity: + +```c +// +Y is up; default is {0, -10, 0} +worldDef.gravity = (b3Vec3){0.0f, -10.0f, 0.0f}; +``` + +Box3D has no built-in concept of an up direction. Gravity is simply a `b3Vec3` applied to every +dynamic body each step. + +If your game doesn't need sleep, you can get a performance boost by completely disabling sleep: + +```c +worldDef.enableSleep = false; +``` + +You can also configure multithreading to improve performance: + +```c +worldDef.workerCount = 4; +worldDef.enqueueTask = myAddTaskFunction; +worldDef.finishTask = myFinishTaskFunction; +worldDef.userTaskContext = &myTaskSystem; +``` + +Multithreading is not required but it can improve performance substantially. + +### World Lifetime +Creating a world is done using a world definition. + +```c +b3WorldId myWorldId = b3CreateWorld(&worldDef); + +// ... do stuff ... + +b3DestroyWorld(myWorldId); + +// Nullify id for safety +myWorldId = b3_nullWorldId; +``` + +You can create up to 128 worlds. These worlds do not interact and may be simulated in parallel. + +When you destroy a world, every body, shape, and joint is also destroyed. This is much faster +than destroying individual objects. + +### Simulation +The world is used to drive the simulation. You specify a time step +and a sub-step count. For example: + +```c +float timeStep = 1.0f / 60.0f; +int subStepCount = 4; +b3World_Step(myWorldId, timeStep, subStepCount); +``` + +After the time step you can examine your bodies and joints for +information. Most likely you will grab the position off the bodies so +that you can update your game objects and render them. Or more optimally, you +will use `b3World_GetBodyEvents()`. + +You can perform the time step anywhere in your game loop, but you should be aware of the +order of things. For example, you must create bodies before the time +step if you want to get collision results for the new bodies in that +frame. + +You should use a fixed time step. By using a larger time step you can improve performance in +low frame rate scenarios. But generally you should use a time step of 1/30 seconds (30Hz) or smaller. +A time step of 1/60 seconds (60Hz) will usually deliver a high quality simulation. + +The sub-step count is used to increase accuracy. By sub-stepping the solver +divides up time into small increments and the bodies move by a small amount. +This allows joints and contacts to respond with finer detail. The recommended +sub-step count is 4. However, increasing the sub-step count may improve +accuracy. For example, long joint chains will stretch less with more sub-steps. + +## Rigid Bodies +Rigid bodies, or just *bodies*, have position and velocity. You can apply forces, torques, +and impulses to bodies. Bodies can be static, kinematic, or dynamic. + +A 3D rigid body has 6 degrees of freedom: 3 translational (position along x, y, z) and +3 rotational (rotation about x, y, z axes). Orientation is represented as a quaternion +(`b3Quat`), and angular velocity and torque are both `b3Vec3` quantities. + +Here are the body type definitions: + +### Body Types +`b3_staticBody`: +A static body does not move under simulation and behaves as if it has infinite mass. +Internally, Box3D stores zero for the mass and the inverse mass. A static body has zero +velocity. Static bodies do not collide with other static or kinematic bodies. + +`b3_kinematicBody`: +A kinematic body moves under simulation according to its velocity. +Kinematic bodies do not respond to forces. A kinematic body is moved by setting its +velocity. A kinematic body behaves as if it has infinite mass, however, +Box3D stores zero for the mass and the inverse mass. Kinematic bodies do +not collide with other kinematic or static bodies. Generally you should use +a kinematic body if you want a shape to be animated and not affected by +forces or collisions. + +`b3_dynamicBody`: +A dynamic body is fully simulated and moves according to forces and torques. +A dynamic body can collide with all body types. A dynamic body always has +finite, non-zero mass. + +> **Caution**: +> Generally you should not set the transform on bodies after creation. +> Box3D treats this as a teleport and may result in undesirable behavior and/or performance problems. + +Bodies carry shapes and move them around in the world. Bodies are always +rigid bodies in Box3D. That means two shapes attached to the same rigid body never move +relative to each other, and shapes attached to the same body don't collide. + +Shapes have collision geometry and density. Normally, bodies acquire +their mass properties from the shapes. However, you can override the +mass properties after a body is constructed. + +You usually keep ids to all the bodies you create. This way you can +query the body positions to update the positions of your graphical +entities. You should also keep body ids so you can destroy them +when you are done with them. + +### Body Definition +Before a body is created you must create a body definition (`b3BodyDef`). +The body definition holds the data needed to create and initialize a +body correctly. + +Because Box3D uses a C API, a function is provided to create a default +body definition. + +```c +b3BodyDef myBodyDef = b3DefaultBodyDef(); +``` + +This ensures the body definition is valid and this initialization is **mandatory**. + +Box3D copies the data out of the body definition; it does not keep a +pointer to the body definition. This means you can recycle a body +definition to create multiple bodies. + +### Body Type +As discussed previously, there are three different +body types: static, kinematic, and dynamic. `b3_staticBody` is the default. +You should establish the body type at creation because changing the body type +later is expensive. + +```c +b3BodyDef bodyDef = b3DefaultBodyDef(); +bodyDef.type = b3_dynamicBody; +``` + +### Position and Orientation +You can initialize the body position and orientation in the body definition. This has far +better performance than creating the body at the world origin and then moving the body. + +> **Caution**: +> Do not create a body at the origin and then move it. If you create +> several bodies at the origin, then performance will suffer. + +A body has two main points of interest. The first point is the body's +origin. Shapes and joints are attached relative to the body's origin. +The second point of interest is the center of mass. The center of mass +is determined from the mass distribution of the attached shapes or is +explicitly set using `b3MassData`. Much of Box3D's internal computations +use the center of mass position. For example the body stores the linear +velocity for the center of mass, not the body origin. + +![Body Origin and Center of Mass](images/center_of_mass.svg) + +When you are building the body definition, you may not know where the +center of mass is located. Therefore you specify the position of the +body's origin. You may also specify the body's orientation as a `b3Quat`. +If you later change the mass properties of the body, then the center of mass may move +on the body, but the origin position and orientation do not change and the attached +shapes and joints do not move. + +```c +b3BodyDef bodyDef = b3DefaultBodyDef(); +bodyDef.position = (b3Vec3){0.0f, 2.0f, 0.0f}; + +// Rotate 45 degrees about the Y axis +b3Vec3 axis = {0.0f, 1.0f, 0.0f}; +bodyDef.rotation = b3MakeQuatFromAxisAngle(axis, 0.25f * B3_PI); +``` + +To read the axis and angle back from a quaternion: + +```c +b3Quat q = b3Body_GetRotation(myBodyId); +float radians; +b3Vec3 axis = b3GetAxisAngle(&radians, q); +``` + +A rigid body is a frame of reference. You can define shapes and +joints in that frame. Those shapes and joint anchors never move in the +local frame of the body. + +### Damping +Damping is used to reduce the world velocity of bodies. Damping is +different than friction because friction only occurs with contact. +Damping is not a replacement for friction and the two effects are +used together. + +Damping parameters are non-negative. Normally you will use a +damping value between 0 and 1. Linear damping is generally undesirable +because it makes bodies look like they are floating. + +```c +bodyDef.linearDamping = 0.0f; +bodyDef.angularDamping = 0.1f; +``` + +Damping is approximated to improve performance. At small damping +values the damping effect is mostly independent of the time step. At +larger damping values, the damping effect will vary with the time step. +This is not an issue if you use a fixed time step (recommended). + +### Gravity Scale +You can use the gravity scale to adjust the gravity on a single body. Be +careful though, a large gravity magnitude can decrease stability. + +```c +// Set the gravity scale to zero so this body will float +bodyDef.gravityScale = 0.0f; +``` + +### Sleep Parameters +When a body comes to rest, Box3D can stop simulating it to save CPU time. +This is called *sleeping*. When Box3D determines that a body (or group of bodies) +has come to rest, the body enters a sleep state which has very little CPU overhead. +If a body is awake and collides with a sleeping body, then the sleeping body +wakes up. Bodies will also wake up if a joint or contact attached to +them is destroyed. You can also wake a body manually. + +The body definition lets you specify whether a body can sleep and +whether a body is created sleeping. + +```c +bodyDef.enableSleep = true; +bodyDef.isAwake = true; +``` + +The `isAwake` flag is ignored if `enableSleep` is false. + +### Motion Locks +In 3D you sometimes want to restrict a body to a subset of its six degrees of freedom. +For example, you might want a door hinge that only rotates about the Y axis, or a +platform that only translates along X. Box3D provides `b3MotionLocks` for this: + +```c +b3MotionLocks locks = {0}; +locks.linearY = true; // prevent translation along Y +locks.angularX = true; // prevent rotation about X +locks.angularZ = true; // prevent rotation about Z +bodyDef.motionLocks = locks; +``` + +You can also update locks after creation: + +```c +b3Body_SetMotionLocks(myBodyId, locks); +b3MotionLocks current = b3Body_GetMotionLocks(myBodyId); +``` + +Locking all three angular axes is equivalent to fixing the rotation entirely. + +### Bullets {#bullets} +Game simulation usually generates a sequence of transforms that are played +at some frame rate. This is called discrete simulation. In discrete +simulation, rigid bodies can move by a large amount in one time step. If +a physics engine doesn't account for the large motion, you may see some +objects incorrectly pass through each other. This effect is called +*tunneling*. + +![Tunneling 1](images/tunneling1.svg) + +![Tunneling 2](images/tunneling2.svg) + +By default, Box3D uses continuous collision detection (CCD) to prevent +dynamic bodies from tunneling through static bodies. This is done by +sweeping shapes from their old position to their new positions. The +engine looks for new collisions during the sweep and computes the time +of impact (TOI) for these collisions. Bodies are moved to their first +TOI at the end of the time step. + +![Captured TOI](images/captured_toi.svg) + +![Missed TOI](images/missed_toi.svg) + +Normally CCD is not used between dynamic bodies. This is done to keep +performance reasonable. In some game scenarios you need dynamic bodies +to use CCD. For example, you may want to shoot a high speed bullet at a +stack of dynamic bricks. Without CCD, the bullet might tunnel through +the bricks. + +Fast moving objects in Box3D can be configured as *bullets*. Bullets will +perform CCD with all body types, but **not** other bullets. You should decide what +bodies should be bullets based on your game design. If you decide a body +should be treated as a bullet, use the following setting. + +```c +bodyDef.isBullet = true; +``` + +The bullet flag only affects dynamic bodies. Bullets should be used sparingly. + +### Disabling +You may wish a body to be created but not participate in collision or +simulation. This state is similar to sleeping except the body will not be +woken by other bodies and the body's shapes will not collide with anything. +This means the body will not participate in collisions, ray +casts, etc. + +You can create a body as disabled and later enable it. + +```c +bodyDef.isEnabled = false; + +// Later ... +b3Body_Enable(myBodyId); +``` + +Joints may be connected to disabled bodies. These joints will not be +simulated. You should be careful when you enable a body that its +joints are not distorted. + +Note that enabling a body is almost as expensive as creating the body +from scratch. So you should not use body disabling for streaming worlds. Instead, use +creation/destruction for streaming worlds to save memory. + +### User Data +User data is a void pointer. This gives you a hook to link your +application objects to bodies. You should be consistent to use the same +object type for all body user data. + +```c +bodyDef.userData = &myGameObject; +``` + +This is useful when you receive results from a query such as a ray-cast +or event and you want to get back to your game object. You can acquire the +user data from a body using `b3Body_GetUserData()`. + +### Body Lifetime +Bodies are created and destroyed using a world id. This lets the world create +the body with an efficient allocator and add the body to the world data structure. + +```c +b3BodyId myBodyId = b3CreateBody(myWorldId, &bodyDef); + +// ... do stuff ... + +b3DestroyBody(myBodyId); + +// Nullify body id for safety +myBodyId = b3_nullBodyId; +``` + +Box3D does not keep a reference to the body definition or any of the +data it holds (except user data pointers). So you can create temporary +body definitions and reuse the same body definitions. + +Box3D allows you to avoid destroying bodies by destroying the world +directly using `b3DestroyWorld()`, which does all the cleanup work for you. +However, you should be mindful to nullify body ids that you keep in your application. + +When you destroy a body, the attached shapes and joints are +automatically destroyed. This has important implications for how you +manage shape and joint ids. You should nullify these ids after destroying +a body. + +### Using a Body +After creating a body, there are many operations you can perform on the +body. These include setting mass properties, accessing position and +velocity, applying forces, and transforming points and vectors. + +### Mass Data +A body has mass (scalar), center of mass (`b3Vec3`), and a rotational +inertia tensor (`b3Matrix3`). For static bodies, the mass and rotational inertia are +set to zero. When all angular motion locks are active, the rotational inertia is +effectively zero. + +Normally the mass properties of a body are established automatically +when shapes are added to the body. You can also adjust the mass of a +body at run-time. This is usually done when you have special game +scenarios that require altering the mass. + +```c +b3MassData myMassData; +myMassData.mass = 10.0f; +myMassData.center = (b3Vec3){0.0f, 0.0f, 0.0f}; +myMassData.inertia = b3Mat3_identity; // b3Matrix3 inertia tensor +b3Body_SetMassData(myBodyId, myMassData); +``` + +After setting a body's mass directly, you may wish to revert to the +mass determined by the shapes. You can do this with: + +```c +b3Body_ApplyMassFromShapes(myBodyId); +``` + +The body's mass data is available through the following functions: + +```c +float mass = b3Body_GetMass(myBodyId); +b3Matrix3 inertia = b3Body_GetLocalRotationalInertia(myBodyId); +b3Vec3 localCenter = b3Body_GetLocalCenterOfMass(myBodyId); +b3MassData massData = b3Body_GetMassData(myBodyId); +``` + +### State Information +There are many aspects to the body's state. You can access this state +data through the following functions: + +```c +b3Body_SetType(myBodyId, b3_kinematicBody); +b3BodyType bodyType = b3Body_GetType(myBodyId); +b3Body_SetBullet(myBodyId, true); +bool isBullet = b3Body_IsBullet(myBodyId); +b3Body_EnableSleep(myBodyId, false); +bool isSleepEnabled = b3Body_IsSleepEnabled(myBodyId); +b3Body_SetAwake(myBodyId, true); +bool isAwake = b3Body_IsAwake(myBodyId); +b3Body_Disable(myBodyId); +b3Body_Enable(myBodyId); +bool isEnabled = b3Body_IsEnabled(myBodyId); +b3Body_SetMotionLocks(myBodyId, locks); +b3MotionLocks locks = b3Body_GetMotionLocks(myBodyId); +``` + +Please see the comments on these functions for more details. + +### Position and Velocity +You can access the position and orientation of a body. This is common when +rendering your associated game object. You can also set the position and orientation, +although this is less common since you will normally use Box3D to +simulate movement. + +```c +b3Body_SetTransform(myBodyId, position, rotation); +b3Transform transform = b3Body_GetTransform(myBodyId); +b3Vec3 position = b3Body_GetPosition(myBodyId); +b3Quat rotation = b3Body_GetRotation(myBodyId); +``` + +You can access the center of mass position in local and world +coordinates. Much of the internal simulation in Box3D uses the center of +mass. However, you should normally not need to access it. Instead you +will usually work with the body transform. For example, you may have a +body that is a box. The body origin might be a corner of the box, +while the center of mass is located at the center of the box. + +```c +b3Vec3 worldCenter = b3Body_GetWorldCenterOfMass(myBodyId); +b3Vec3 localCenter = b3Body_GetLocalCenterOfMass(myBodyId); +``` + +You can access the linear and angular velocity. The linear velocity is +for the center of mass. The angular velocity is a `b3Vec3` whose direction +is the axis of rotation and whose magnitude is the rotation rate in radians per second. + +```c +b3Vec3 linearVelocity = b3Body_GetLinearVelocity(myBodyId); +b3Vec3 angularVelocity = b3Body_GetAngularVelocity(myBodyId); +``` + +You can drive a body to a specific transform. This is useful for kinematic bodies. + +```c +b3Vec3 targetPosition = {42.0f, 0.0f, -100.0f}; +b3Quat targetRotation = b3MakeQuatFromAxisAngle(b3Vec3_axisY, B3_PI); +b3Transform target = {targetPosition, targetRotation}; +float timeStep = 1.0f / 60.0f; +b3Body_SetTargetTransform(myBodyId, target, timeStep, true); +``` + +### Forces and Impulses +You can apply forces, torques, and impulses to a body. When you apply a +force or an impulse, you can provide a world point where the load is +applied. This often results in a torque about the center of mass. + +```c +b3Body_ApplyForce(myBodyId, force, worldPoint, wake); +b3Body_ApplyTorque(myBodyId, torque, wake); +b3Body_ApplyLinearImpulse(myBodyId, linearImpulse, worldPoint, wake); +b3Body_ApplyAngularImpulse(myBodyId, angularImpulse, wake); +``` + +All force, torque, and impulse values are `b3Vec3` in world space. Applying a +force, torque, or impulse optionally wakes the body. If you don't +wake the body and it is asleep, then the force or impulse will be ignored. + +You can also apply a force and linear impulse to the center of mass to avoid rotation. + +```c +b3Body_ApplyForceToCenter(myBodyId, force, wake); +b3Body_ApplyLinearImpulseToCenter(myBodyId, linearImpulse, wake); +``` + +> **Caution**: +> Since Box3D uses sub-stepping, you should not apply a steady impulse +> for several frames. Instead you should apply a force which Box3D will +> spread out evenly across the sub-steps, resulting in smoother movement. + +### Coordinate Transformations +The body has some utility functions to help you transform points +and vectors between local and world space. If you don't understand +these concepts, I recommend reading "Essential Mathematics for Games and +Interactive Applications" by Jim Van Verth and Lars Bishop. + +```c +b3Vec3 worldPoint = b3Body_GetWorldPoint(myBodyId, localPoint); +b3Vec3 worldVector = b3Body_GetWorldVector(myBodyId, localVector); +b3Vec3 localPoint = b3Body_GetLocalPoint(myBodyId, worldPoint); +b3Vec3 localVector = b3Body_GetLocalVector(myBodyId, worldVector); +``` + +### Accessing Shapes and Joints +You can access the shapes on a body. You can get the number of shapes first. + +```c +int shapeCount = b3Body_GetShapeCount(myBodyId); +``` + +If you have bodies with many shapes, you can allocate an array or if you +know the number is limited you can use a fixed size array. + +```c +b3ShapeId shapeIds[10]; +int returnCount = b3Body_GetShapes(myBodyId, shapeIds, 10); + +for (int i = 0; i < returnCount; ++i) +{ + b3ShapeId shapeId = shapeIds[i]; + + // do something with shapeId +} +``` + +You can similarly get an array of the joints on a body. + +### Body Events +While you can gather transforms from all your bodies after every time step, this is inefficient. +Many bodies may not have moved because they are sleeping. Also iterating across many bodies +will have lots of cache misses. + +Box3D provides `b3BodyEvents` that you can access after every call to `b3World_Step()` to get +an array of body movement events. Since this data is contiguous, it is cache friendly. + +```c +b3BodyEvents events = b3World_GetBodyEvents(myWorldId); +for (int i = 0; i < events.moveCount; ++i) +{ + const b3BodyMoveEvent* event = events.moveEvents + i; + MyGameObject* gameObject = event->userData; + MoveGameObject(gameObject, event->transform); + if (event->fellAsleep) + { + SleepGameObject(gameObject); + } +} +``` + +The body event also indicates if the body fell asleep this time step. This might be useful to +optimize your application. + +## Shapes +A body may have zero or more shapes. A body with multiple shapes is sometimes +called a *compound body.* + +Shapes hold the following: +- a shape primitive +- density, friction, and restitution (via `baseMaterial`) +- collision filtering flags +- parent body id +- user data +- sensor flag + +These are described in the following sections. + +The geometry types (sphere, capsule, hull, mesh, height field) are documented in detail in +`collision.md`. Compound shapes are documented in `compound.md`. This section covers the +shape lifecycle and material properties. + +### Shape Lifetime +Shapes are created by initializing a shape definition and a shape primitive. +These are passed to a creation function specific to each shape type. + +```c +b3ShapeDef shapeDef = b3DefaultShapeDef(); +shapeDef.density = 10.0f; +shapeDef.baseMaterial.friction = 0.7f; + +b3BoxHull box = b3MakeBoxHull(0.5f, 0.5f, 1.0f); +b3ShapeId myShapeId = b3CreateHullShape(myBodyId, &shapeDef, &box.base); +``` + +This creates a hull shape and attaches it to the body. You do not need to +store the shape id since the shape will automatically be +destroyed when the parent body is destroyed. However, you may wish to store the shape id if you plan +to change properties on it later. + +You can create multiple shapes on a single body. They all can contribute +to the mass of the body. These shapes never collide with each other and may overlap. + +You can destroy a shape on the parent body. You may do this to model a +breakable object. Otherwise you can just leave the shape alone and let +the body destruction take care of destroying the attached shapes. + +```c +b3DestroyShape(myShapeId, true); +``` + +The second argument controls whether the parent body's mass is updated immediately. + +Material properties such as density, friction, and restitution are associated with shapes +instead of bodies. Since you can attach multiple shapes to a body, this allows for more +possible setups. For example, you can make a vehicle that is heavier in the back. + +### Density +The shape density is used to compute the mass properties of the parent +body. The density can be zero or positive. You should generally use +similar densities for all your shapes. This will improve stacking +stability. + +The mass of a body is not adjusted when you set the density. You must +call `b3Body_ApplyMassFromShapes()` for this to occur. Generally you should establish +the shape density in `b3ShapeDef` and avoid modifying it later because this +can be expensive, especially on a compound body. + +```c +b3Shape_SetDensity(myShapeId, 5.0f, true); +b3Body_ApplyMassFromShapes(myBodyId); +``` + +### Friction +Friction is used to make objects slide along each other realistically. +Box3D supports static and dynamic friction, but uses the same parameter +for both. Box3D attempts to simulate friction accurately and the friction +strength is proportional to the normal force. This is called [Coulomb +friction](https://en.wikipedia.org/wiki/Friction). The friction parameter +is usually set between 0 and 1, but +can be any non-negative value. A friction value of 0 turns off friction +and a value of 1 makes the friction strong. When the friction force is +computed between two shapes, Box3D must combine the friction parameters +of the two parent shapes. This is done with the +[geometric mean](https://en.wikipedia.org/wiki/Geometric_mean): + +```c +float mixedFriction = sqrtf(b3Shape_GetFriction(shapeIdA) * b3Shape_GetFriction(shapeIdB)); +``` + +If one shape has zero friction then the mixed friction will be zero. + +Friction is stored as part of the shape's base surface material: + +```c +shapeDef.baseMaterial.friction = 0.5f; +``` + +### Restitution +[Restitution](https://en.wikipedia.org/wiki/Coefficient_of_restitution) is used to make +objects bounce. The restitution value is +usually set to be between 0 and 1. Consider dropping a ball on a table. +A value of zero means the ball won't bounce. This is called an +*inelastic* collision. A value of one means the ball's velocity will be +exactly reflected. This is called a *perfectly elastic* collision. +Restitution is combined using the following formula. + +```c +float mixedRestitution = b3MaxFloat(b3Shape_GetRestitution(shapeIdA), b3Shape_GetRestitution(shapeIdB)); +``` + +Restitution is combined this way so that you can have a bouncy super +ball without having a bouncy floor. + +When a shape develops multiple contacts, restitution is simulated +approximately. This is because Box3D uses a sequential solver. Box3D +also uses inelastic collisions when the collision velocity is small. +This is done to prevent jitter. See `b3WorldDef::restitutionThreshold`. + +Restitution is stored as part of the shape's base surface material: + +```c +shapeDef.baseMaterial.restitution = 0.3f; +``` + +### Friction and Restitution Callbacks +Advanced users can override friction and restitution mixing using `b3FrictionCallback` +and `b3RestitutionCallback`. These should be very lightweight functions because they +are called frequently. The callbacks receive the two friction (or restitution) values +and the user material ids from each shape's surface material. + +```c +float MyFrictionCallback(float frictionA, uint64_t userMaterialIdA, + float frictionB, uint64_t userMaterialIdB) +{ + if (userMaterialIdA > userMaterialIdB) + { + return frictionA; + } + + return frictionB; +} + +b3WorldDef worldDef = b3DefaultWorldDef(); +worldDef.frictionCallback = MyFrictionCallback; +``` + +### Filtering {#filtering} +Collision filtering allows you to efficiently prevent collision between shapes. +For example, say you make a character that rides a bicycle. You want the +bicycle to collide with the terrain and the character to collide with +the terrain, but you don't want the character to collide with the +bicycle (because they must overlap). Box3D supports such collision +filtering using categories, masks, and groups. + +Box3D supports 64 collision categories (stored as `uint64_t`). For each shape you can specify +which category it belongs to. You can also specify what other categories +this shape can collide with. For example, you could specify in a +multiplayer game that players don't collide with each other. Rather +than identifying all the situations where things should not collide, I recommend +identifying all the situations where things should collide. This way you +don't get into situations where you are using +[double negatives](https://en.wikipedia.org/wiki/Double_negative). +You can specify which things can collide using mask bits. For example: + +```c +enum MyCategories +{ + PLAYER = 0x00000002, + MONSTER = 0x00000004, +}; + +b3ShapeDef playerShapeDef = b3DefaultShapeDef(); +b3ShapeDef monsterShapeDef = b3DefaultShapeDef(); +playerShapeDef.filter.categoryBits = PLAYER; +monsterShapeDef.filter.categoryBits = MONSTER; + +// Players collide with monsters, but not with other players +playerShapeDef.filter.maskBits = MONSTER; + +// Monsters collide with players and other monsters +monsterShapeDef.filter.maskBits = PLAYER | MONSTER; +``` + +Here is the rule for a collision to occur: + +```c +uint64_t catA = shapeA.filter.categoryBits; +uint64_t maskA = shapeA.filter.maskBits; +uint64_t catB = shapeB.filter.categoryBits; +uint64_t maskB = shapeB.filter.maskBits; + +if ((catA & maskB) != 0 && (catB & maskA) != 0) +{ + // shapes can collide +} +``` + +Another filtering feature is *collision groups*. +Collision groups let you specify a group index. You can have +all shapes with the same group index always collide (positive index) +or never collide (negative index). Group indices are usually used for +things that are somehow related, like the parts of a vehicle. In the +following example, shape1 and shape2 always collide, but shape3 +and shape4 never collide. + +```c +shape1Def.filter.groupIndex = 2; +shape2Def.filter.groupIndex = 2; +shape3Def.filter.groupIndex = -8; +shape4Def.filter.groupIndex = -8; +``` + +Collisions between shapes of different group indices are filtered +according the category and mask bits. If two shapes have the +same non-zero group index, then this overrides the category and mask. +Collision groups have a higher priority than categories and masks. + +Note that additional collision filtering occurs automatically in Box3D. Here is a +list: +- A shape on a static body can only collide with a dynamic body. +- A shape on a kinematic body can only collide with a dynamic body. +- Shapes on the same body never collide with each other. +- You can optionally enable/disable collision between bodies connected by a joint. + +Sometimes you might need to change collision filtering after a shape +has already been created. You can get and set the `b3Filter` structure on +an existing shape using `b3Shape_GetFilter()` and +`b3Shape_SetFilter()`. Changing the filter is expensive because +it causes contacts to be destroyed. + +### Sensors +Sometimes game logic needs to know when two shapes overlap yet there +should be no collision response. This is done by using sensors. A sensor +is a shape that detects overlap but does not produce a response. + +You can flag any shape as being a sensor. Sensors may be static, +kinematic, or dynamic. Remember that you may have multiple shapes per +body and you can have any mix of sensors and solid shapes. Sensors can also +detect other sensors. Sensor shapes have mass like regular shapes. You can set +the density to zero if you don't want a sensor to have mass. + +```c +b3ShapeDef shapeDef = b3DefaultShapeDef(); +shapeDef.isSensor = true; +``` + +For both sensors and non-sensors, sensor events must also be enabled. There is a +performance cost to generate sensor events, so they are disabled by default. + +```c +shapeDef.enableSensorEvents = true; +``` + +Both shapes involved must have this flag set to true. This allows a game to disable a +specific sensor using `b3Shape_EnableSensorEvents`. + +Sensors are processed at the end of the world step and generate begin and end +events without delay. User operations may cause overlaps to begin or end. These +are processed the next time step. Such operations include: +- destroying a body or shape +- changing a shape filter +- disabling or enabling a body +- setting a body transform +- disabling or enabling sensor events on a shape + +Sensors do not detect objects that pass through the sensor shape within +one time step. So sensors do not have continuous collision detection. +If you have a fast moving object and/or small sensors then you should use a +ray or shape cast to detect these events. + +You can access the current sensor overlaps from the previous world step. Be careful because some +shape ids may be invalid due to a shape being destroyed. Use `b3Shape_IsValid` to ensure an +overlapping shape is still valid. + +```c +// First determine the required array capacity to hold all the overlapping shape ids. +int capacity = b3Shape_GetSensorCapacity(sensorShapeId); +b3ShapeId overlaps[64]; // or dynamically allocate capacity items + +// Now get all overlaps and record the actual count +int count = b3Shape_GetSensorData(sensorShapeId, overlaps, capacity); + +for (int i = 0; i < count; ++i) +{ + b3ShapeId visitorId = overlaps[i]; + + // Ensure the visitorId is valid + if (b3Shape_IsValid(visitorId) == false) + { + continue; + } + + // process overlap using game logic +} +``` + +Sensor overlap can also be determined using events, which are described below. + +### Sensor Events +Sensor events are available after every call to `b3World_Step()`. +Sensor events are the best way to get information about sensor overlaps. There are +events for when a shape begins to overlap with a sensor. + +```c +b3SensorEvents sensorEvents = b3World_GetSensorEvents(myWorldId); +for (int i = 0; i < sensorEvents.beginCount; ++i) +{ + b3SensorBeginTouchEvent* beginTouch = sensorEvents.beginEvents + i; + void* myUserData = b3Shape_GetUserData(beginTouch->visitorShapeId); + // process begin event +} +``` + +And there are events when a shape stops overlapping with a sensor. Be careful with end +touch events because they may be generated when shapes are destroyed. Test the shape +ids with `b3Shape_IsValid`. + +```c +for (int i = 0; i < sensorEvents.endCount; ++i) +{ + b3SensorEndTouchEvent* endTouch = sensorEvents.endEvents + i; + if (b3Shape_IsValid(endTouch->visitorShapeId)) + { + void* myUserData = b3Shape_GetUserData(endTouch->visitorShapeId); + // process end event + } +} +``` + +Sensor events should be processed after the world step and before other game logic. This should +help you avoid processing stale data. + +Sensor events are only enabled for shapes if `b3ShapeDef::enableSensorEvents` is set to true. + +> **Note**: +> A shape cannot start or stop being a sensor. Such a feature would break +> sensor events, potentially causing bugs in game logic. + +## Contacts +Contacts are internal objects created by Box3D to manage collision between pairs of +shapes. They are fundamental to rigid body simulation in games. + +### Terminology +Contacts have a fair bit of terminology that are important to review. + +#### contact point +A contact point is a point where two shapes touch. Box3D approximates +contact with a small number of points. + +#### contact normal +A contact normal is a unit vector that points from one shape to another. +By convention, the normal points from shapeA to shapeB. + +#### contact separation +Separation is the opposite of penetration. Separation is negative when +shapes overlap. + +#### contact manifold +Contact between two convex shapes may generate multiple contact points. +These points share the same normal, so they are grouped into a +contact manifold, which is an approximation of a continuous region of +contact. + +#### normal impulse +The normal force is the force applied at a contact point to prevent the +shapes from penetrating. For convenience, Box3D uses impulses. The +normal impulse is just the normal force multiplied by the time step. Since +Box3D uses sub-stepping, this is the sub-step time step. + +#### tangent impulse +The tangent force is generated at a contact point to simulate friction. +For convenience, this is stored as an impulse. + +#### contact point id +Box3D tries to re-use the contact impulse results from a time step as the +initial guess for the next time step. Box3D uses contact point ids to match +contact points across time steps. The ids contain geometric feature +indices that help to distinguish one contact point from another. + +#### speculative contact +When two shapes are close together, Box3D will create contact +points even if the shapes are not touching. This lets Box3D anticipate +collision to improve behavior. Speculative contact points have positive +separation. + +### Contact Lifetime +Contacts are created when two shapes' AABBs (bounding boxes) begin to overlap. Sometimes +collision filtering will prevent the creation of contacts. Contacts are +destroyed when the AABBs cease to overlap. + +So you might gather that there may be contacts created for shapes that +are not touching (just their AABBs). Well, this is correct. It's a +"chicken or egg" problem. We don't know if we need a contact object +until one is created to analyze the collision. We could delete the +contact right away if the shapes are not touching, or we can just wait +until the AABBs stop overlapping. Box3D takes the latter approach +because it lets the system cache information to improve performance. + +### Contact Data +As mentioned before, the contact is created and destroyed by +Box3D automatically. Contact data is not created by the user. However, you are +able to access the contact data. + +You can get contact data from shapes or bodies. The contact data +on a shape is a sub-set of the contact data on a body. The contact +data is only returned for touching contacts. Contacts that are not +touching provide no meaningful information for an application. + +Contact data is returned in arrays. So first you can ask a shape or +body how much space you'll need in your array. This number is conservative +and the actual number of contacts you'll receive may be less than +this number, but never more. + +```c +int shapeContactCapacity = b3Shape_GetContactCapacity(myShapeId); +int bodyContactCapacity = b3Body_GetContactCapacity(myBodyId); +``` + +You could allocate array space to get all the contact data in all cases, or you could use a fixed size +array and get a limited number of results. + +```c +b3ContactData contactData[10]; +int shapeContactCount = b3Shape_GetContactData(myShapeId, contactData, 10); +int bodyContactCount = b3Body_GetContactData(myBodyId, contactData, 10); +``` + +`b3ContactData` contains the two shape ids and the manifold array. + +```c +for (int i = 0; i < bodyContactCount; ++i) +{ + b3ContactData* data = contactData + i; + printf("manifold count = %d\n", data->manifoldCount); +} +``` + +Getting contact data off shapes and bodies is not the most efficient +way to handle contact data. Instead you should use contact events. + +### Contact Events +Contact events are available after each world step. Like sensor events these should be +retrieved and processed before performing other game logic. Otherwise +you may be accessing orphaned/invalid data. + +You can access all contact events in a single data structure. This is much more efficient +than using functions like `b3Body_GetContactData()`. + +```c +b3ContactEvents contactEvents = b3World_GetContactEvents(myWorldId); +``` + +None of this data applies to sensors because they are handled separately. All events involve +at least one dynamic body. + +There are three kinds of contact events: +1. Begin touch events +2. End touch events +3. Hit events + +#### Contact Touch Event +`b3ContactBeginTouchEvent` is recorded when two shapes begin touching. + +```c +for (int i = 0; i < contactEvents.beginCount; ++i) +{ + b3ContactBeginTouchEvent* beginEvent = contactEvents.beginEvents + i; + ShapesStartTouching(beginEvent->shapeIdA, beginEvent->shapeIdB); +} +``` + +`b3ContactEndTouchEvent` is recorded when two shapes stop touching. + +```c +for (int i = 0; i < contactEvents.endCount; ++i) +{ + b3ContactEndTouchEvent* endEvent = contactEvents.endEvents + i; + + // Use b3Shape_IsValid because a shape may have been destroyed + if (b3Shape_IsValid(endEvent->shapeIdA) && b3Shape_IsValid(endEvent->shapeIdB)) + { + ShapesStopTouching(endEvent->shapeIdA, endEvent->shapeIdB); + } +} +``` + +Similar to `b3SensorEndTouchEvent`, `b3ContactEndTouchEvent` may be generated due to a user operation, +such as destroying a body or shape. These events are included with simulation events after the next `b3World_Step`. + +Shapes only generate begin and end touch events if `b3ShapeDef::enableContactEvents` is true. + +#### Hit Events +Typically in games you are mainly concerned about getting contact events for when +two shapes collide at a significant speed so you can play a sound and/or particle effect. Hit +events are the answer for this. + +```c +for (int i = 0; i < contactEvents.hitCount; ++i) +{ + b3ContactHitEvent* hitEvent = contactEvents.hitEvents + i; + if (hitEvent->approachSpeed > 10.0f) + { + // play sound + } +} +``` + +Shapes only generate hit events if `b3ShapeDef::enableHitEvents` is true. +Only enable this for shapes that need hit events because +it creates some overhead. Box3D also only reports hit events that have an +approach speed larger than `b3WorldDef::hitEventThreshold`. + +### Contact Filtering +Often in a game you don't want all objects to collide. For example, you +may want to create a door that only certain characters can pass through. +This is called contact filtering, because some interactions are filtered +out. + +Contact filtering is setup on shapes and is covered [here](#filtering). + +### Advanced Contact Handling + +#### Custom Filtering Callback +For the best performance, use the contact filtering provided by `b3Filter`. +However, in some cases you may need custom filtering. You can do +this by registering a custom filter callback that implements `b3CustomFilterFcn()`. + +```c +bool MyCustomFilter(b3ShapeId shapeIdA, b3ShapeId shapeIdB, void* context) +{ + MyGame* myGame = context; + return myGame->WantsCollision(shapeIdA, shapeIdB); +} + +// Elsewhere +b3World_SetCustomFilterCallback(myWorldId, MyCustomFilter, myGame); +``` + +This function must be [thread-safe](https://en.wikipedia.org/wiki/Thread_safety) and must not read from or write to the Box3D world. Otherwise you will get a [race condition](https://en.wikipedia.org/wiki/Race_condition). + +#### Pre-Solve Callback +This is called after collision detection, but before collision +resolution. This gives you a chance to disable the contact based on the contact geometry. For example, you can implement a one-sided platform using this callback. + +The contact will be re-enabled each time through collision processing, +so you will need to disable the contact every time-step. This function must be thread-safe +and must not read from or write to the Box3D world. + +The pre-solve callback for Box3D receives the two shape ids, the contact point, and the contact normal: + +```c +bool MyPreSolve(b3ShapeId shapeIdA, b3ShapeId shapeIdB, + b3Vec3 point, b3Vec3 normal, void* context) +{ + MyGame* myGame = context; + + if (myGame->ShouldDisableContact(shapeIdA, shapeIdB, point, normal)) + { + return false; + } + + return true; +} + +// Elsewhere +b3World_SetPreSolveCallback(myWorldId, MyPreSolve, myGame); +``` + +Note this currently does not work with high speed collisions, so you may see a +pause in those situations. + +## Joints +Joints are used to constrain bodies to the world or to each other. +Typical examples in games include ragdolls, teeters, and pulleys. Joints +can be combined in many different ways to create interesting motions. + +Some joints provide limits so you can control the range of motion. Some +joints provide motors which can be used to drive the joint at a +prescribed speed until a prescribed force/torque is exceeded. And some +joints provide springs with damping. + +Joint motors can be used in many ways. You can use motors to control +position by specifying a joint velocity that is proportional to the +difference between the actual and desired position. You can also use +motors to simulate joint friction: set the joint velocity to zero and +provide a small, but significant maximum motor force/torque. Then the +motor will attempt to keep the joint from moving until the load becomes +too strong. + +### Joint Definition +Each joint type has an associated joint definition that embeds a `b3JointDef` base. +All joints are connected between two different bodies. One body may be static. +Joints between static and/or kinematic bodies are allowed, but have no +effect and use some processing time. + +If a joint is connected to a disabled body, that joint is effectively disabled. +When both bodies on a joint become enabled, the joint will automatically +be enabled as well. In other words, you do not need to explicitly enable +or disable a joint. + +You can specify user data for any joint type and you can provide a flag +to prevent the attached bodies from colliding with each other. This is +the default behavior and you must set `collideConnected` to true +to allow collision between two connected bodies. + +Many joint definitions require that you provide some geometric data. +In Box3D joints use *local frames* (`b3Transform localFrameA` and `b3Transform localFrameB`) +rather than anchor points. The local frame specifies both the attachment point and the +orientation axes used to measure joint quantities. These frames are specified in the local +space of the attached bodies. This way the joint can be specified even when the +current body transforms violate the joint constraint. + +### Joint Lifetime +Joints are created using creation functions supplied for each joint type. They are destroyed +with a shared function. All joint types share a single id type `b3JointId`. + +Here's an example of the lifetime of a revolute joint: + +```c +b3RevoluteJointDef jointDef = b3DefaultRevoluteJointDef(); +jointDef.base.bodyIdA = myBodyA; +jointDef.base.bodyIdB = myBodyB; +// Set up local frames so the hinge aligns with the desired pivot +jointDef.base.localFrameA = b3Transform_identity; +jointDef.base.localFrameB = b3Transform_identity; + +b3JointId myJointId = b3CreateRevoluteJoint(myWorldId, &jointDef); + +// ... do stuff ... + +b3DestroyJoint(myJointId, false); +myJointId = b3_nullJointId; +``` + +It is always good to nullify your ids after they are destroyed. + +Joint lifetime is related to body lifetime. Joints cannot exist detached from a body. +So when a body is destroyed, all joints attached to that body are automatically destroyed. +This means you need to be careful to avoid using joint ids when the attached body was +destroyed. Box3D will assert if you use a dangling joint id. + +> **Caution**: +> Joints are destroyed when an attached body is destroyed. + +Fortunately you can check if your joint id is valid. + +```c +if (b3Joint_IsValid(myJointId) == false) +{ + myJointId = b3_nullJointId; +} +``` + +### Using Joints +Many simulations create the joints and don't access them again until +they are destroyed. However, there is a lot of useful data contained in +joints that you can use to create a rich simulation. + +First of all, you can get the type, bodies, local frames, and user data from +a joint. + +```c +b3JointType jointType = b3Joint_GetType(myJointId); +b3BodyId bodyIdA = b3Joint_GetBodyA(myJointId); +b3BodyId bodyIdB = b3Joint_GetBodyB(myJointId); +b3Transform localFrameA = b3Joint_GetLocalFrameA(myJointId); +b3Transform localFrameB = b3Joint_GetLocalFrameB(myJointId); +void* myUserData = b3Joint_GetUserData(myJointId); +``` + +All joints have a reaction force and torque. Reaction forces are +related to the [free body diagram](https://en.wikipedia.org/wiki/Free_body_diagram). +The Box3D convention is that the reaction force +is applied to body B at the anchor point. You can use reaction forces to +break joints or trigger other game events. These functions may do some +computations, so don't call them if you don't need the result. + +```c +b3Vec3 force = b3Joint_GetConstraintForce(myJointId); +b3Vec3 torque = b3Joint_GetConstraintTorque(myJointId); +``` + +### Distance Joint +One of the simplest joints is a distance joint which says that the +distance between two anchor points on two bodies must be constant. When you +specify a distance joint the two bodies should already be in place. Then +you specify the two anchor points via local frames. These points imply the +length of the distance constraint. + + + +Here is an example of a distance joint definition: + +```c +b3DistanceJointDef jointDef = b3DefaultDistanceJointDef(); +jointDef.base.bodyIdA = myBodyIdA; +jointDef.base.bodyIdB = myBodyIdB; + +// Place anchor A at world point anchorA, measured in body A's local frame +b3Vec3 localAnchorA = b3Body_GetLocalPoint(myBodyIdA, anchorA); +b3Vec3 localAnchorB = b3Body_GetLocalPoint(myBodyIdB, anchorB); +jointDef.base.localFrameA.p = localAnchorA; +jointDef.base.localFrameB.p = localAnchorB; +jointDef.length = b3Distance(anchorA, anchorB); +jointDef.base.collideConnected = true; + +b3JointId myJointId = b3CreateDistanceJoint(myWorldId, &jointDef); +``` + +The distance joint can also be made soft, like a spring-damper +connection. Softness is achieved by enabling the spring and tuning two values in the definition: +Hertz and damping ratio. + +```c +jointDef.enableSpring = true; +jointDef.hertz = 2.0f; +jointDef.dampingRatio = 0.5f; +``` + +The hertz is the frequency of a [harmonic oscillator](https://en.wikipedia.org/wiki/Harmonic_oscillator) (like a +guitar string). Typically the frequency +should be less than a half the frequency of the time step. So if you are using +a 60Hz time step, the frequency of the distance joint should be less than 30Hz. +The reason is related to the [Nyquist frequency](https://en.wikipedia.org/wiki/Nyquist_frequency). + +The damping ratio controls how fast the oscillations dissipate. A damping +ratio of one is [critical damping](https://en.wikipedia.org/wiki/Damping) and prevents +oscillation. + +It is also possible to define a minimum and maximum length for the distance joint. +You can even motorize the distance joint to adjust its length dynamically. +See `b3DistanceJointDef` and the `DistanceJoint` sample for details. + +### Revolute Joint +A revolute joint (also called a *hinge* or *pin* joint) forces two bodies to share a +common anchor point and allows relative rotation about a single axis — the z-axis of the +local frame. It has one rotational degree of freedom. + + + +The joint angle is measured as the twist of frame B's z-axis relative to frame A's z-axis. + +```c +b3RevoluteJointDef jointDef = b3DefaultRevoluteJointDef(); +jointDef.base.bodyIdA = myBodyIdA; +jointDef.base.bodyIdB = myBodyIdB; +jointDef.base.localFrameA.p = b3Body_GetLocalPoint(myBodyIdA, worldPivot); +jointDef.base.localFrameB.p = b3Body_GetLocalPoint(myBodyIdB, worldPivot); + +b3JointId myJointId = b3CreateRevoluteJoint(myWorldId, &jointDef); +``` + +In some cases you might wish to control the joint angle. For this, the +revolute joint can simulate a joint limit and/or a motor. + +A joint limit forces the joint angle to remain between a lower and upper +angle. The limit will apply as much torque as needed to make this +happen. The limit range should include zero, otherwise the joint will +lurch when the simulation begins. + +A joint motor allows you to specify the joint speed. The speed can be negative or +positive. A motor can have infinite torque, but this is usually not desirable. Recall the eternal +question: + +> *What happens when an irresistible force meets an immovable object?* + +I can tell you it's not pretty. So you can provide a maximum torque for +the joint motor. The joint motor will maintain the specified speed +unless the required torque exceeds the specified maximum. When the +maximum torque is exceeded, the joint will slow down and can even +reverse. + +You can use a joint motor to simulate joint friction. Just set the joint +speed to zero, and set the maximum torque to some small, but significant +value. The motor will try to prevent the joint from rotating, but will +yield to a significant load. + +Here's an example revolute joint with a limit and a motor enabled. The motor is setup to simulate +joint friction. + +```c +jointDef.base.localFrameA.p = b3Body_GetLocalPoint(myBodyIdA, worldPivot); +jointDef.base.localFrameB.p = b3Body_GetLocalPoint(myBodyIdB, worldPivot); +jointDef.lowerAngle = -0.5f * B3_PI; // -90 degrees +jointDef.upperAngle = 0.25f * B3_PI; // 45 degrees +jointDef.enableLimit = true; +jointDef.maxMotorTorque = 10.0f; +jointDef.motorSpeed = 0.0f; +jointDef.enableMotor = true; +``` + +You can access a revolute joint's angle, speed, and motor torque. + +```c +float angleInRadians = b3RevoluteJoint_GetAngle(myJointId); +float speed = b3RevoluteJoint_GetMotorSpeed(myJointId); +float currentTorque = b3RevoluteJoint_GetMotorTorque(myJointId); +``` + +You can also update the motor parameters each step. + +```c +b3RevoluteJoint_SetMotorSpeed(myJointId, 20.0f); +b3RevoluteJoint_SetMaxMotorTorque(myJointId, 100.0f); +``` + +Joint motors have some interesting abilities. You can update the joint +speed every time step so you can make the joint move back-and-forth like +a sine-wave or according to whatever function you want. + +```c +// ... Game Loop Begin ... +b3RevoluteJoint_SetMotorSpeed(myJointId, cosf(0.5f * time)); +// ... Game Loop End ... +``` + +### Prismatic Joint +A prismatic joint (also called a *slider* joint) allows for relative translation of two bodies +along the x-axis of local frame A. A prismatic joint prevents relative rotation. +Therefore, a prismatic joint has a single degree of freedom. + + + +The prismatic joint definition is similar to the revolute joint +description; just substitute translation for angle and force for torque. +Using this analogy provides an example prismatic joint definition with a +joint limit and a friction motor: + +```c +b3PrismaticJointDef jointDef = b3DefaultPrismaticJointDef(); +jointDef.base.bodyIdA = myBodyIdA; +jointDef.base.bodyIdB = myBodyIdB; +jointDef.base.localFrameA.p = b3Body_GetLocalPoint(myBodyIdA, worldPivot); +jointDef.base.localFrameB.p = b3Body_GetLocalPoint(myBodyIdB, worldPivot); +jointDef.lowerTranslation = -5.0f; +jointDef.upperTranslation = 2.5f; +jointDef.enableLimit = true; +jointDef.maxMotorForce = 1.0f; +jointDef.motorSpeed = 0.0f; +jointDef.enableMotor = true; + +b3JointId myJointId = b3CreatePrismaticJoint(myWorldId, &jointDef); +``` + +The slide axis is the x-axis of local frame A. + +The prismatic joint translation is zero when the frame origins coincide. + +Using a prismatic joint is similar to using a revolute joint. Here are +the relevant functions: + +```c +float translation = b3PrismaticJoint_GetTranslation(myJointId); +float speed = b3PrismaticJoint_GetSpeed(myJointId); +float motorForce = b3PrismaticJoint_GetMotorForce(myJointId); +b3PrismaticJoint_SetMotorSpeed(myJointId, speed); +b3PrismaticJoint_SetMaxMotorForce(myJointId, force); +``` + +### Weld Joint +The weld joint attempts to constrain all relative motion between two +bodies. Both translation and rotation can have spring-damper softness. +See `b3WeldJointDef` and the `Cantilever` sample for details. + +It is tempting to use the weld joint to define breakable structures. +However, the Box3D solver is approximate so the joints can be soft in some +cases regardless of the joint settings. So chains of bodies connected by weld +joints may flex. + +```c +b3WeldJointDef jointDef = b3DefaultWeldJointDef(); +jointDef.base.bodyIdA = myBodyIdA; +jointDef.base.bodyIdB = myBodyIdB; +jointDef.linearHertz = 0.0f; // 0 = rigid +jointDef.angularHertz = 0.0f; // 0 = rigid +jointDef.linearDampingRatio = 1.0f; +jointDef.angularDampingRatio = 1.0f; + +b3JointId myJointId = b3CreateWeldJoint(myWorldId, &jointDef); +``` + +### Motor Joint +A motor joint lets you control the motion of a body by specifying target +linear and angular velocities. You can set the maximum motor force and +torque that will be applied. If the body is blocked, it will stop and the +contact forces will be proportional to the maximum motor force and torque. + +The motor joint also has an optional position spring that drives the +relative transform toward a target. See `b3MotorJointDef` and +the `MotorJoint` sample for details. + +```c +b3MotorJointDef jointDef = b3DefaultMotorJointDef(); +jointDef.base.bodyIdA = myBodyIdA; +jointDef.base.bodyIdB = myBodyIdB; +jointDef.linearVelocity = (b3Vec3){0.0f, 0.0f, 0.0f}; +jointDef.maxVelocityForce = 1000.0f; +jointDef.angularVelocity = (b3Vec3){0.0f, 1.0f, 0.0f}; +jointDef.maxVelocityTorque = 500.0f; + +b3JointId myJointId = b3CreateMotorJoint(myWorldId, &jointDef); +``` + +### Wheel Joint +The wheel joint is designed specifically for vehicles. Body A is the chassis and +body B is the wheel. The wheel: +- translates along the x-axis of frame A (suspension direction), +- spins about the z-axis of frame B, +- optionally steers about the suspension axis. + + + +The translation has a spring and damper to simulate vehicle +suspension. The spin allows the wheel to rotate. You can specify a rotational +motor to drive the wheel and to apply braking. Steering adds a rotation about the +suspension axis. See `b3WheelJointDef` and the `Drive` sample for details. + +```c +b3WheelJointDef jointDef = b3DefaultWheelJointDef(); +jointDef.base.bodyIdA = chassisBodyId; +jointDef.base.bodyIdB = wheelBodyId; +jointDef.enableSuspensionSpring = true; +jointDef.suspensionHertz = 4.0f; +jointDef.suspensionDampingRatio = 0.7f; +jointDef.enableSpinMotor = true; +jointDef.maxSpinTorque = 300.0f; +jointDef.spinSpeed = 0.0f; +jointDef.enableSteering = true; +jointDef.steeringHertz = 5.0f; +jointDef.steeringDampingRatio = 0.7f; + +b3JointId myJointId = b3CreateWheelJoint(myWorldId, &jointDef); +``` + +### Spherical Joint +A spherical joint (also called a *ball-in-socket* or *point-to-point* joint) fixes a point on +body B to a point on body A and allows free rotation about all three axes. This gives 3 +rotational degrees of freedom with no translation. + + + +The cone limit restricts how far the z-axis of frame B can deviate from the z-axis of frame A. +The twist limit restricts rotation about the z-axis of frame B. + +```c +b3SphericalJointDef jointDef = b3DefaultSphericalJointDef(); +jointDef.base.bodyIdA = myBodyIdA; +jointDef.base.bodyIdB = myBodyIdB; + +// Cone limit: allows ±45 degrees of swing +jointDef.enableConeLimit = true; +jointDef.coneAngle = 0.25f * B3_PI; // half-angle, radians + +// Twist limit: ±30 degrees of twist about z +jointDef.enableTwistLimit = true; +jointDef.lowerTwistAngle = -B3_PI / 6.0f; +jointDef.upperTwistAngle = B3_PI / 6.0f; + +b3JointId myJointId = b3CreateSphericalJoint(myWorldId, &jointDef); +``` + +At runtime you can query and adjust the limits: + +```c +b3SphericalJoint_EnableConeLimit(myJointId, true); +b3SphericalJoint_SetConeLimit(myJointId, 0.3f); +float currentConeAngle = b3SphericalJoint_GetConeAngle(myJointId); + +b3SphericalJoint_EnableTwistLimit(myJointId, true); +b3SphericalJoint_SetTwistLimits(myJointId, -0.5f, 0.5f); +float twistAngle = b3SphericalJoint_GetTwistAngle(myJointId); +``` + +The spherical joint also supports an optional alignment spring. When enabled it drives +the relative orientation toward a target quaternion using a spring-damper: + +```c +jointDef.enableSpring = true; +jointDef.hertz = 5.0f; +jointDef.dampingRatio = 0.7f; +jointDef.targetRotation = b3Quat_identity; +``` + +And an angular velocity motor: + +```c +jointDef.enableMotor = true; +jointDef.motorVelocity = (b3Vec3){0.0f, 1.0f, 0.0f}; +jointDef.maxMotorTorque = 100.0f; +``` + +### Parallel Joint +The parallel joint constrains the z-axis of body B to remain parallel to the z-axis of +body A, using a spring-damper. This is useful for keeping a body upright without fully +fixing its translation or other rotation axes. + + + +```c +b3ParallelJointDef jointDef = b3DefaultParallelJointDef(); +jointDef.base.bodyIdA = myBodyIdA; +jointDef.base.bodyIdB = myBodyIdB; +jointDef.hertz = 5.0f; +jointDef.dampingRatio = 0.7f; +jointDef.maxTorque = 200.0f; + +b3JointId myJointId = b3CreateParallelJoint(myWorldId, &jointDef); +``` + +You can also adjust the spring and torque limit at runtime: + +```c +b3ParallelJoint_SetSpringHertz(myJointId, 8.0f); +b3ParallelJoint_SetSpringDampingRatio(myJointId, 0.5f); +b3ParallelJoint_SetMaxTorque(myJointId, 500.0f); +``` + +### Filter Joint +The filter (or null) joint is used to disable collision between two specific bodies. +As a side effect of being a joint, it also keeps the two bodies in the same simulation +island, which can be useful for performance. + +```c +b3FilterJointDef jointDef = b3DefaultFilterJointDef(); +jointDef.base.bodyIdA = myBodyIdA; +jointDef.base.bodyIdB = myBodyIdB; + +b3JointId myJointId = b3CreateFilterJoint(myWorldId, &jointDef); +``` + +## Spatial Queries {#spatial} +Spatial queries allow you to inspect the world geometrically. There are overlap queries, +ray-casts, and shape-casts. These allow you to do things like: +- find a treasure chest near the player +- shoot a laser beam and destroy all objects in the path +- throw a grenade that is represented as a sphere moving along a parabolic path + +### Overlap Queries +Sometimes you want to determine all the shapes in a region. The world has a fast +log(N) method for this using the broad-phase data structure. Box3D provides these +overlap tests: +- axis-aligned bounding box (AABB) overlap +- shape proxy overlap + +![Overlap Test](images/overlap_test.svg) + +#### Query Filtering +A basic understanding of query filtering is needed before considering the specific queries. +Shape versus shape filtering was discussed [here](#filtering). A similar setup is used +for queries. This lets your queries only consider certain categories of shapes, and also +lets your shapes ignore certain queries. + +Just like shapes, queries themselves can have a category. For example, you can have a `CAMERA` +or `PROJECTILE` category. + +```c +enum MyCategories +{ + STATIC = 0x00000001, + PLAYER = 0x00000002, + MONSTER = 0x00000004, + WINDOW = 0x00000008, + CAMERA = 0x00000010, + PROJECTILE = 0x00000020, +}; + +// Grenades collide with the static world, monsters, and windows but +// not players or other projectiles. +b3QueryFilter grenadeFilter; +grenadeFilter.categoryBits = PROJECTILE; +grenadeFilter.maskBits = STATIC | MONSTER | WINDOW; + +// The view collides with the static world, monsters, and players. +b3QueryFilter viewFilter; +viewFilter.categoryBits = CAMERA; +viewFilter.maskBits = STATIC | PLAYER | MONSTER; +``` + +If you want to query everything you can use `b3DefaultQueryFilter()`. + +#### AABB Overlap +You provide a `b3AABB` in world coordinates and an +implementation of `b3OverlapResultFcn()`. The world calls your function with each +shape whose AABB overlaps the query AABB. Return true to continue the +query, otherwise return false. For example, the following code finds all +the shapes that potentially intersect a specified AABB and wakes up +all of the associated bodies. + +```c +bool MyOverlapCallback(b3ShapeId shapeId, void* context) +{ + b3BodyId bodyId = b3Shape_GetBody(shapeId); + b3Body_SetAwake(bodyId, true); + + // Return true to continue the query. + return true; +} + +// Elsewhere ... +b3AABB aabb; +aabb.lowerBound = (b3Vec3){-1.0f, -1.0f, -1.0f}; +aabb.upperBound = (b3Vec3){ 1.0f, 1.0f, 1.0f}; +b3QueryFilter filter = b3DefaultQueryFilter(); +b3World_OverlapAABB(myWorldId, aabb, filter, MyOverlapCallback, &myGame); +``` + +Do not make any assumptions about the order of the callback. The order shapes +are returned to your callback may seem arbitrary. + +#### Shape Overlap +The AABB overlap is very fast but not very accurate because it only considers +the shape bounding box. If you want an accurate overlap test, you can use a shape +overlap query. + +The overlap function uses a `b3ShapeProxy` which is an abstract shape consisting +of some points and a radius. You can think of it as a cloud of spheres that has been +*shrink wrapped*. This can represent a point, a sphere, a capsule, a convex hull, +and so on. + +In this example, I'm creating a shape proxy from a sphere and then calling `b3World_OverlapShape()`. +This takes a `b3OverlapResultFcn()` to receive results and control the search progress. + +```c +b3Sphere sphere = {{0.0f, 0.0f, 0.0f}, 0.2f}; +b3ShapeProxy proxy; +proxy.points = &sphere.center; +proxy.count = 1; +proxy.radius = sphere.radius; +b3World_OverlapShape(myWorldId, &proxy, grenadeFilter, MyOverlapCallback, &myGame); +``` + +### Ray-casts +You can use ray-casts to do line-of-sight checks, fire guns, etc. You +perform a ray-cast by implementing the `b3CastResultFcn()` callback +function and providing the +origin point and translation. The world calls your function with each shape +hit by the ray. Your callback is provided with the shape, the point of +intersection, the unit normal vector, and the fractional distance along +the ray. You cannot make any assumptions about the order of the points +sent to the callback. The callback may receive points that are further away +before receiving points that are closer. + +![Ray Cast](images/raycast.svg) + +You control the continuation of the ray-cast by returning a fraction. +Returning a fraction of zero indicates the ray-cast should be +terminated. A fraction of one indicates the ray-cast should continue as +if no hit occurred. If you return the fraction from the argument list, +the ray will be clipped to the current intersection point. So you can +ray-cast any shape, ray-cast all shapes, or ray-cast the closest shape +by returning the appropriate fraction. + +You may also return a fraction of -1 to filter the shape. Then the +ray-cast will proceed as if the shape does not exist. + +Here is an example: + +```c +struct MyRayCastContext +{ + b3ShapeId shapeId; + b3Vec3 point; + b3Vec3 normal; + float fraction; +}; + +float MyCastCallback(b3ShapeId shapeId, b3Vec3 point, b3Vec3 normal, + float fraction, uint64_t userMaterialId, + int triangleIndex, int childIndex, void* context) +{ + MyRayCastContext* myContext = context; + myContext->shapeId = shapeId; + myContext->point = point; + myContext->normal = normal; + myContext->fraction = fraction; + return fraction; +} + +// Elsewhere ... +MyRayCastContext context = {0}; +b3Vec3 origin = {-1.0f, 0.0f, 0.0f}; +b3Vec3 translation = { 4.0f, 1.0f, 0.0f}; +b3World_CastRay(myWorldId, origin, translation, viewFilter, MyCastCallback, &context); +``` + +There is also a convenience function for the closest hit: + +```c +b3RayResult result = b3World_CastRayClosest(myWorldId, origin, translation, filter); +if (result.hit) +{ + // result.point, result.normal, result.fraction +} +``` + +Ray-cast results may be delivered in an arbitrary order. When you are collecting multiple +hits along the ray, you may want to sort them according to the hit fraction. + +### Shape-casts +Shape-casts are similar to ray-casts. You can view a ray-cast as tracing a point along a line. +A shape-cast allows you to trace a shape along a line. Like the shape overlap query, the shape cast +uses a `b3ShapeProxy` to represent an arbitrary shape. + +```c +struct MyRayCastContext +{ + b3ShapeId shapeId; + b3Vec3 point; + b3Vec3 normal; + float fraction; +}; + +float MyCastCallback(b3ShapeId shapeId, b3Vec3 point, b3Vec3 normal, + float fraction, uint64_t userMaterialId, + int triangleIndex, int childIndex, void* context) +{ + MyRayCastContext* myContext = context; + myContext->shapeId = shapeId; + myContext->point = point; + myContext->normal = normal; + myContext->fraction = fraction; + return fraction; +} + +// Elsewhere ... +MyRayCastContext context = {0}; +b3Sphere sphere = {{-1.0f, 0.0f, 0.0f}, 0.05f}; +b3ShapeProxy proxy; +proxy.points = &sphere.center; +proxy.count = 1; +proxy.radius = sphere.radius; +b3Vec3 translation = {10.0f, -5.0f, 0.0f}; +b3World_CastShape(myWorldId, &proxy, translation, grenadeFilter, MyCastCallback, &context); +``` + +Shape-casts are setup similarly to ray-casts. Shape-casts are generally slower +than ray-casts, so only use a shape-cast if a ray-cast won't do. + +Like ray-casts, shape-cast results may be sent to the callback in any order. If you need multiple sorted results, you will need to write some code to collect and sort the results. + +## Simulation Loop + +![Simulation Loop](images/simulation_loop.svg) + +The Box3D simulation loop can be useful to understand when you process results. + +Multithreading is represented in the diagram. +- rectangles are parallel-for work +- rounded rectangles are single-threaded work, but may be in parallel with other work + +Let's review each of these stages. + +### time step +The game starts the simulation by calling `b3World_Step` supplying the time step. + +### find pairs +Box3D maintains a record of every shape that has moved. For each of these shapes the broad-phase +(BVH) is queried for overlaps. New overlaps are recorded for processing in the next step. Existing +overlaps are tracked in a hash set of all existing shape pairs. This operation is a parallel-for. +Box3D maintains separate BVH trees for static, kinematic, and dynamic bodies. + +### create contacts +This takes the pair results and creates the internal contact pair structure. This +structure is persistent across time steps. It is used for the island graph and holding contact +manifolds. This operation is single-threaded but most of the work is done in `find pairs`. + +### rebuild BVH +After the new shape pairs are known the BVH is not considered until later in the time step. Therefore the BVH +for dynamic and kinematic shapes may be optimized. This involves identifying the part of the collision tree that +is stale from refitting and then performing a rebuild of that sub-tree. This is a single-threaded operation +that is done concurrently with other work. + +### narrow phase +This is where the contact manifolds and points are computed. Each active contact pair is confirmed as touching +or non-touching. If the touching state changes then contact begin and end events are generated. This is a +parallel-for operation. + +Contact points are computed at the beginning of the time step, before bodies have moved and before impulses +are known. This is necessary for obtaining good simulation results efficiently. If contacts were computed at the end +of the time step then new contact points would not be known to the constraint solver and shapes would sink into each +other. + +The `b3PreSolveFcn` is called within the parallel-for so it should be efficient and thread-safe. This is only called for +shapes that have `enablePreSolveEvents == true`. + +### merge islands +Simulation islands are merged when shapes begin touching. Existing islands that have shapes that stop touching +are flagged as candidates for splitting. This stage is single-threaded. + +### split island +A split island task may be generated if: +- there is an island that has shapes that stopped touching +- this island has a body that is moving slow enough to sleep + +Splitting an island may result in several new islands being created. +Only a single island will be split per time step because it is expensive. Delaying the split may delay some +bodies from sleeping. This is a single-threaded operation that is done concurrently with other work. + +### solve constraints +This solves contact and joint constraints and applies restitution. This is a parallel-for with multiple internal stages. + +### update transforms +This stage does several tasks: +- updates body transforms +- updates the body sleeping status +- generates body move events +- generates island splitting candidates +- resets forces and torques +- updates shape bounding boxes +- performs continuous collision between dynamic and static bodies + +This stage is a parallel-for. + +Note that continuous collision does not generate events. Instead they are generated the next time step. However, continuous collision will issue a `b3PreSolveFcn` callback. + +### hit events +Active contacts are scanned for fast approach velocities and added to a buffer. This considers contact points that +have an impulse. This includes touching contacts and speculative contacts that generated an impulse (they are confirmed). +So you may get hit events for contact points that have a positive separation. This is a single-threaded operation. + +### refit BVH +This updates the BVH for shapes that have moved significantly. This is done by enlarging the shapes' bounding box and all ancestor bounding boxes in the BVH. This is a single-threaded operation. + +This can result in an inefficient BVH, which is why the `rebuild BVH` stage exists. Refitting is faster than rebuilding the +BVH but is necessary to ensure the BVH is valid for subsequent queries, such as ray casts. + +### bullets +This is where bullets are processed. Note that this comes after hit events because continuous collision in Box3D does not +generate events until the next time step. + +### island sleep +When an island goes to sleep the simulation data associated with that island is moved to separate storage. This keeps the active simulation data contiguous and cache friendly. + +### sensors +Sensor overlaps are checked in the final stage. The overlap state reflects the final body transform. Sensors do not consider sleep so they may react to the user setting a body transform or creating a sleeping body. This is a parallel-for operation. The cost is roughly proportional to the number of sensors. + +## Determinism +Box3D is designed to be deterministic across thread counts and platforms. This is important for debugging and game design. + +Multithreaded determinism is achieved by basing simulation order on creation order. This includes bodies, shapes, and joint creation order. Determinism includes results reported to users (events). These events must be in deterministic order. + +Cross-platform determinism is achieved on 64-bit platforms by using compiler flags and by avoiding non-deterministic library functions. +- Precise math is used on MSVC. +- Floating point contraction is disabled on Clang and GCC via `-ffp-contract=off`. +- Box3D has custom implementations of atan2, cosine, and sine. + +Determinism is on by default and there is no explicit option to disable it. However, you can break determinism by choosing different compiler flags. Box3D was designed to provide determinism with minimal cost. So there is no advantage to attempting to disable determinism. + +A unit test for determinism is run for every pull request. Determinism is easy to break, so it is important to have regular validation. + +> **Caution**: +> Box3D determinism does not mean your application will be deterministic. Consider using similar strategies to make your +> application deterministic as have been used for Box3D. diff --git a/include/box3d/base.h b/include/box3d/base.h index eb08060..6e1bd80 100644 --- a/include/box3d/base.h +++ b/include/box3d/base.h @@ -96,19 +96,22 @@ B3_API int32_t b3GetByteCount( void ); /// @param assertFcn a non-null assert callback B3_API void b3SetAssertFcn( b3AssertFcn* assertFcn ); -// see https://github.com/scottt/debugbreak +/// see https://github.com/scottt/debugbreak #if defined( _MSC_VER ) +/// Break to the debugger #define B3_BREAKPOINT __debugbreak() #elif defined( __GNUC__ ) || defined( __clang__ ) #define B3_BREAKPOINT __builtin_trap() #else -// Unknown compiler +/// Unknown compiler #include #define B3_BREAKPOINT assert( 0 ) #endif #if !defined( NDEBUG ) || defined( B3_ENABLE_ASSERT ) +/// Internal assertion handler. Allows for host intervention. B3_API int b3InternalAssert( const char* condition, const char* fileName, int lineNumber ); +/// Assert that a condition is true. #define B3_ASSERT( condition ) \ ( (void)( ( !!( condition ) ) || ( b3InternalAssert( #condition, __FILE__, (int)( __LINE__ ) ), 0 ) ) ) #else @@ -116,9 +119,12 @@ B3_API int b3InternalAssert( const char* condition, const char* fileName, int li #endif #if B3_ENABLE_VALIDATION -// Floating point tolerance checks should use this instead of the regular assertion +/// Validation is typically only enabled in debug builds. +/// Floating point tolerance checks should use this instead of the regular assertion #define B3_VALIDATE( condition ) B3_ASSERT( condition ) #else +/// Validation is typically only enabled in debug builds. +/// Floating point tolerance checks should use this instead of the regular assertion #define B3_VALIDATE( ... ) ( (void)0 ) #endif @@ -139,7 +145,7 @@ typedef struct b3Version int revision; } b3Version; -/// Get the current version of Box2D +/// Get the current version of Box3D B3_API b3Version b3GetVersion( void ); /**@}*/ diff --git a/include/box3d/box3d.h b/include/box3d/box3d.h index c2a954a..849cb30 100644 --- a/include/box3d/box3d.h +++ b/include/box3d/box3d.h @@ -16,13 +16,13 @@ * These functions allow you to create a simulation world. * * You can add rigid bodies and joint constraints to the world and run the simulation. You can get contact - * information to get contact points and normals as well as events. You can query to world, checking for overlaps and casting rays + * information to get contact points and normals as well as events. You can query the world, checking for overlaps and casting rays * or shapes. There is also debugging information such as debug draw, timing information, and counters. You can find documentation * here: https://box2d.org/ * @{ */ -/// Create a world for rigid body simulation. A world contains bodies, shapes, and constraints. You make create +/// Create a world for rigid body simulation. A world contains bodies, shapes, and constraints. You may create /// up to 128 worlds. Each world is completely independent and may be simulated in parallel. /// @return the world id. B3_API b3WorldId b3CreateWorld( const b3WorldDef* def ); @@ -48,7 +48,7 @@ B3_API void b3World_Step( b3WorldId worldId, float timeStep, int subStepCount ); /// Call this to draw shapes and other debug draw data B3_API void b3World_Draw( b3WorldId worldId, b3DebugDraw* draw, uint64_t maskBits ); -/// Get the worlds bounds. This is the bounding box that covers the current simulation. May have a small +/// Get the world's bounds. This is the bounding box that covers the current simulation. May have a small /// amount of padding. B3_API b3AABB b3World_GetBounds( b3WorldId worldId ); @@ -134,7 +134,7 @@ B3_API bool b3World_IsContinuousEnabled( b3WorldId worldId ); /// @see b3WorldDef B3_API void b3World_SetRestitutionThreshold( b3WorldId worldId, float value ); -/// Get the the restitution speed threshold. Usually in meters per second. +/// Get the restitution speed threshold. Usually in meters per second. B3_API float b3World_GetRestitutionThreshold( b3WorldId worldId ); /// Adjust the hit event threshold. This controls the collision speed needed to generate a b3ContactHitEvent. @@ -142,7 +142,7 @@ B3_API float b3World_GetRestitutionThreshold( b3WorldId worldId ); /// @see b3WorldDef::hitEventThreshold B3_API void b3World_SetHitEventThreshold( b3WorldId worldId, float value ); -/// Get the the hit event speed threshold. Usually in meters per second. +/// Get the hit event speed threshold. Usually in meters per second. B3_API float b3World_GetHitEventThreshold( b3WorldId worldId ); /// Register the custom filter callback. This is optional. @@ -151,7 +151,7 @@ B3_API void b3World_SetCustomFilterCallback( b3WorldId worldId, b3CustomFilterFc /// Register the pre-solve callback. This is optional. B3_API void b3World_SetPreSolveCallback( b3WorldId worldId, b3PreSolveFcn* fcn, void* context ); -/// Set the gravity vector for the entire world. Box2D has no concept of an up direction and this +/// Set the gravity vector for the entire world. Box3D has no concept of an up direction and this /// is left as a decision for the application. Usually in m/s^2. /// @see b3WorldDef B3_API void b3World_SetGravity( b3WorldId worldId, b3Vec3 gravity ); @@ -186,7 +186,7 @@ B3_API void b3World_SetMaximumLinearSpeed( b3WorldId worldId, float maximumLinea B3_API float b3World_GetMaximumLinearSpeed( b3WorldId worldId ); /// Enable/disable constraint warm starting. Advanced feature for testing. Disabling -/// sleeping greatly reduces stability and provides no performance gain. +/// warm starting greatly reduces stability and provides no performance gain. B3_API void b3World_EnableWarmStarting( b3WorldId worldId, bool flag ); /// Is constraint warm starting enabled? @@ -216,7 +216,7 @@ B3_API void b3World_SetFrictionCallback( b3WorldId worldId, b3FrictionCallback* /// Set the restitution callback. Passing NULL resets to default. B3_API void b3World_SetRestitutionCallback( b3WorldId worldId, b3RestitutionCallback* callback ); -/// Set the worker count. Must be between in the range [1, B3_MAX_WORKERS] +/// Set the worker count. Must be in the range [1, B3_MAX_WORKERS] B3_API void b3World_SetWorkerCount( b3WorldId worldId, int count ); /// Get the worker count. @@ -241,7 +241,7 @@ B3_API void b3World_DumpAwake( b3WorldId worldId ); /// Dump world to a text file. Meshes are saved to binary b3m files. B3_API void b3World_Dump( b3WorldId worldId ); -/** @} */ +/** @} */ // world /** * @defgroup body Body @@ -273,7 +273,7 @@ B3_API b3BodyType b3Body_GetType( b3BodyId bodyId ); /// properties regardless of the automatic mass setting. B3_API void b3Body_SetType( b3BodyId bodyId, b3BodyType type ); -/// Set the body name. Up to 31 characters excluding 0 termination. +/// Set the body name. Up to B3_NAME_LENGTH characters including null termination. B3_API void b3Body_SetName( b3BodyId bodyId, const char* name ); /// Get the body name. @@ -288,14 +288,14 @@ B3_API void* b3Body_GetUserData( b3BodyId bodyId ); /// Get the world position of a body. This is the location of the body origin. B3_API b3Vec3 b3Body_GetPosition( b3BodyId bodyId ); -/// Get the world rotation of a body as a cosine/sine pair (complex number) +/// Get the world rotation of a body as a quaternion B3_API b3Quat b3Body_GetRotation( b3BodyId bodyId ); /// Get the world transform of a body. B3_API b3Transform b3Body_GetTransform( b3BodyId bodyId ); /// Set the world transform of a body. This acts as a teleport and is fairly expensive. -/// @note Generally you should create a body with then intended transform. +/// @note Generally you should create a body with the intended transform. /// @see b3BodyDef::position and b3BodyDef::rotation B3_API void b3Body_SetTransform( b3BodyId bodyId, b3Vec3 position, b3Quat rotation ); @@ -414,7 +414,7 @@ B3_API void b3Body_SetMassData( b3BodyId bodyId, b3MassData massData ); /// Get the mass data for a body B3_API b3MassData b3Body_GetMassData( b3BodyId bodyId ); -/// This update the mass properties to the sum of the mass properties of the shapes. +/// This updates the mass properties to the sum of the mass properties of the shapes. /// This normally does not need to be called unless you called SetMassData to override /// the mass and you later want to reset the mass. /// You may also use this when automatic mass computation has been disabled. @@ -539,7 +539,7 @@ B3_API bool b3Body_OverlapShape( b3BodyId bodyId, const b3ShapeProxy* proxy, b3Q B3_API int b3Body_CollideMover( b3BodyId bodyId, b3BodyPlaneResult* bodyPlanes, int planeCapacity, const b3Capsule* mover, b3QueryFilter filter, b3Transform bodyTransform ); -/** @} */ +/** @} */ // body /** * @defgroup shape Shape @@ -603,10 +603,10 @@ B3_API b3BodyId b3Shape_GetBody( b3ShapeId shapeId ); /// Get the world that owns this shape B3_API b3WorldId b3Shape_GetWorld( b3ShapeId shapeId ); -/// Returns true If the shape is a sensor +/// Returns true if the shape is a sensor B3_API bool b3Shape_IsSensor( b3ShapeId shapeId ); -/// Set the shape name. Up to 31 characters excluding 0 termination. +/// Set the shape name. Up to B3_NAME_LENGTH characters including null termination. B3_API void b3Shape_SetName( b3ShapeId shapeId, const char* name ); /// Get the shape name. @@ -619,12 +619,12 @@ B3_API void b3Shape_SetUserData( b3ShapeId shapeId, void* userData ); /// from an event or query. B3_API void* b3Shape_GetUserData( b3ShapeId shapeId ); -/// Set the mass density of a shape, usually in kg/m^2. +/// Set the mass density of a shape, usually in kg/m^3. /// This will optionally update the mass properties on the parent body. /// @see b3ShapeDef::density, b3Body_ApplyMassFromShapes B3_API void b3Shape_SetDensity( b3ShapeId shapeId, float density, bool updateBodyMass ); -/// Get the density of a shape, usually in kg/m^2 +/// Get the density of a shape, usually in kg/m^3 B3_API float b3Shape_GetDensity( b3ShapeId shapeId ); /// Set the friction on a shape @@ -775,7 +775,7 @@ B3_API b3Vec3 b3Shape_GetClosestPoint( b3ShapeId shapeId, b3Vec3 target ); /// @param wake should this wake the body B3_API void b3Shape_ApplyWind( b3ShapeId shapeId, b3Vec3 wind, float drag, float lift, float maxSpeed, bool wake ); -/** @} */ +/** @} */ // shape /** * @defgroup joint Joint @@ -837,7 +837,7 @@ B3_API b3Vec3 b3Joint_GetConstraintTorque( b3JointId jointId ); /// Get the current linear separation error for this joint. Does not consider admissible movement. Usually in meters. B3_API float b3Joint_GetLinearSeparation( b3JointId jointId ); -/// Get the current angular separation error for this joint. Does not consider admissible movement. Usually in meters. +/// Get the current angular separation error for this joint. Does not consider admissible movement. Usually in radians. B3_API float b3Joint_GetAngularSeparation( b3JointId jointId ); /// Set the joint constraint tuning. Advanced feature. @@ -862,7 +862,7 @@ B3_API void b3Joint_SetTorqueThreshold( b3JointId jointId, float threshold ); B3_API float b3Joint_GetTorqueThreshold( b3JointId jointId ); /** - * @defgroup cone_joint Parallel Joint + * @defgroup parallel_joint Parallel Joint * @brief Functions for the parallel joint. * @{ */ @@ -883,12 +883,13 @@ B3_API float b3ParallelJoint_GetSpringHertz( b3JointId jointId ); /// Get the spring damping ratio B3_API float b3ParallelJoint_GetSpringDampingRatio( b3JointId jointId ); -/// Set the maximum spring torque, usually in newtons-meters +/// Set the maximum spring torque, usually in newton-meters B3_API void b3ParallelJoint_SetMaxTorque( b3JointId jointId, float force ); -/// Get the maximum spring torque, usually in newtons-meters +/// Get the maximum spring torque, usually in newton-meters B3_API float b3ParallelJoint_GetMaxTorque( b3JointId jointId ); -/** @} */ + +/** @} */ // parallel_joint /** * @defgroup distance_joint Distance Joint @@ -971,7 +972,8 @@ B3_API float b3DistanceJoint_GetMaxMotorForce( b3JointId jointId ); /// Get the distance joint current motor force, usually in newtons B3_API float b3DistanceJoint_GetMotorForce( b3JointId jointId ); -/** @} */ + +/** @} */ // distance_joint /** * @defgroup motor_joint Motor Joint @@ -1049,14 +1051,13 @@ B3_API void b3MotorJoint_SetMaxSpringTorque( b3JointId jointId, float maxTorque /// Get the maximum spring torque in newtons * meters B3_API float b3MotorJoint_GetMaxSpringTorque( b3JointId jointId ); -/**@}*/ +/**@}*/ // motor_joint -/**@}*/ /** - * @defgroup null_joint Null Joint - * @brief Functions for the null joint. + * @defgroup filter_joint Filter Joint + * @brief Functions for the filter joint. * - * The null joint is used to disable collision between two bodies. As a side effect of being a joint, it also + * The filter joint is used to disable collision between two bodies. As a side effect of being a joint, it also * keeps the two bodies in the same simulation island. * @{ */ @@ -1065,7 +1066,7 @@ B3_API float b3MotorJoint_GetMaxSpringTorque( b3JointId jointId ); /// @see b3FilterJointDef for details B3_API b3JointId b3CreateFilterJoint( b3WorldId worldId, const b3FilterJointDef* def ); -/**@}*/ +/**@}*/ // filter_joint /** * @defgroup prismatic_joint Prismatic Joint @@ -1148,11 +1149,11 @@ B3_API float b3PrismaticJoint_GetTranslation( b3JointId jointId ); /// Get the current joint translation speed, usually in meters per second. B3_API float b3PrismaticJoint_GetSpeed( b3JointId jointId ); -/** @} */ +/**@}*/ // prismatic_joint /** * @defgroup revolute_joint Revolute Joint - * @brief A revolute joint allows for relative rotation in the 2D plane with no relative translation. + * @brief A revolute joint allows for relative rotation about a single axis with no relative translation. * * The revolute joint is probably the most common joint. It can be used for ragdolls and chains. * Also called a *hinge* or *pin* joint. @@ -1166,7 +1167,7 @@ B3_API b3JointId b3CreateRevoluteJoint( b3WorldId worldId, const b3RevoluteJoint /// Enable/disable the revolute joint spring B3_API void b3RevoluteJoint_EnableSpring( b3JointId jointId, bool enableSpring ); -/// It the revolute angular spring enabled? +/// Is the revolute angular spring enabled? B3_API bool b3RevoluteJoint_IsSpringEnabled( b3JointId jointId ); /// Set the revolute joint spring stiffness in Hertz @@ -1227,7 +1228,7 @@ B3_API void b3RevoluteJoint_SetMaxMotorTorque( b3JointId jointId, float torque ) /// Get the revolute joint maximum motor torque, usually in newton-meters B3_API float b3RevoluteJoint_GetMaxMotorTorque( b3JointId jointId ); -/**@}*/ +/**@}*/ // revolute_joint /** * @defgroup spherical_joint Spherical Joint @@ -1237,8 +1238,8 @@ B3_API float b3RevoluteJoint_GetMaxMotorTorque( b3JointId jointId ); * @{ */ -/// Create a revolute joint -/// @see b3RevoluteJointDef for details +/// Create a spherical joint +/// @see b3SphericalJointDef for details B3_API b3JointId b3CreateSphericalJoint( b3WorldId worldId, const b3SphericalJointDef* def ); /// Enable/disable the spherical joint cone limit @@ -1277,7 +1278,7 @@ B3_API float b3SphericalJoint_GetTwistAngle( b3JointId jointId ); /// Enable/disable the spherical joint spring B3_API void b3SphericalJoint_EnableSpring( b3JointId jointId, bool enableSpring ); -/// It the spherical angular spring enabled? +/// Is the spherical angular spring enabled? B3_API bool b3SphericalJoint_IsSpringEnabled( b3JointId jointId ); /// Set the spherical joint spring stiffness in Hertz @@ -1319,7 +1320,7 @@ B3_API void b3SphericalJoint_SetMaxMotorTorque( b3JointId jointId, float torque /// Get the spherical joint maximum motor torque, usually in newton-meters B3_API float b3SphericalJoint_GetMaxMotorTorque( b3JointId jointId ); -/**@}*/ +/**@}*/ // spherical_joint /** * @defgroup weld_joint Weld Joint @@ -1360,7 +1361,7 @@ B3_API void b3WeldJoint_SetAngularDampingRatio( b3JointId jointId, float damping /// Get the weld joint angular damping ratio, non-dimensional B3_API float b3WeldJoint_GetAngularDampingRatio( b3JointId jointId ); -/** @} */ +/**@}*/ // weld_joint /** * @defgroup wheel_joint Wheel Joint @@ -1372,62 +1373,65 @@ B3_API float b3WeldJoint_GetAngularDampingRatio( b3JointId jointId ); * @{ */ -/// Create a wheel joint -/// @see b3WheelJointDef for details +/// Create a wheel joint. +/// @see b3WheelJointDef for details. B3_API b3JointId b3CreateWheelJoint( b3WorldId worldId, const b3WheelJointDef* def ); -/// Enable/disable the wheel joint spring +/// Enable/disable the wheel joint spring. B3_API void b3WheelJoint_EnableSuspension( b3JointId jointId, bool flag ); /// Is the wheel joint spring enabled? B3_API bool b3WheelJoint_IsSuspensionEnabled( b3JointId jointId ); -/// Set the wheel joint stiffness in Hertz +/// Set the wheel joint stiffness in Hertz. B3_API void b3WheelJoint_SetSuspensionHertz( b3JointId jointId, float hertz ); -/// Get the wheel joint stiffness in Hertz +/// Get the wheel joint stiffness in Hertz. B3_API float b3WheelJoint_GetSuspensionHertz( b3JointId jointId ); -/// Set the wheel joint damping ratio, non-dimensional +/// Set the wheel joint damping ratio, non-dimensional. B3_API void b3WheelJoint_SetSuspensionDampingRatio( b3JointId jointId, float dampingRatio ); -/// Get the wheel joint damping ratio, non-dimensional +/// Get the wheel joint damping ratio, non-dimensional. B3_API float b3WheelJoint_GetSuspensionDampingRatio( b3JointId jointId ); -/// Enable/disable the wheel joint limit +/// Enable/disable the wheel joint limit. B3_API void b3WheelJoint_EnableSuspensionLimit( b3JointId jointId, bool flag ); /// Is the wheel joint limit enabled? B3_API bool b3WheelJoint_IsSuspensionLimitEnabled( b3JointId jointId ); -/// Get the wheel joint lower limit +/// Get the wheel joint lower limit. B3_API float b3WheelJoint_GetLowerSuspensionLimit( b3JointId jointId ); -/// Get the wheel joint upper limit +/// Get the wheel joint upper limit. B3_API float b3WheelJoint_GetUpperSuspensionLimit( b3JointId jointId ); -/// Set the wheel joint limits +/// Set the wheel joint limits. B3_API void b3WheelJoint_SetSuspensionLimits( b3JointId jointId, float lower, float upper ); -/// Enable/disable the wheel joint motor +/// Enable/disable the wheel joint motor. B3_API void b3WheelJoint_EnableSpinMotor( b3JointId jointId, bool flag ); /// Is the wheel joint motor enabled? B3_API bool b3WheelJoint_IsSpinMotorEnabled( b3JointId jointId ); -/// Set the wheel joint motor speed in radians per second +/// Set the wheel joint motor speed in radians per second. B3_API void b3WheelJoint_SetSpinMotorSpeed( b3JointId jointId, float speed ); -/// Get the wheel joint motor speed in radians per second +/// Get the wheel joint motor speed in radians per second. B3_API float b3WheelJoint_GetSpinMotorSpeed( b3JointId jointId ); -/// Set the wheel joint maximum motor torque, usually in newton-meters +/// Set the wheel joint maximum motor torque, usually in newton-meters. B3_API void b3WheelJoint_SetMaxSpinTorque( b3JointId jointId, float torque ); -/// Get the wheel joint maximum motor torque, usually in newton-meters +/// Get the wheel joint maximum motor torque, usually in newton-meters. B3_API float b3WheelJoint_GetMaxSpinTorque( b3JointId jointId ); -/// Get the wheel joint current motor torque, usually in newton-meters +/// Get the current spin speed in radians per second. +B3_API float b3WheelJoint_GetSpinSpeed( b3JointId jointId ); + +/// Get the wheel joint current motor torque, usually in newton-meters. B3_API float b3WheelJoint_GetSpinTorque( b3JointId jointId ); /// Enable/disable wheel steering. Steering allows the wheel to rotate about the suspension axis. @@ -1436,16 +1440,16 @@ B3_API void b3WheelJoint_EnableSteering( b3JointId jointId, bool flag ); /// Can the wheel steer? B3_API bool b3WheelJoint_IsSteeringEnabled( b3JointId jointId ); -/// Set the wheel joint steering stiffness in Hertz +/// Set the wheel joint steering stiffness in Hertz. B3_API void b3WheelJoint_SetSteeringHertz( b3JointId jointId, float hertz ); -/// Get the wheel joint steering stiffness in Hertz +/// Get the wheel joint steering stiffness in Hertz. B3_API float b3WheelJoint_GetSteeringHertz( b3JointId jointId ); -/// Set the wheel joint steering damping ratio, non-dimensional +/// Set the wheel joint steering damping ratio, non-dimensional. B3_API void b3WheelJoint_SetSteeringDampingRatio( b3JointId jointId, float dampingRatio ); -/// Get the wheel joint steering damping ratio, non-dimensional +/// Get the wheel joint steering damping ratio, non-dimensional. B3_API float b3WheelJoint_GetSteeringDampingRatio( b3JointId jointId ); /// Set the wheel joint maximum steering torque in N*m. @@ -1454,42 +1458,36 @@ B3_API void b3WheelJoint_SetMaxSteeringTorque( b3JointId jointId, float torque ) /// Get the wheel joint maximum steering torque in N*m. B3_API float b3WheelJoint_GetMaxSteeringTorque( b3JointId jointId ); -/// Enable/disable the wheel joint steering limit +/// Enable/disable the wheel joint steering limit. B3_API void b3WheelJoint_EnableSteeringLimit( b3JointId jointId, bool flag ); /// Is the wheel joint steering limit enabled? B3_API bool b3WheelJoint_IsSteeringLimitEnabled( b3JointId jointId ); -/// Get the wheel joint lower steering limit in radians +/// Get the wheel joint lower steering limit in radians. B3_API float b3WheelJoint_GetLowerSteeringLimit( b3JointId jointId ); -/// Get the wheel joint upper steering limit in radians +/// Get the wheel joint upper steering limit in radians. B3_API float b3WheelJoint_GetUpperSteeringLimit( b3JointId jointId ); -/// Set the wheel joint steering limits in radians +/// Set the wheel joint steering limits in radians. B3_API void b3WheelJoint_SetSteeringLimits( b3JointId jointId, float lowerRadians, float upperRadians ); -/// Set the wheel joint target steering angle in radians +/// Set the wheel joint target steering angle in radians. B3_API void b3WheelJoint_SetTargetSteeringAngle( b3JointId jointId, float radians ); -/// Get the wheel joint target steering angle in radians +/// Get the wheel joint target steering angle in radians. B3_API float b3WheelJoint_GetTargetSteeringAngle( b3JointId jointId ); -/// Get the current spin speed in radians per second -B3_API float b3WheelJoint_GetSpinSpeed( b3JointId jointId ); - -/// Get the current spin torque in N*m -B3_API float b3WheelJoint_GetSpinTorque( b3JointId jointId ); - -/// Get the current steering angle in radians +/// Get the current steering angle in radians. B3_API float b3WheelJoint_GetSteeringAngle( b3JointId jointId ); -/// Get the current steering torque in N*m +/// Get the current steering torque in N*m. B3_API float b3WheelJoint_GetSteeringTorque( b3JointId jointId ); -/**@}*/ +/**@}*/ // wheel_joint -/**@}*/ +/**@}*/ // joint /** * @defgroup contact Contact @@ -1503,4 +1501,4 @@ B3_API bool b3Contact_IsValid( b3ContactId id ); /// Get the manifolds for a contact. The manifold may have no points if the contact is not touching. B3_API b3ContactData b3Contact_GetData( b3ContactId contactId ); -/**@}*/ +/**@}*/ // contact diff --git a/include/box3d/collision.h b/include/box3d/collision.h index 8c677f2..8c8d6a0 100644 --- a/include/box3d/collision.h +++ b/include/box3d/collision.h @@ -5,241 +5,16 @@ #include "base.h" #include "math_functions.h" +#include "types.h" #include #include -/// Material properties supported per triangle on meshes and height fields -/// @ingroup shape -typedef struct b3SurfaceMaterial -{ - /// The Coulomb (dry) friction coefficient, usually in the range [0,1]. - float friction; - - /// The coefficient of restitution (bounce) usually in the range [0,1]. - /// https://en.wikipedia.org/wiki/Coefficient_of_restitution - float restitution; - - /// The rolling resistance usually in the range [0,1]. This is only used for spheres and capsules. - float rollingResistance; - - /// The tangent velocity for conveyor belts. This is local to the shape and will be projected - /// onto the contact surface. - b3Vec3 tangentVelocity; - - /// User material identifier. This is passed with query results and to friction and restitution - /// combining functions. It is not used internally. - uint64_t userMaterialId; - - /// Custom debug draw color. Ignored if 0. The low 24 bits are RGB. The high byte may - /// carry a b3DebugMaterial preset, see b3MakeDebugColor. - /// @see b3HexColor - uint32_t customColor; -} b3SurfaceMaterial; - -/// Use this to initialize your surface material -/// @ingroup shape -B3_API b3SurfaceMaterial b3DefaultSurfaceMaterial( void ); - /** - * @defgroup geometry Geometry - * @brief Geometry types and algorithms - * - * Definitions of spheres, capsules, hulls, meshes, and height fields. - * Functions should take the shape as the first argument to assist editor auto-complete. + * @addtogroup tree * @{ */ -#define B3_MAX_SHAPE_CAST_POINTS 64 - -/// Low level ray cast input data -typedef struct b3RayCastInput -{ - /// Start point of the ray cast - b3Vec3 origin; - - /// Translation of the ray cast - b3Vec3 translation; - - /// The maximum fraction of the translation to consider, typically 1 - float maxFraction; -} b3RayCastInput; - -/// A shape proxy is used by the GJK algorithm. It can represent a convex shape. -typedef struct b3ShapeProxy -{ - /// The point cloud - const b3Vec3* points; - - /// The number of points. Do not exceed B3_MAX_SHAPE_CAST_POINTS. - int count; - - /// The external radius of the point cloud - float radius; -} b3ShapeProxy; - -/// Low level shape cast input in generic form. This allows casting an arbitrary point -/// cloud wrap with a radius. For example, a sphere is a single point with a non-zero radius. -/// A capsule is two points with a non-zero radius. A box is four points with a zero radius. -typedef struct b3ShapeCastInput -{ - /// A generic query shape - b3ShapeProxy proxy; - - /// The translation of the shape cast - b3Vec3 translation; - - /// The maximum fraction of the translation to consider, typically 1 - float maxFraction; - - /// Allow shape cast to encroach when initially touching. This only works if the radius is greater than zero. - bool canEncroach; -} b3ShapeCastInput; - -/// Low level ray cast or shape-cast output data -typedef struct b3CastOutput -{ - /// The surface normal at the hit point - b3Vec3 normal; - - /// The surface hit point - b3Vec3 point; - - /// The fraction of the input translation at collision - float fraction; - - /// The number of iterations used - int iterations; - - /// The index of the mesh or height field triangle hit - int triangleIndex; - - /// The index of the compound child shape - int childIndex; - - /// The material index. May be -1 for null. - int materialIndex; - - /// Did the cast hit? - bool hit; -} b3CastOutput; - -/** - * @defgroup tree Dynamic Tree - * The dynamic tree is a binary AABB tree to organize and query large numbers of geometric objects - * - * Box2D uses the dynamic tree internally to sort collision shapes into a binary bounding volume hierarchy. - * This data structure may have uses in games for organizing other geometry data and may be used independently - * of Box2D rigid body simulation. - * - * A dynamic AABB tree broad-phase, inspired by Nathanael Presson's btDbvt. - * A dynamic tree arranges data in a binary tree to accelerate - * queries such as AABB queries and ray casts. Leaf nodes are proxies - * with an AABB. These are used to hold a user collision object. - * Nodes are pooled and relocatable, so I use node indices rather than pointers. - * The dynamic tree is made available for advanced users that would like to use it to organize - * spatial game data besides rigid bodies. - * @{ - */ - -typedef enum b3TreeNodeFlags -{ - b3_allocatedNode = 0x0001, - b3_enlargedNode = 0x0002, - b3_leafNode = 0x0004, -} b3TreeNodeFlags; - -typedef struct b3TreeNodeChildren -{ - int child1; - int child2; -} b3TreeNodeChildren; - -/// A node in the dynamic tree. This is private data placed here for performance reasons. -/// todo test padding to 64 bytes to avoid straddling cache lines -typedef struct b3TreeNode -{ - /// The node bounding box - b3AABB aabb; // 24 - - /// Category bits for collision filtering - uint64_t categoryBits; // 8 - - union - { - /// Children (internal node) - b3TreeNodeChildren children; - - /// User data (leaf node) - uint64_t userData; - }; // 8 - - union - { - /// The node parent index (allocated node) - int parent; - - /// The node freelist next index (free node) - int next; - }; // 4 - - /// Height of the node. Leaves have a height of 0. - uint16_t height; // 2 - uint16_t flags; // 2 -} b3TreeNode; - -#define B3_DYNAMIC_TREE_VERSION 0x8E867C390754064Bull - -/// The dynamic tree structure. This should be considered private data. -/// It is placed here for performance reasons. -typedef struct b3DynamicTree -{ - uint64_t version; - - /// The tree nodes - b3TreeNode* nodes; - - /// The root index - int root; - - /// The number of nodes - int nodeCount; - - /// The allocated node space - int nodeCapacity; - - /// Number of proxies created - int proxyCount; - - /// Node free list - int freeList; - - /// Leaf indices for rebuild - int* leafIndices; - - /// Leaf bounding boxes for rebuild - b3AABB* leafBoxes; - - /// Leaf bounding box centers for rebuild - b3Vec3* leafCenters; - - /// Bins for sorting during rebuild - int* binIndices; - - /// Allocated space for rebuilding - int rebuildCapacity; -} b3DynamicTree; - -/// These are performance results returned by dynamic tree queries. -typedef struct b3TreeStats -{ - /// Number of internal nodes visited during the query - int nodeVisits; - - /// Number of leaf nodes visited during the query - int leafVisits; -} b3TreeStats; - /// Constructing the tree initializes the node pool. B3_API b3DynamicTree b3DynamicTree_Create( int proxyCapacity ); @@ -264,26 +39,18 @@ B3_API void b3DynamicTree_SetCategoryBits( b3DynamicTree* tree, int proxyId, uin /// Get the category bits on a proxy. B3_API uint64_t b3DynamicTree_GetCategoryBits( b3DynamicTree* tree, int proxyId ); -/// This function receives proxies found in the AABB query. -/// @return true if the query should continue -typedef bool b3TreeQueryCallbackFcn( int proxyId, uint64_t userData, void* context ); - -/// Query an AABB for overlapping proxies. The callback class is called for each proxy that overlaps the supplied AABB. +/// Query an AABB for overlapping proxies. The callback function is called for each proxy that overlaps the supplied AABB. /// @return performance data B3_API b3TreeStats b3DynamicTree_Query( const b3DynamicTree* tree, b3AABB aabb, uint64_t maskBits, bool requireAllBits, b3TreeQueryCallbackFcn* callback, void* context ); -/// This function receives the minimum distance squared so far and proxy to check in the closest query. -/// @return minimum distance squared to user objects in the proxy -typedef float b3TreeQueryClosestCallbackFcn( float distanceSqrMin, int proxyId, uint64_t userData, void* context ); - -/// Query an AABB for the closest object. The callback class is called for each proxy that might be closest to the supplied point. +/// Query an AABB for the closest object. The callback function is called for each proxy that might be closest to the supplied point. /// @param tree the dynamic tree to query /// @param point the query point /// @param maskBits nodes are skipped if the bit-wise AND with the node category bits is zero /// @param requireAllBits nodes are skipped if the bit-wise AND with the node category bits does not equal the maskBits /// @param callback a user provided instance of b3TreeQueryClosestCallbackFcn -/// @param context a user context object that is provide to the callback +/// @param context a user context object that is provided to the callback /// @param minDistanceSqr the initial and final minimum squared distance. Provide a small initial to restrict the search and /// improve performance. If the value is large this query has performance that scales linearly with the number of proxies and /// would be slower than a brute force search. @@ -291,16 +58,9 @@ typedef float b3TreeQueryClosestCallbackFcn( float distanceSqrMin, int proxyId, B3_API b3TreeStats b3DynamicTree_QueryClosest( const b3DynamicTree* tree, b3Vec3 point, uint64_t maskBits, bool requireAllBits, b3TreeQueryClosestCallbackFcn* callback, void* context, float* minDistanceSqr ); -/// This function receives clipped ray cast input for a proxy. The function -/// returns the new ray fraction. -/// - return a value of 0 to terminate the ray cast -/// - return a value less than input->maxFraction to clip the ray -/// - return a value of input->maxFraction to continue the ray cast without clipping -typedef float b3TreeRayCastCallbackFcn( const b3RayCastInput* input, int proxyId, uint64_t userData, void* context ); - /// Ray cast against the proxies in the tree. This relies on the callback -/// to perform a exact ray cast in the case were the proxy contains a shape. -/// The callback also performs the any collision filtering. This has performance +/// to perform an exact ray cast in the case where the proxy contains a shape. +/// The callback also performs any collision filtering. This has performance /// roughly equal to k * log(n), where k is the number of collisions and n is the /// number of proxies in the tree. /// Bit-wise filtering using mask bits can greatly improve performance in some scenarios. @@ -309,29 +69,22 @@ typedef float b3TreeRayCastCallbackFcn( const b3RayCastInput* input, int proxyId /// @param input the ray cast input data. The ray extends from p1 to p1 + maxFraction * (p2 - p1) /// @param maskBits bit mask test: `bool accept = (maskBits & node->categoryBits) != 0;` /// @param requireAllBits modifies bit mask test: `bool accept = (maskBits & node->categoryBits) == maskBits;` -/// @param callback a callback class that is called for each proxy that is hit by the ray +/// @param callback a callback function that is called for each proxy that is hit by the ray /// @param context user context that is passed to the callback /// @return performance data B3_API b3TreeStats b3DynamicTree_RayCast( const b3DynamicTree* tree, const b3RayCastInput* input, uint64_t maskBits, bool requireAllBits, b3TreeRayCastCallbackFcn* callback, void* context ); -/// This function receives clipped ray cast input for a proxy. The function -/// returns the new ray fraction. -/// - return a value of 0 to terminate the ray cast -/// - return a value less than input->maxFraction to clip the ray -/// - return a value of input->maxFraction to continue the ray cast without clipping -typedef float b3TreeShapeCastCallbackFcn( const b3ShapeCastInput* input, int proxyId, uint64_t userData, void* context ); - /// Ray cast against the proxies in the tree. This relies on the callback -/// to perform a exact ray cast in the case were the proxy contains a shape. -/// The callback also performs the any collision filtering. This has performance +/// to perform an exact ray cast in the case where the proxy contains a shape. +/// The callback also performs any collision filtering. This has performance /// roughly equal to k * log(n), where k is the number of collisions and n is the /// number of proxies in the tree. /// @param tree the dynamic tree to ray cast /// @param input the ray cast input data. The ray extends from p1 to p1 + maxFraction * (p2 - p1). /// @param maskBits bit mask test: `bool accept = (maskBits & node->categoryBits) != 0;` /// @param requireAllBits modifies bit mask test: `bool accept = (maskBits & node->categoryBits) == maskBits;` -/// @param callback a callback class that is called for each proxy that is hit by the shape +/// @param callback a callback function that is called for each proxy that is hit by the shape /// @param context user context that is passed to the callback /// @return performance data B3_API b3TreeStats b3DynamicTree_ShapeCast( const b3DynamicTree* tree, const b3ShapeCastInput* input, uint64_t maskBits, @@ -382,108 +135,14 @@ B3_INLINE b3AABB b3DynamicTree_GetAABB( const b3DynamicTree* tree, int proxyId ) return tree->nodes[proxyId].aabb; } -/**@}*/ +/**@}*/ // tree -/// This holds the mass data computed for a shape. -typedef struct b3MassData -{ - float mass; - b3Vec3 center; - - // todo_erin this should be central inertia - b3Matrix3 inertia; -} b3MassData; - -/// A solid sphere -typedef struct b3Sphere -{ - /// The local center - b3Vec3 center; - - /// The radius - float radius; -} b3Sphere; - -/// A solid capsule can be viewed as two hemispheres connected -/// by a rectangle. -typedef struct b3Capsule -{ - /// Local center of the first hemisphere - b3Vec3 center1; - - /// Local center of the second hemisphere - b3Vec3 center2; - - /// The radius of the hemispheres - float radius; -} b3Capsule; - -typedef struct b3HullVertex -{ - // A half-edge that has this vertex as the origin - // Can be used along with edge twins and winding order - // to traverse all the edges connected to this vertex. - uint8_t edge; -} b3HullVertex; - -/// Half-edge for hull data structure -typedef struct b3HullHalfEdge -{ - // Next edge index CCW - uint8_t next; - - // Twin edge index - uint8_t twin; - - // index of origin vertex and point - uint8_t origin; - - // Face to the left of this edge - uint8_t face; -} b3HullHalfEdge; - -typedef struct b3HullFace -{ - // An arbitrary half-edge on this face - uint8_t edge; -} b3HullFace; - -#define B3_HULL_VERSION 0x8F5034CF987D4FD9ull - -/// A convex hull. -/// @note This data structure has data hanging off the end and cannot be directly copied. -typedef struct b3Hull -{ - // Version must be first and match B3_HULL_VERSION - uint64_t version; - int byteCount; - - // Hash of this hull (this field is zero when the hash is computed) - uint32_t hash; - - // Bulk properties - b3AABB aabb; - float surfaceArea; - float volume; - float innerRadius; - b3Vec3 center; - b3Matrix3 centralInertia; - - // Geometry - int vertexCount; - int vertexOffset; - int pointOffset; - - // This is the half-edge count (double the edge count) - int edgeCount; - int edgeOffset; - - int faceCount; - int faceOffset; - int planeOffset; - -} b3Hull; +/** + * @addtogroup hull + * @{ + */ +/// Get read only hull vertices. B3_INLINE const b3HullVertex* b3GetHullVertices( const b3Hull* hull ) { if ( hull->vertexOffset == 0 ) @@ -494,6 +153,7 @@ B3_INLINE const b3HullVertex* b3GetHullVertices( const b3Hull* hull ) return (const b3HullVertex*)( (intptr_t)hull + hull->vertexOffset ); } +/// Get read only hull points. B3_INLINE const b3Vec3* b3GetHullPoints( const b3Hull* hull ) { if ( hull->pointOffset == 0 ) @@ -504,6 +164,7 @@ B3_INLINE const b3Vec3* b3GetHullPoints( const b3Hull* hull ) return (const b3Vec3*)( (intptr_t)hull + hull->pointOffset ); } +/// Get read only hull half edges. B3_INLINE const b3HullHalfEdge* b3GetHullEdges( const b3Hull* hull ) { if ( hull->edgeOffset == 0 ) @@ -514,6 +175,7 @@ B3_INLINE const b3HullHalfEdge* b3GetHullEdges( const b3Hull* hull ) return (const b3HullHalfEdge*)( (intptr_t)hull + hull->edgeOffset ); } +/// Get read only hull faces. B3_INLINE const b3HullFace* b3GetHullFaces( const b3Hull* hull ) { if ( hull->faceOffset == 0 ) @@ -524,6 +186,7 @@ B3_INLINE const b3HullFace* b3GetHullFaces( const b3Hull* hull ) return (const b3HullFace*)( (intptr_t)hull + hull->faceOffset ); } +/// Get read only hull planes. B3_INLINE const b3Plane* b3GetHullPlanes( const b3Hull* hull ) { if ( hull->planeOffset == 0 ) @@ -534,40 +197,41 @@ B3_INLINE const b3Plane* b3GetHullPlanes( const b3Hull* hull ) return (const b3Plane*)( (intptr_t)hull + hull->planeOffset ); } +/// Create a tessellated cylinder as a hull. B3_API b3Hull* b3CreateCylinder( float height, float radius, float yOffset, int sides ); + +/// Create a tessellated cone as a hull. B3_API b3Hull* b3CreateCone( float height, float radius1, float radius2, int slices ); + +/// Create a generic convex hull. B3_API b3Hull* b3CreateHull( const b3Vec3* points, int pointCount, int maxVertexCount ); + +/// Deep clone a hull. B3_API b3Hull* b3CloneHull( const b3Hull* hull ); + +/// Clone and transform a hull. Supports non-uniform and mirroring scale. B3_API b3Hull* b3CloneAndTransformHull( const b3Hull* original, b3Transform transform, b3Vec3 scale ); + +/// Destroy a hull. B3_API void b3DestroyHull( b3Hull* hull ); -/// Efficient box hull -typedef struct b3BoxHull -{ - b3Hull base; - b3HullVertex boxVertices[8]; - b3Vec3 boxPoints[8]; - b3HullHalfEdge boxEdges[24]; - b3HullFace boxFaces[6]; - b3Plane boxPlanes[6]; -} b3BoxHull; - -/// This makes a box hull cube. Do not call b3DestroyHull on this. +/// Make a cube as a hull. Do not call b3DestroyHull on this. B3_API b3BoxHull b3MakeCubeHull( float halfWidth ); -/// This makes a box hull. Do not call b3DestroyHull on this. +/// Make a box as a hull. Do not call b3DestroyHull on this. B3_API b3BoxHull b3MakeBoxHull( float hx, float hy, float hz ); +/// Make an offset box as a hull. Do not call b3DestroyHull on this. B3_API b3BoxHull b3MakeOffsetBoxHull( float hx, float hy, float hz, b3Vec3 offset ); -/// This makes an transformed box hull. Do not call b3DestroyHull on this. +/// Make a transformed box as a hull. Do not call b3DestroyHull on this. /// @param hx, hy, hz positive half widths /// @param transform local transform of box B3_API b3BoxHull b3MakeTransformedBoxHull( float hx, float hy, float hz, b3Transform transform ); -/// This makes an transformed box hull with post scaling. This is useful for boxes that are scaled in -/// a level editor. Such scaling can have reflection and sheer. In the case of sheer the result -/// may be approximate. If you need to support sheer consider using b3CreateHull. +/// This makes a transformed box hull with post scaling. This is useful for boxes that are scaled in +/// a level editor. Such scaling can have reflection and shear. In the case of shear the result +/// may be approximate. If you need to support shear consider using b3CreateHull. /// Do not call b3DestroyHull on this. /// @param halfWidths positive half widths /// @param transform local transform of box @@ -583,111 +247,14 @@ B3_API b3BoxHull b3MakeScaledBoxHull( b3Vec3 halfWidths, b3Transform transform, /// @param minHalfWidth the minimum half width after scale is applied B3_API void b3ScaleBox( b3Vec3* halfWidths, b3Transform* transform, b3Vec3 postScale, float minHalfWidth ); -// 64-bit guid that is changed every time the format of the mesh changes -#define B3_MESH_VERSION 0x4A1E7B2C8D5F3091ull +/**@}*/ // hull -typedef enum b3MeshEdgeFlags -{ - b3_concaveEdge1 = 0x01, - b3_concaveEdge2 = 0x02, - b3_concaveEdge3 = 0x04, +/** + * @addtogroup mesh + * @{ + */ - b3_inverseConcaveEdge1 = 0x10, - b3_inverseConcaveEdge2 = 0x20, - b3_inverseConcaveEdge3 = 0x40, - - b3_allConcaveEdges = b3_concaveEdge1 | b3_concaveEdge2 | b3_concaveEdge3, - - b3_flatEdge1 = b3_concaveEdge1 | b3_inverseConcaveEdge1, - b3_flatEdge2 = b3_concaveEdge2 | b3_inverseConcaveEdge2, - b3_flatEdge3 = b3_concaveEdge3 | b3_inverseConcaveEdge3, - - b3_allFlatEdges = b3_flatEdge1 | b3_flatEdge2 | b3_flatEdge3, - -} b3MeshEdgeFlags; - -typedef struct b3MeshTriangle -{ - int32_t index1; - int32_t index2; - int32_t index3; -} b3MeshTriangle; - -typedef struct b3MeshNode -{ - b3Vec3 lowerBound; - union - { - // Internal node - struct - { - uint32_t axis : 2; - uint32_t childOffset : 30; - } asNode; - - // Leaf node - struct - { - uint32_t type : 2; - uint32_t triangleCount : 30; - } asLeaf; - } data; - - b3Vec3 upperBound; - uint32_t triangleOffset; -} b3MeshNode; - -/// This is a sorted triangle collision tree. -/// @note This struct has data hanging off the end and cannot be directly copied. -typedef struct b3MeshData -{ - // Version must be first - uint64_t version; - int byteCount; - - // Hash of this mesh (this field is zero when the hash is computed) - uint32_t hash; - - b3AABB bounds; - - /// Combined surface area of all triangles. Single-sided. - float surfaceArea; - - int treeHeight; - int degenerateCount; - - // Offset of the node array in bytes from the struct address - int nodeOffset; - int nodeCount; - - // Offset of the vertex array in bytes from the struct address - int vertexOffset; - int vertexCount; - - // Offset of the triangle array in bytes from the struct address - int triangleOffset; - int triangleCount; - - // Offset of the material array in bytes from the struct address - int materialOffset; - int materialCount; - - // Offset of the triangle flag array in bytes from the struct address - int flagsOffset; -} b3MeshData; - -/// This small struct allows a mesh data to be re-used with different scale. -typedef struct b3Mesh -{ - const b3MeshData* data; - - /// This scale may be non-uniform and have negative components. However, - /// no component may be zero or very small in magnitude. - b3Vec3 scale; - -} b3Mesh; - -// todo these don't need to be inline +/// Get read only mesh BVH nodes. B3_INLINE const b3MeshNode* b3GetMeshNodes( const b3MeshData* mesh ) { if ( mesh->nodeOffset == 0 ) @@ -698,6 +265,7 @@ B3_INLINE const b3MeshNode* b3GetMeshNodes( const b3MeshData* mesh ) return (const b3MeshNode*)( (intptr_t)mesh + mesh->nodeOffset ); } +/// Get read only mesh vertices. B3_INLINE const b3Vec3* b3GetMeshVertices( const b3MeshData* mesh ) { if ( mesh->vertexOffset == 0 ) @@ -708,6 +276,7 @@ B3_INLINE const b3Vec3* b3GetMeshVertices( const b3MeshData* mesh ) return (const b3Vec3*)( (intptr_t)mesh + mesh->vertexOffset ); } +/// Get read only mesh triangles. B3_INLINE const b3MeshTriangle* b3GetMeshTriangles( const b3MeshData* mesh ) { if ( mesh->triangleOffset == 0 ) @@ -718,7 +287,7 @@ B3_INLINE const b3MeshTriangle* b3GetMeshTriangles( const b3MeshData* mesh ) return (const b3MeshTriangle*)( (intptr_t)mesh + mesh->triangleOffset ); } -// @note count is equal to the triangle count +/// Get read only mesh materials. The count is equal to the triangle count. B3_INLINE const uint8_t* b3GetMeshMaterialIndices( const b3MeshData* mesh ) { if ( mesh->materialOffset == 0 ) @@ -729,7 +298,7 @@ B3_INLINE const uint8_t* b3GetMeshMaterialIndices( const b3MeshData* mesh ) return (const uint8_t*)( (intptr_t)mesh + mesh->materialOffset ); } -// @note count is equal to the triangle count +/// Get read only mesh flags. The count is equal to the triangle count. B3_INLINE const uint8_t* b3GetMeshFlags( const b3MeshData* mesh ) { if ( mesh->flagsOffset == 0 ) @@ -740,39 +309,7 @@ B3_INLINE const uint8_t* b3GetMeshFlags( const b3MeshData* mesh ) return (const uint8_t*)( (intptr_t)mesh + mesh->flagsOffset ); } -/// This is used to create a re-usable collision mesh -typedef struct b3MeshDef -{ - /// Triangle vertices - b3Vec3* vertices; - - /// Triangle vertex indices. 3 for each triangle. - int32_t* indices; - - /// Triangle material index. 1 per triangle. Indexes into b3ShapeDef::materials. - /// This allows different run-time material data to be associated with different - /// instances of this mesh. - uint8_t* materialIndices; - - /// Tolerance for vertex welding in length units. - float weldTolerance; - - int vertexCount; - int triangleCount; - - /// Optionally weld nearby vertices. - bool weldVertices; - - /// Use the median split instead of SAH to speed up mesh creation. Good - /// for meshes that are structured like a grid. - bool useMedianSplit; - - /// Compute triangle adjacency information using shared edges - bool identifyEdges; - -} b3MeshDef; - -/// Creates a grid mesh along the x and z axes. +/// Create a grid mesh along the x and z axes. /// @param xCount the number of rows in the x direction /// @param zCount the number of rows in the z direction /// @param cellWidth the width of each cell @@ -780,212 +317,89 @@ typedef struct b3MeshDef /// @param identifyEdges compute adjacency information B3_API b3MeshData* b3CreateGridMesh( int xCount, int zCount, float cellWidth, int materialCount, bool identifyEdges ); +/// Create a wave mesh along the x and z axes. B3_API b3MeshData* b3CreateWaveMesh( int xCount, int zCount, float cellWidth, float amplitude, float rowFrequency, float columnFrequency ); + +/// Create a torus mesh. B3_API b3MeshData* b3CreateTorusMesh( int radialResolution, int tubularResolution, float radius, float thickness ); + +/// Create a box mesh. B3_API b3MeshData* b3CreateBoxMesh( b3Vec3 center, b3Vec3 extent, bool identifyEdges ); + +/// Create a hollow box mesh. B3_API b3MeshData* b3CreateHollowBoxMesh( b3Vec3 center, b3Vec3 extent ); + +/// Create a platform mesh. A truncated pyramid. B3_API b3MeshData* b3CreatePlatformMesh( b3Vec3 center, float height, float topWidth, float bottomWidth ); + +/// Create a generic mesh. B3_API b3MeshData* b3CreateMesh( const b3MeshDef* def, int* degenerateTriangleIndices, int degenerateCapacity ); + +/// Destroy a mesh. B3_API void b3DestroyMesh( b3MeshData* mesh ); + +/// Get the height of the mesh BVH. B3_API int b3GetHeight( const b3MeshData* mesh ); -/// Data used to create a height field -typedef struct b3HeightFieldDef -{ - // Grid point heights - // count = countX * countZ - float* heights; +/**@}*/ // mesh - // Grid cell material - // A value of 0xFF is reserved for holes - // count = (countX - 1) * (countZ - 1) - uint8_t* materialIndices; +/** + * @addtogroup height_field + * @{ + */ - b3Vec3 scale; - int countX; - int countZ; - - // Global minimum and maximum heights used for quantization. This is important - // if you want height fields to be placed next to each other and line up exactly. - // In that case, both height fields should use the same minimum and maximum heights. - // All height values are clamped to this range. - // These values are in unscaled space. - float globalMinimumHeight; - float globalMaximumHeight; - - bool clockwiseWinding; -} b3HeightFieldDef; - -// This material index is used to designate holes in a height field. -#define B3_HEIGHT_FIELD_HOLE 0xFF - -// 64-bit guid that is changed every time the format of the height field changes -#define B3_HEIGHT_FIELD_VERSION 0xB6E83F1D947A28C5ull - -// A height field with compressed storage. -typedef struct b3HeightField -{ - // Version must be first - uint64_t version; - - // todo_erin use offset storage - uint16_t* compressedHeights; - uint8_t* materialIndices; - uint8_t* flags; - - // Hash of this height field (this field is zero when the hash is computed). - // Pointer values above are skipped; the bulk arrays they reference and the - // scalar block below are folded in at construction time. - uint32_t hash; - - b3AABB aabb; - float minHeight; - float maxHeight; - float heightScale; - b3Vec3 scale; - int columnCount; - int rowCount; - bool clockwise; -} b3HeightField; - -// Create a height field +/// Create a generic height field. B3_API b3HeightField* b3CreateHeightField( const b3HeightFieldDef* data ); + +/// Create a grid as a height field. B3_API b3HeightField* b3CreateGrid( int rowCount, int columnCount, b3Vec3 scale, bool makeHoles ); + +/// Create a wave grid as a height field. B3_API b3HeightField* b3CreateWave( int rowCount, int columnCount, b3Vec3 scale, float rowFrequency, float columnFrequency, bool makeHoles ); + +/// Destroy a height field. B3_API void b3DestroyHeightField( b3HeightField* heightField ); -// Save input height data to a file +/// Save input height data to a file B3_API void b3DumpHeightData( const b3HeightFieldDef* data, const char* fileName ); -// Create a height field by loading a previously saved height data +/// Create a height field by loading a previously saved height data B3_API b3HeightField* b3LoadHeightField( const char* fileName ); -typedef struct b3CompoundCapsuleDef -{ - b3Capsule capsule; - b3SurfaceMaterial material; -} b3CompoundCapsuleDef; +/**@}*/ // height_field -typedef struct b3CompoundHullDef -{ - const b3Hull* hull; - b3Transform transform; - b3SurfaceMaterial material; -} b3CompoundHullDef; +/** + * @addtogroup compound + * @{ + */ -typedef struct b3CompoundMeshDef -{ - const b3MeshData* meshData; - b3Transform transform; - b3Vec3 scale; +/// Get a child shape of a compound. +B3_API b3ChildShape b3GetCompoundChild( const b3Compound* compound, int childIndex ); - // This array must line up with the material indices on the triangles. - const b3SurfaceMaterial* materials; - int materialCount; - -} b3CompoundMeshDef; - -typedef struct b3CompoundSphereDef -{ - b3Sphere sphere; - b3SurfaceMaterial material; -} b3CompoundSphereDef; - -/// Definition to creating a compound shape. No data in this structure -/// is referenced in the compound. -typedef struct b3CompoundDef -{ - b3CompoundCapsuleDef* capsules; - int capsuleCount; - - /// Hulls instances. - b3CompoundHullDef* hulls; - int hullCount; - - /// Mesh instances - b3CompoundMeshDef* meshes; - int meshCount; - - /// Spheres are fully cloned - b3CompoundSphereDef* spheres; - int sphereCount; -} b3CompoundDef; - -#define B3_COMPOUND_VERSION ( 0x902AC5D34D9BD452ull ^ B3_DYNAMIC_TREE_VERSION ^ B3_MESH_VERSION ^ B3_HULL_VERSION ) - -/// Meshes used in compounds have limited space for materials. If you have -/// a mesh with many materials, you can use it outside of the the compound. -#define B3_MAX_COMPOUND_MESH_MATERIALS 4 - -typedef struct b3Compound -{ - uint64_t version; - int byteCount; - - // immutable tree - // The tree node pointer must be fixed up using the node offset - // todo use a custom tree like b3MeshData to save space and improve performance - int nodeOffset; - b3DynamicTree tree; - - int materialOffset; - int materialCount; - - int capsuleOffset; - int capsuleCount; - - int hullOffset; - int hullCount; - int sharedHullCount; - - int meshOffset; - int meshCount; - int sharedMeshCount; - - int sphereOffset; - int sphereCount; -} b3Compound; - -typedef struct b3CompoundCapsule -{ - b3Capsule capsule; - int materialIndex; -} b3CompoundCapsule; - -typedef struct b3CompoundHull -{ - const b3Hull* hull; - b3Transform transform; - int materialIndex; -} b3CompoundHull; - -typedef struct b3CompoundMesh -{ - const b3MeshData* meshData; - b3Transform transform; - b3Vec3 scale; - - // This is used to access the surface material from b3GetCompoundMaterials - // materialIndex = materialIndices[triangle->materialIndex] - int materialIndices[B3_MAX_COMPOUND_MESH_MATERIALS]; -} b3CompoundMesh; - -typedef struct b3CompoundSphere -{ - b3Sphere sphere; - int materialIndex; -} b3CompoundSphere; +/// Query a compound shape for children that overlap an AABB. +B3_API void b3QueryCompound( const b3Compound* compound, b3AABB aabb, b3CompoundQueryFcn* fcn, void* context ); +/// Access a child capsule by index. B3_API b3CompoundCapsule b3GetCompoundCapsule( const b3Compound* compound, int index ); + +/// Access a child hull by index. B3_API b3CompoundHull b3GetCompoundHull( const b3Compound* compound, int index ); + +/// Access a child mesh by index. B3_API b3CompoundMesh b3GetCompoundMesh( const b3Compound* compound, int index ); + +/// Access a child sphere by index. B3_API b3CompoundSphere b3GetCompoundSphere( const b3Compound* compound, int index ); + +/// Access the compound material array. B3_API const b3SurfaceMaterial* b3GetCompoundMaterials( const b3Compound* compound ); -// All input data in the definition is cloned into the resulting compound +/// Create a compound shape. All input data in the definition is cloned into the resulting compound. B3_API b3Compound* b3CreateCompound( const b3CompoundDef* def ); + +/// Destroy a compound shape. B3_API void b3DestroyCompound( b3Compound* compound ); /// If bytes is null then this returns the number of required bytes. This clones all the @@ -998,6 +412,13 @@ B3_API uint8_t* b3ConvertCompoundToBytes( b3Compound* compound ); /// The bytes are mutated to fixup pointers. B3_API b3Compound* b3ConvertBytesToCompound( uint8_t* bytes, int byteCount ); +/**@}*/ // compound + +/** + * @addtogroup geometry + * @{ + */ + /// Compute mass properties of a sphere B3_API b3MassData b3ComputeSphereMass( const b3Sphere* shape, float density ); @@ -1025,6 +446,13 @@ B3_API b3AABB b3ComputeHeightFieldAABB( const b3HeightField* shape, b3Transform /// Compute the bounding box of a compound B3_API b3AABB b3ComputeCompoundAABB( const b3Compound* shape, b3Transform transform ); +/**@}*/ // geometry + +/** + * @addtogroup query + * @{ + */ + /// Use this to ensure your ray cast input is valid and avoid internal assertions. B3_API bool b3IsValidRay( const b3RayCastInput* input ); @@ -1102,441 +530,82 @@ B3_API void b3QueryMesh( const b3Mesh* mesh, const b3AABB bounds, b3MeshQueryFcn /// @param context the context sent to the user function. B3_API void b3QueryHeightField( const b3HeightField* heightField, b3AABB bounds, b3MeshQueryFcn* fcn, void* context ); -/** - * @defgroup distance Distance - * Functions for computing the distance between shapes. - * - * These are advanced functions you can use to perform distance calculations. There - * are functions for computing the closest points between shapes, doing linear shape casts, - * and doing rotational shape casts. The latter is called time of impact (TOI). - * @{ - */ - -/// Result of computing the distance between two line segments -typedef struct b3SegmentDistanceResult -{ - /// The closest point on the first segment - b3Vec3 closest1; - - /// The closest point on the second segment - b3Vec3 closest2; - - /// The barycentric coordinate on the first segment - float fraction1; - - /// The barycentric coordinate on the second segment - float fraction2; - - /// The squared distance between the closest points - float distanceSquared; -} b3SegmentDistanceResult; - -/// Compute the distance between two line segments, clamping at the end points if needed. -B3_API b3SegmentDistanceResult b3SegmentDistance( b3Vec3 p1, b3Vec3 q1, b3Vec3 p2, b3Vec3 q2 ); - -/// Used to warm start the GJK simplex. If you call this function multiple times with nearby -/// transforms this might improve performance. Otherwise you can zero initialize this. -/// The distance cache must be initialized to zero on the first call. -/// Users should generally just zero initialize this structure for each call. -typedef struct b3SimplexCache -{ - /// Value use to compare length, area, volume of two simplexes. - float metric; - - // todo use an index of 0xFF as a sentinel and remove the count - /// The number of stored simplex points - uint16_t count; - - /// The cached simplex indices on shape A - uint8_t indexA[4]; - - /// The cached simplex indices on shape B - uint8_t indexB[4]; - -} b3SimplexCache; - -static const b3SimplexCache b3_emptyDistanceCache = B3_ZERO_INIT; - -/// Input for b3ShapeDistance -typedef struct b3DistanceInput -{ - /// The proxy for shape A - b3ShapeProxy proxyA; - - /// The proxy for shape B - b3ShapeProxy proxyB; - - /// The world transform for shape A - b3Transform transformA; - - /// The world transform for shape B - b3Transform transformB; - - /// Should the proxy radius be considered? - bool useRadii; -} b3DistanceInput; - -/// Output for b3ShapeDistance -typedef struct b3DistanceOutput -{ - b3Vec3 pointA; ///< Closest point on shapeA - b3Vec3 pointB; ///< Closest point on shapeB - b3Vec3 normal; ///< Normal vector pointing from A to B - float distance; ///< The final distance, zero if overlapped - int iterations; ///< Number of GJK iterations used - int simplexCount; ///< The number of simplexes stored in the simplex array -} b3DistanceOutput; - -/// Simplex vertex for debugging the GJK algorithm -typedef struct b3SimplexVertex -{ - b3Vec3 wA; ///< support point in proxyA - b3Vec3 wB; ///< support point in proxyB - b3Vec3 w; ///< wB - wA - float a; ///< barycentric coordinates - int indexA; ///< wA index - int indexB; ///< wB index -} b3SimplexVertex; - -/// Simplex from the GJK algorithm -typedef struct b3Simplex -{ - b3SimplexVertex vertices[4]; ///< vertices - int count; ///< number of valid vertices -} b3Simplex; - /// Compute the closest points between two shapes represented as point clouds. /// b3SimplexCache cache is input/output. On the first call set b3SimplexCache.count to zero. /// The underlying GJK algorithm may be debugged by passing in debug simplexes and capacity. You may pass in NULL and 0 for these. -/// todo make cache optional (can be null) B3_API b3DistanceOutput b3ShapeDistance( const b3DistanceInput* input, b3SimplexCache* cache, b3Simplex* simplexes, int simplexCapacity ); -/// Input parameters for b3ShapeCast -typedef struct b3ShapeCastPairInput -{ - b3ShapeProxy proxyA; ///< The proxy for shape A - b3ShapeProxy proxyB; ///< The proxy for shape B - b3Transform transformA; ///< The world transform for shape A - b3Transform transformB; ///< The world transform for shape B - b3Vec3 translationB; ///< The translation of shape B - float maxFraction; ///< The fraction of the translation to consider, typically 1 - bool canEncroach; ///< Allows shapes with a radius to move slightly closer if already touching -} b3ShapeCastPairInput; - /// Perform a linear shape cast of shape B moving and shape A fixed. Determines the hit point, normal, and translation fraction. B3_API b3CastOutput b3ShapeCast( const b3ShapeCastPairInput* input ); -/// This describes the motion of a body/shape for TOI computation. Shapes are defined with respect to the body origin, -/// which may not coincide with the center of mass. However, to support dynamics we must interpolate the center of mass -/// position. -typedef struct b3Sweep -{ - b3Vec3 localCenter; ///< Local center of mass position - b3Vec3 c1; ///< Starting center of mass world position - b3Vec3 c2; ///< Ending center of mass world position - b3Quat q1; ///< Starting world rotation - b3Quat q2; ///< Ending world rotation -} b3Sweep; - /// Evaluate the transform sweep at a specific time. B3_API b3Transform b3GetSweepTransform( const b3Sweep* sweep, float time ); -/// Time of impact input -typedef struct b3TOIInput -{ - b3ShapeProxy proxyA; ///< The proxy for shape A - b3ShapeProxy proxyB; ///< The proxy for shape B - b3Sweep sweepA; ///< The movement of shape A - b3Sweep sweepB; ///< The movement of shape B - float maxFraction; ///< Defines the sweep interval [0, tMax] -} b3TOIInput; - -/// Describes the TOI output -typedef enum b3TOIState -{ - b3_toiStateUnknown, - b3_toiStateFailed, - b3_toiStateOverlapped, - b3_toiStateHit, - b3_toiStateSeparated -} b3TOIState; - -/// Time of impact output -typedef struct b3TOIOutput -{ - /// The type of result - b3TOIState state; - - /// The hit point - b3Vec3 point; - - /// The hit normal - b3Vec3 normal; - - /// The sweep time of the collision - float fraction; - - /// The final distance - float distance; - - /// Number of outer iterations - int distanceIterations; - - /// Total number of push back iterations - int pushBackIterations; - - /// Total number of root iterations - int rootIterations; - - bool usedFallback; -} b3TOIOutput; - /// Compute the upper bound on time before two shapes penetrate. Time is represented as /// a fraction between [0,tMax]. This uses a swept separating axis and may miss some intermediate, /// non-tunneling collisions. If you change the time interval, you should call this function /// again. B3_API b3TOIOutput b3TimeOfImpact( const b3TOIInput* input ); -/**@}*/ - -/// A manifold point is a contact point belonging to a contact manifold. -/// It holds details related to the geometry and dynamics of the contact points. -/// Box3D uses speculative collision so some contact points may be separated. -/// You may use the maxNormalImpulse to determine if there was an interaction during -/// the time step. -typedef struct b3ManifoldPoint -{ - /// Location of the contact point relative to the bodyA center of mass in world space. - b3Vec3 anchorA; - - /// Location of the contact point relative to the bodyB center of mass in world space. - b3Vec3 anchorB; - - /// The separation of the contact point, negative if penetrating - float separation; - - /// Cached separation used for contact recycling - float baseSeparation; - - /// The impulse along the manifold normal vector. Since Box3D uses sub-stepping, this is - /// result from the final sub-step. - float normalImpulse; - - /// The total normal impulse applied during sub-stepping. This is important - /// to identify speculative contact points that had an interaction in the time step. - float totalNormalImpulse; - - /// Relative normal velocity pre-solve. Used for hit events. If the normal impulse is - /// zero then there was no hit. Negative means shapes are approaching. - float normalVelocity; - - /// Local point for matching - /// Uniquely identifies a contact point between two shapes - uint32_t featureId; - - /// Triangle index if one of the shapes is a mesh or height field - int triangleIndex; - - /// Did this contact point exist the previous step? - bool persisted; -} b3ManifoldPoint; - -/// The maximum number of contact points between two touching shapes. -#define B3_MAX_MANIFOLD_POINTS 4 - -/// A contact manifold describes the contact points between colliding shapes. -/// @note Box3D uses speculative collision so some contact points may be separated. -typedef struct b3Manifold -{ - /// The manifold points. There may be 1 to 4 valid points. - b3ManifoldPoint points[B3_MAX_MANIFOLD_POINTS]; - - /// The unit normal vector in world space, points from shape A to bodyB - b3Vec3 normal; - - // Central friction angular impulse (applied about the normal) - float twistImpulse; - - // Central friction linear impulse - b3Vec3 frictionImpulse; - - // Rolling resistance angular impulse - b3Vec3 rollingImpulse; - - /// The number of contacts points, will be 0, 1, or 2 - int pointCount; - -} b3Manifold; - -// todo adopt this for SAT -typedef enum -{ - b3_invalidAxis = 0, - b3_backsideAxis, - b3_faceAxisA, - b3_faceAxisB, - b3_edgePairAxis, - b3_closestPointsAxis, - - // These are for testing - b3_manualFaceAxisA, - b3_manualFaceAxisB, - b3_manualEdgePairAxis, -} b3SeparatingFeature; - -typedef enum -{ - b3_featureNone = 0, - b3_featureTriangleFace, - b3_featureHullFace, - // v1-v2 - b3_featureEdge1, - // v2-v3 - b3_featureEdge2, - // v3-v1 - b3_featureEdge3, - b3_featureVertex1, - b3_featureVertex2, - b3_featureVertex3 -} b3TriangleFeature; - -typedef struct -{ - float separation; - // b3SeparatingFeature - uint8_t type; - uint8_t indexA; - uint8_t indexB; - uint8_t hit; -} b3SATCache; - -/// Contact points are always the result of two edges intersecting. -/// It can be two edges of the same shape, which is just a shape vertex. -/// Or a contact point can be the result of two edges crossing from different shapes. -/// This is designed to support hull versus hull, but it is adapted to work -/// with all shape types. The feature pair is used to identify contact points -/// for temporal coherence and warm starting. -typedef struct b3FeaturePair -{ - // Incoming type (either edge on shape A or shape B) - uint8_t owner1; - // Incoming edge index (into associated shape array) - uint8_t index1; - // Outgoing type (either edge on shape A or shape B) - uint8_t owner2; - // Outgoing edge index (into associated shape array) - uint8_t index2; -} b3FeaturePair; - -/// A local manifold point and normal in frame A -typedef struct b3LocalManifoldPoint -{ - b3Vec3 point; - float separation; - b3FeaturePair pair; - int triangleIndex; -} b3LocalManifoldPoint; - -/// A local manifold with no dynamic information. Used by b3Collide functions. -typedef struct b3LocalManifold -{ - b3Vec3 normal; - b3Vec3 triangleNormal; - b3LocalManifoldPoint* points; - int pointCount; - int triangleIndex; - int i1, i2, i3; - float squaredDistance; - b3TriangleFeature feature; - int triangleFlags; -} b3LocalManifold; - -B3_API void b3CollideSpheres( b3LocalManifold* manifold, int capacity, const b3Sphere* sphereA, const b3Sphere* sphereB, - b3Transform transformBtoA ); - -B3_API void b3CollideCapsuleAndSphere( b3LocalManifold* manifold, int capacity, const b3Capsule* capsuleA, const b3Sphere* sphereB, - b3Transform transformBtoA ); - -B3_API void b3CollideHullAndSphere( b3LocalManifold* manifold, int capacity, const b3Hull* hullA, const b3Sphere* sphereB, - b3Transform transformBtoA, b3SimplexCache* cache ); - -B3_API void b3CollideCapsules( b3LocalManifold* manifold, int capacity, const b3Capsule* capsuleA, const b3Capsule* capsuleB, - b3Transform transformBtoA ); - -B3_API void b3CollideHullAndCapsule( b3LocalManifold* manifold, int capacity, const b3Hull* hullA, const b3Capsule* capsuleB, - b3Transform transformBtoA, b3SimplexCache* cache ); - -B3_API void b3CollideHulls( b3LocalManifold* manifold, int capacity, const b3Hull* hullA, const b3Hull* hullB, - b3Transform transformBtoA, b3SATCache* cache ); - -B3_API void b3CollideCapsuleAndTriangle( b3LocalManifold* manifold, int capacity, const b3Capsule* capsuleA, - const b3Vec3* triangleB, b3SimplexCache* cache ); - -// b3MeshEdgeFlags -B3_API void b3CollideHullAndTriangle( b3LocalManifold* manifold, int capacity, const b3Hull* hullA, b3Vec3 v1, b3Vec3 v2, b3Vec3 v3, - int triangleFlags, b3SATCache* cache ); - -B3_API void b3CollideSphereAndTriangle( b3LocalManifold* manifold, int capacity, const b3Sphere* sphereA, const b3Vec3* triangleB ); - -B3_API bool b3IntersectRayAndAABB( b3Vec3 lowerBound, b3Vec3 upperBound, b3Vec3 p1, b3Vec3 p2, float* minFraction, - float* maxFraction ); - -/**@}*/ +/**@}*/ // query /** - * @defgroup character - * Experimental character movement solver + * @addtogroup collision * @{ */ -typedef struct b3PlaneResult -{ - b3Plane plane; - b3Vec3 point; -} b3PlaneResult; +/// Collide two spheres. +B3_API void b3CollideSpheres( b3LocalManifold* manifold, int capacity, const b3Sphere* sphereA, const b3Sphere* sphereB, + b3Transform transformBtoA ); -typedef struct b3CollisionPlane -{ - b3Plane plane; - float pushLimit; - float push; - bool clipVelocity; -} b3CollisionPlane; +/// Collide a capsule and a sphere. +B3_API void b3CollideCapsuleAndSphere( b3LocalManifold* manifold, int capacity, const b3Capsule* capsuleA, + const b3Sphere* sphereB, b3Transform transformBtoA ); -typedef struct b3PlaneSolverResult -{ - b3Vec3 delta; - int iterationCount; -} b3PlaneSolverResult; +/// Collide a hull and a sphere. +B3_API void b3CollideHullAndSphere( b3LocalManifold* manifold, int capacity, const b3Hull* hullA, const b3Sphere* sphereB, + b3Transform transformBtoA, b3SimplexCache* cache ); +/// Collide two capsules. +B3_API void b3CollideCapsules( b3LocalManifold* manifold, int capacity, const b3Capsule* capsuleA, const b3Capsule* capsuleB, + b3Transform transformBtoA ); + +/// Collide a hull and a capsule. +B3_API void b3CollideHullAndCapsule( b3LocalManifold* manifold, int capacity, const b3Hull* hullA, const b3Capsule* capsuleB, + b3Transform transformBtoA, b3SimplexCache* cache ); + +/// Collide two hulls. +B3_API void b3CollideHulls( b3LocalManifold* manifold, int capacity, const b3Hull* hullA, const b3Hull* hullB, + b3Transform transformBtoA, b3SATCache* cache ); + +/// Collide a capsule and a triangle. +B3_API void b3CollideCapsuleAndTriangle( b3LocalManifold* manifold, int capacity, const b3Capsule* capsuleA, + const b3Vec3* triangleB, b3SimplexCache* cache ); + +/// Collide a hull and a triangle. +B3_API void b3CollideHullAndTriangle( b3LocalManifold* manifold, int capacity, const b3Hull* hullA, b3Vec3 v1, b3Vec3 v2, + b3Vec3 v3, int triangleFlags, b3SATCache* cache ); + +/// Collide a sphere and a triangle. +B3_API void b3CollideSphereAndTriangle( b3LocalManifold* manifold, int capacity, const b3Sphere* sphereA, + const b3Vec3* triangleB ); + +/**@}*/ // collision + +/** + * @addtogroup character + * @{ + */ + +/// Solves the position of a mover that satisfies the given collision planes. +/// @param targetDelta the desired translation from the position used to generate the collision planes +/// @param planes the collision planes +/// @param count the number of collision planes B3_API b3PlaneSolverResult b3SolvePlanes( b3Vec3 targetDelta, b3CollisionPlane* planes, int count ); + +/// Clips the velocity against the given collision planes. Planes with zero push or clipVelocity +/// set to false are skipped. B3_API b3Vec3 b3ClipVector( b3Vec3 vector, const b3CollisionPlane* planes, int count ); -/**@}*/ - -typedef struct b3ClosestApproachResult -{ - b3Vec3 point1; - float lambda1; - b3Vec3 point2; - float lambda2; -} b3ClosestApproachResult; - -/// Compute the closest point on the segment a-b to the target q -B3_API b3Vec3 b3ClosestPointOnSegment( b3Vec3 a, b3Vec3 b, b3Vec3 q ); - -/// Compute the closest points on two infinite lines -B3_API b3ClosestApproachResult b3ClosestApproachLines( b3Vec3 p1, b3Vec3 d1, b3Vec3 p2, b3Vec3 d2 ); - -/// Compute the closest points on two line segments -B3_API b3ClosestApproachResult b3ClosestApproachSegments( b3Vec3 p1, b3Vec3 q1, b3Vec3 p2, b3Vec3 q2 ); - -typedef struct b3Point2D -{ - b3Vec2 p; - float separation; - int originalIndex; -} b3Point2D; - -B3_API int b3CullPoints( b3Point2D* points, int count ); +/**@}*/ // character diff --git a/include/box3d/constants.h b/include/box3d/constants.h index c661e6f..6fd35c7 100644 --- a/include/box3d/constants.h +++ b/include/box3d/constants.h @@ -5,10 +5,10 @@ #include "base.h" -/// Box2D bases all length units on meters, but you may need different units for your game. +/// Box3D bases all length units on meters, but you may need different units for your game. /// You can set this value to use different units. This should be done at application startup /// and only modified once. Default value is 1. -/// @warning This must be modified before any calls to Box2D +/// @warning This must be modified before any calls to Box3D B3_API void b3SetLengthUnitsPerMeter( float lengthUnits ); /// Get the current length units per meter. @@ -21,7 +21,7 @@ B3_API float b3GetLengthUnitsPerMeter( void ); /// Maximum parallel workers. Used for some fixed size arrays. #define B3_MAX_WORKERS 32 -/// Maximum number of tasks queued per world step. b2EnqueueTaskCallback will never be called +/// Maximum number of tasks queued per world step. b3EnqueueTaskCallback will never be called /// more than this per world step. This is related to B3_MAX_WORKERS. With 32 workers, /// the maximum observed task count is 130. This allows an external task system to use a fixed /// size array for Box3D task, which may help with creating stable user task pointers. @@ -55,7 +55,7 @@ B3_API float b3GetLengthUnitsPerMeter( void ); /// The maximum rotation of a body per time step. This limit is very large and is used /// to prevent numerical problems. You shouldn't need to adjust this. -/// @warning increasing this to 0.5f * b3_pi or greater will break continuous collision. +/// @warning increasing this to 0.5f * B3_PI or greater will break continuous collision. #define B3_MAX_ROTATION ( 0.25f * B3_PI ) /// @warning modifying this can have a significant impact on performance and stability @@ -91,6 +91,12 @@ B3_API float b3GetLengthUnitsPerMeter( void ); #define B3_NAME_LENGTH 18 #endif +/// The maximum number of contact points between two touching shapes. +#define B3_MAX_MANIFOLD_POINTS 4 + +/// The maximum number points to use for shape cast proxies (swept point cloud). +#define B3_MAX_SHAPE_CAST_POINTS 64 + /// These generous limits allow for easy hashing. See b3ShapePairKey. #define B3_SHAPE_POWER 22 #define B3_CHILD_POWER ( 64 - 2 * B3_SHAPE_POWER ) diff --git a/include/box3d/id.h b/include/box3d/id.h index 7d59c94..447fd34 100644 --- a/include/box3d/id.h +++ b/include/box3d/id.h @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText: 2023 Erin Catto +// SPDX-FileCopyrightText: 2026 Erin Catto // SPDX-License-Identifier: MIT #pragma once @@ -9,9 +9,9 @@ /** * @defgroup id Ids - * These ids serve as handles to internal Box2D objects. + * These ids serve as handles to internal Box3D objects. * These should be considered opaque data and passed by value. - * Include this header if you need the id types and not the whole Box2D API. + * Include this header if you need the id types and not the whole Box3D API. * All ids are considered null if initialized to zero. * * For example in C++: @@ -29,7 +29,7 @@ * These are both considered null. * * @warning Do not use the internals of these ids. They are subject to change. Ids should be treated as opaque objects. - * @warning You should use ids to access objects in Box2D. Do not access files within the src folder. Such usage is unsupported. + * @warning You should use ids to access objects in Box3D. Do not access files within the src folder. Such usage is unsupported. * @{ */ @@ -64,7 +64,7 @@ typedef struct b3JointId uint16_t generation; } b3JointId; -/// Contact id references a contact instance. This should be treated as an opaque handled. +/// Contact id references a contact instance. This should be treated as an opaque handle. typedef struct b3ContactId { int32_t index1; @@ -73,13 +73,19 @@ typedef struct b3ContactId uint32_t generation; } b3ContactId; +// clang-format off #ifdef __cplusplus + /// A null id. Works for any id type. #define B3_NULL_ID {} #define B3_ID_INLINE inline #else + /// A null id. Works for any id type. #define B3_NULL_ID { 0 } + + /// This macro bridges C and C++ inline functions. C++ has the one definition rule that C lacks. #define B3_ID_INLINE static inline #endif +// clang-format on /// Use these to make your identifiers null. /// You may also use zero initialization to get null. @@ -150,7 +156,7 @@ B3_ID_INLINE b3JointId b3LoadJointId( uint64_t x ) return id; } -/// Store a contact id into 16 bytes +/// Store a contact id into three uint32 values B3_ID_INLINE void b3StoreContactId( b3ContactId id, uint32_t values[3] ) { values[0] = (uint32_t)id.index1; @@ -158,7 +164,7 @@ B3_ID_INLINE void b3StoreContactId( b3ContactId id, uint32_t values[3] ) values[2] = (uint32_t)id.generation; } -/// Load a two uint64_t into a contact id. +/// Load a contact id from three uint32 values. B3_ID_INLINE b3ContactId b3LoadContactId( uint32_t values[3] ) { b3ContactId id; diff --git a/include/box3d/math_functions.h b/include/box3d/math_functions.h index c845d9d..a69e9d2 100644 --- a/include/box3d/math_functions.h +++ b/include/box3d/math_functions.h @@ -17,12 +17,26 @@ * @{ */ +/// https://en.wikipedia.org/wiki/Pi +#define B3_PI 3.14159265359f + +/// Convenience macro to convert from degrees to radians. +#define B3_DEG_TO_RAD 0.01745329251f + +/// Convenience macro to convert from radians to degrees. +#define B3_RAD_TO_DEG 57.2957795131f + +/// Minimum scale used for scaling collision meshes, etc. +#define B3_MIN_SCALE 0.01f + +/// A 2D vector. typedef struct b3Vec2 { float x; float y; } b3Vec2; +/// A 3D vector. typedef struct b3Vec3 { float x; @@ -30,8 +44,8 @@ typedef struct b3Vec3 float z; } b3Vec3; -/// Cosine and sine pair -/// This uses a custom implementation designed for cross-platform determinism +/// Cosine and sine pair. +/// This uses a custom implementation designed for cross-platform determinism. typedef struct b3CosSin { /// cosine and sine @@ -39,29 +53,34 @@ typedef struct b3CosSin float sine; } b3CosSin; +/// A quaternion. typedef struct b3Quat { b3Vec3 v; float s; } b3Quat; +/// A rigid transform. typedef struct b3Transform { b3Vec3 p; b3Quat q; } b3Transform; +/// A 3x3 matrix. typedef struct b3Matrix3 { b3Vec3 cx, cy, cz; } b3Matrix3; +/// Axis aligned bounding box. typedef struct b3AABB { b3Vec3 lowerBound; b3Vec3 upperBound; } b3AABB; +/// A plane. /// separation = dot(normal, point) - offset typedef struct b3Plane { @@ -69,87 +88,70 @@ typedef struct b3Plane float offset; } b3Plane; -/**@}*/ - -/** - * @addtogroup math - * @{ - */ - -#define B3_PI 3.141592654f -#define B3_DEG_TO_RAD 0.01745329251f -#define B3_RAD_TO_DEG 57.2957795131f - -/// Minimum scale used for scaling collision meshes, etc. -#define B3_MIN_SCALE 0.01f - static const b3Vec3 b3Vec3_zero = { 0.0f, 0.0f, 0.0f }; static const b3Vec3 b3Vec3_one = { 1.0f, 1.0f, 1.0f }; static const b3Vec3 b3Vec3_axisX = { 1.0f, 0.0f, 0.0f }; static const b3Vec3 b3Vec3_axisY = { 0.0f, 1.0f, 0.0f }; static const b3Vec3 b3Vec3_axisZ = { 0.0f, 0.0f, 1.0f }; - static const b3Quat b3Quat_identity = { { 0.0f, 0.0f, 0.0f }, 1.0f }; static const b3Transform b3Transform_identity = { { 0.0f, 0.0f, 0.0f }, { { 0.0f, 0.0f, 0.0f }, 1.0f } }; - static const b3Matrix3 b3Mat3_zero = { { 0.0f, 0.0f, 0.0f }, { 0.0f, 0.0f, 0.0f }, { 0.0f, 0.0f, 0.0f }, }; - static const b3Matrix3 b3Mat3_identity = { { 1.0f, 0.0f, 0.0f }, { 0.0f, 1.0f, 0.0f }, { 0.0f, 0.0f, 1.0f }, }; -/// @return the minimum of two integers +/// @return the minimum of two integers. B3_INLINE int b3MinInt( int a, int b ) { return a < b ? a : b; } -/// @return the maximum of two integers +/// @return the maximum of two integers. B3_INLINE int b3MaxInt( int a, int b ) { return a > b ? a : b; } -/// @return an integer clamped between a lower and upper bound +/// @return an integer clamped between a lower and upper bound. B3_INLINE int b3ClampInt( int a, int lower, int upper ) { return a < lower ? lower : ( upper < a ? upper : a ); } -/// Is this float valid (finite and not NaN) +/// @return is this float valid (finite and not NaN). B3_API bool b3IsValidFloat( float a ); -/// @return the absolute value of a float +/// @return the absolute value of a float. B3_INLINE float b3AbsFloat( float a ) { return a < 0 ? -a : a; } -/// @return the minimum of two floats +/// @return the minimum of two floats. B3_INLINE float b3MinFloat( float a, float b ) { return a < b ? a : b; } -/// @return the maximum of two floats +/// @return the maximum of two floats. B3_INLINE float b3MaxFloat( float a, float b ) { return a > b ? a : b; } -/// @return a float clamped between a lower and upper bound +/// @return a float clamped between a lower and upper bound. B3_INLINE float b3ClampFloat( float a, float lower, float upper ) { return a < lower ? lower : ( upper < a ? upper : a ); } -/// Interpolate a scalar +/// Interpolate a scalar. B3_INLINE float b3LerpFloat( float a, float b, float alpha ) { return ( 1.0f - alpha ) * a + alpha * b; @@ -158,86 +160,91 @@ B3_INLINE float b3LerpFloat( float a, float b, float alpha ) /// Compute an approximate arctangent in the range [-pi, pi] /// This is hand coded for cross-platform determinism. The atan2f /// function in the standard library is not cross-platform deterministic. -/// Accurate to around 0.0023 degrees +/// Accurate to around 0.0023 degrees. B3_API float b3Atan2( float y, float x ); /// Compute the cosine and sine of an angle in radians. Implemented /// for cross-platform determinism. B3_API b3CosSin b3ComputeCosSin( float radians ); +/// @deprecated B3_INLINE float b3Sin( float radians ) { b3CosSin cs = b3ComputeCosSin( radians ); return cs.sine; } +/// @deprecated B3_INLINE float b3Cos( float radians ) { b3CosSin cs = b3ComputeCosSin( radians ); return cs.cosine; } -/// Convert any angle into the range [-pi, pi] +/// Convert any angle into the range [-pi, pi]. B3_INLINE float b3UnwindAngle( float radians ) { // Assuming this is deterministic return remainderf( radians, 2.0f * B3_PI ); } -/// Vector addition +/// Vector addition. B3_INLINE b3Vec3 b3Add( b3Vec3 a, b3Vec3 b ) { return B3_LITERAL( b3Vec3 ){ a.x + b.x, a.y + b.y, a.z + b.z }; } -/// Vector subtraction +/// Vector subtraction. B3_INLINE b3Vec3 b3Sub( b3Vec3 a, b3Vec3 b ) { return B3_LITERAL( b3Vec3 ){ a.x - b.x, a.y - b.y, a.z - b.z }; } -/// Vector component-wise multiplication +/// Vector component-wise multiplication. B3_INLINE b3Vec3 b3Mul( b3Vec3 a, b3Vec3 b ) { return B3_LITERAL( b3Vec3 ){ a.x * b.x, a.y * b.y, a.z * b.z }; } -/// Vector negation +/// Vector negation. B3_INLINE b3Vec3 b3Neg( b3Vec3 a ) { return B3_LITERAL( b3Vec3 ){ -a.x, -a.y, -a.z }; } -/// Vector dot product +/// Vector dot product. B3_INLINE float b3Dot( b3Vec3 a, b3Vec3 b ) { return a.x * b.x + a.y * b.y + a.z * b.z; } -/// Vector length +/// Vector length. B3_INLINE float b3Length( b3Vec3 v ) { return sqrtf( b3Dot( v, v ) ); } -/// Vector length squared +/// Vector length squared. B3_INLINE float b3LengthSquared( b3Vec3 a ) { return a.x * a.x + a.y * a.y + a.z * a.z; } -B3_INLINE float b3Distance( b3Vec3 v1, b3Vec3 v2 ) +/// Distance between two points. +B3_INLINE float b3Distance( b3Vec3 a, b3Vec3 b ) { - b3Vec3 dv = { v2.x - v1.x, v2.y - v1.y, v2.z - v1.z }; + b3Vec3 dv = { b.x - a.x, b.y - a.y, b.z - a.z }; return b3Length( dv ); } -B3_INLINE float b3DistanceSquared( b3Vec3 v1, b3Vec3 v2 ) +/// Squared distance between two points. +B3_INLINE float b3DistanceSquared( b3Vec3 a, b3Vec3 b ) { - b3Vec3 dv = { v2.x - v1.x, v2.y - v1.y, v2.z - v1.z }; + b3Vec3 dv = { b.x - a.x, b.y - a.y, b.z - a.z }; return dv.x * dv.x + dv.y * dv.y + dv.z * dv.z; } +/// Normalize a vector. Returns a zero vector if the input vector is very small. B3_INLINE b3Vec3 b3Normalize( b3Vec3 a ) { float lengthSquared = a.x * a.x + a.y * a.y + a.z * a.z; @@ -252,37 +259,41 @@ B3_INLINE b3Vec3 b3Normalize( b3Vec3 a ) return B3_LITERAL( b3Vec3 ){ 0.0f, 0.0f, 0.0f }; } -B3_INLINE b3Vec3 b3GetLengthAndNormalize( float* length, b3Vec3 v ) +/// Normalize a vector and return the length. Returns a zero vector +/// if the input is very small. +B3_INLINE b3Vec3 b3GetLengthAndNormalize( float* length, b3Vec3 a ) { - *length = b3Length( v ); + *length = b3Length( a ); if ( *length < FLT_EPSILON ) { return b3Vec3_zero; } float invLength = 1.0f / *length; - b3Vec3 n = { invLength * v.x, invLength * v.y, invLength * v.z }; + b3Vec3 n = { invLength * a.x, invLength * a.y, invLength * a.z }; return n; } -B3_INLINE b3Vec3 b3Perp( b3Vec3 v ) +/// Get a unit vector that is perpendicular to the supplied vector. +B3_INLINE b3Vec3 b3Perp( b3Vec3 a ) { // Suppose vector a has all equal components and is a unit vector: a = (s, s, s) // Then 3*s*s = 1, s = sqrt(1/3) = 0.57735. This means that at least one component // of a unit vector must be greater or equal to 0.57735. b3Vec3 p; - if ( v.x < -0.5f || 0.5f < v.x ) + if ( a.x < -0.5f || 0.5f < a.x ) { - p = B3_LITERAL( b3Vec3 ){ v.y, -v.x, 0.0f }; + p = B3_LITERAL( b3Vec3 ){ a.y, -a.x, 0.0f }; } else { - p = B3_LITERAL( b3Vec3 ){ 0.0f, v.z, -v.y }; + p = B3_LITERAL( b3Vec3 ){ 0.0f, a.z, -a.y }; } return b3Normalize( p ); } +/// Is a vector normalized? In other words, does it have unit length? B3_INLINE bool b3IsNormalized( b3Vec3 a ) { float aa = b3Dot( a, a ); @@ -301,12 +312,13 @@ B3_INLINE b3Vec3 b3MulSub( b3Vec3 a, float s, b3Vec3 b ) return B3_LITERAL( b3Vec3 ){ a.x - s * b.x, a.y - s * b.y, a.z - s * b.z }; } -/// a + s * b +/// s * a B3_INLINE b3Vec3 b3MulSV( float s, b3Vec3 a ) { return B3_LITERAL( b3Vec3 ){ s * a.x, s * a.y, s * a.z }; } +/// https://en.wikipedia.org/wiki/Cross_product B3_INLINE b3Vec3 b3Cross( b3Vec3 a, b3Vec3 b ) { b3Vec3 c; @@ -316,6 +328,7 @@ B3_INLINE b3Vec3 b3Cross( b3Vec3 a, b3Vec3 b ) return c; } +/// Linearly interpolate between two vectors. B3_INLINE b3Vec3 b3Lerp( b3Vec3 a, b3Vec3 b, float alpha ) { B3_ASSERT( 0.0f <= alpha && alpha <= 1.0f ); @@ -328,6 +341,7 @@ B3_INLINE b3Vec3 b3Lerp( b3Vec3 a, b3Vec3 b, float alpha ) return c; } +/// Blend two vectors: s * a + t * b B3_INLINE b3Vec3 b3Blend2( float s, b3Vec3 a, float t, b3Vec3 b ) { b3Vec3 d = { @@ -338,16 +352,7 @@ B3_INLINE b3Vec3 b3Blend2( float s, b3Vec3 a, float t, b3Vec3 b ) return d; } -B3_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; -} - +/// Component-wise absolute value. B3_INLINE b3Vec3 b3Abs( b3Vec3 a ) { return B3_LITERAL( b3Vec3 ){ @@ -357,7 +362,7 @@ B3_INLINE b3Vec3 b3Abs( b3Vec3 a ) }; } -// -1 or 1 (1 if zero) +/// Component-wise -1 or 1 (1 if zero). B3_INLINE b3Vec3 b3Sign( b3Vec3 a ) { return B3_LITERAL( b3Vec3 ){ @@ -367,6 +372,7 @@ B3_INLINE b3Vec3 b3Sign( b3Vec3 a ) }; } +/// Component-wise minimum value. B3_INLINE b3Vec3 b3Min( b3Vec3 a, b3Vec3 b ) { return B3_LITERAL( b3Vec3 ){ @@ -376,6 +382,7 @@ B3_INLINE b3Vec3 b3Min( b3Vec3 a, b3Vec3 b ) }; } +/// Component-wise maximum value. B3_INLINE b3Vec3 b3Max( b3Vec3 a, b3Vec3 b ) { return B3_LITERAL( b3Vec3 ){ @@ -385,6 +392,7 @@ B3_INLINE b3Vec3 b3Max( b3Vec3 a, b3Vec3 b ) }; } +/// Component-wise clamped value. B3_INLINE b3Vec3 b3Clamp( b3Vec3 a, b3Vec3 lower, b3Vec3 upper ) { b3Vec3 b; @@ -394,8 +402,8 @@ B3_INLINE b3Vec3 b3Clamp( b3Vec3 a, b3Vec3 lower, b3Vec3 upper ) return b; } -// Create a safe scaling value for scaling collision. This allows -// negative scale, but keeps scale sufficiently far from zero. +/// Create a safe scaling value for scaling collision. This allows +/// negative scale, but keeps scale sufficiently far from zero. B3_INLINE b3Vec3 b3SafeScale( b3Vec3 a ) { b3Vec3 absScale = b3Abs( a ); @@ -404,13 +412,14 @@ B3_INLINE b3Vec3 b3SafeScale( b3Vec3 a ) return safeScale; } +/// Does the supplied quaternion have unit length? B3_INLINE bool b3IsNormalizedQuat( b3Quat q ) { float qq = q.v.x * q.v.x + q.v.y * q.v.y + q.v.z * q.v.z + q.s * q.s; return 1.0f - 20.0f * FLT_EPSILON < qq && qq < 1.0f + 20.0f * FLT_EPSILON; } -/// Rotate a vector +/// Rotate a vector. B3_INLINE b3Vec3 b3RotateVector( b3Quat q, b3Vec3 v ) { // v + 2 * cross(q.v, cross(q.v, v) + q.s * v) @@ -421,7 +430,7 @@ B3_INLINE b3Vec3 b3RotateVector( b3Quat q, b3Vec3 v ) return b3MulAdd( v, 2.0f, t3 ); } -/// Inverse rotate a vector +/// Inverse rotate a vector. B3_INLINE b3Vec3 b3InvRotateVector( b3Quat q, b3Vec3 v ) { // v + 2 * cross(q.v, cross(q.v, v) - q.s * v) @@ -432,11 +441,13 @@ B3_INLINE b3Vec3 b3InvRotateVector( b3Quat q, b3Vec3 v ) return b3MulAdd( v, 2.0f, t3 ); } +/// Compute dot product of two quaternions. Useful for polarity tests. B3_INLINE float b3DotQuat( b3Quat a, b3Quat b ) { return a.v.x * b.v.x + a.v.y * b.v.y + a.v.z * b.v.z + a.s * b.s; } +/// Multiply two quaternions. B3_INLINE b3Quat b3MulQuat( b3Quat q1, b3Quat q2 ) { b3Vec3 t1 = b3Cross( q1.v, q2.v ); @@ -446,7 +457,8 @@ B3_INLINE b3Quat b3MulQuat( b3Quat q1, b3Quat q2 ) return q; } -// inv(q1) * q2 +/// Compute a relative quaternion. +/// inv(q1) * q2 B3_INLINE b3Quat b3InvMulQuat( b3Quat q1, b3Quat q2 ) { b3Vec3 t1 = b3Cross( q2.v, q1.v ); @@ -456,16 +468,19 @@ B3_INLINE b3Quat b3InvMulQuat( b3Quat q1, b3Quat q2 ) return q; } +/// Quaternion conjugate (cheap inverse). B3_INLINE b3Quat b3Conjugate( b3Quat q ) { return B3_LITERAL( b3Quat ){ { -q.v.x, -q.v.y, -q.v.z }, q.s }; } +/// Component-wise quaternion negation. B3_INLINE b3Quat b3NegateQuat( b3Quat q ) { return B3_LITERAL( b3Quat ){ { -q.v.x, -q.v.y, -q.v.z }, -q.s }; } +/// Normalize a quaternion. B3_INLINE b3Quat b3NormalizeQuat( b3Quat q ) { float lengthSq = b3DotQuat( q, q ); @@ -479,6 +494,7 @@ B3_INLINE b3Quat b3NormalizeQuat( b3Quat q ) return b3Quat_identity; } +/// Make a quaternion that is equivalent to rotating around an axis by a specified angle. B3_INLINE b3Quat b3MakeQuatFromAxisAngle( b3Vec3 axis, float radians ) { B3_ASSERT( b3IsNormalized( axis ) ); @@ -487,6 +503,7 @@ B3_INLINE b3Quat b3MakeQuatFromAxisAngle( b3Vec3 axis, float radians ) return q; } +/// Get the axis and angle from a quaternion. Assumes the quaternion is normalized. B3_INLINE b3Vec3 b3GetAxisAngle( float* radians, b3Quat q ) { float length = sqrtf( q.v.x * q.v.x + q.v.y * q.v.y + q.v.z * q.v.z ); @@ -508,38 +525,16 @@ B3_INLINE float b3GetQuatAngle( b3Quat q ) return 2.0f * b3Atan2( length, q.s ); } -// Twist angle around the z-axis, used for twist limit and revolute angle limit -B3_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 -B3_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; -} - -/// Extract a quaternion from a rotation matrix +/// Extract a quaternion from a rotation matrix. B3_API b3Quat b3MakeQuatFromMatrix( const b3Matrix3* m ); -/// Find a quaternion that rotations one vector to another +/// Find a quaternion that rotates one vector to another. B3_API b3Quat b3ComputeQuatBetweenUnitVectors( b3Vec3 v1, b3Vec3 v2 ); /// Linearly interpolate and normalize between two quaternions B3_INLINE b3Quat b3NLerp( b3Quat q1, b3Quat q2, float alpha ) { - B3_ASSERT( 0.0f <= alpha && alpha <= 1.0f ); + B3_VALIDATE( 0.0f <= alpha && alpha <= 1.0f ); if ( b3DotQuat( q1, q2 ) < 0.0f ) { q1 = B3_LITERAL( b3Quat ){ { -q1.v.x, -q1.v.y, -q1.v.z }, -q1.s }; @@ -574,6 +569,7 @@ B3_FORCE_INLINE b3Transform b3InvMulTransforms( b3Transform a, b3Transform b ) return out; } +/// Get the inverse of a transform. B3_INLINE b3Transform b3InvertTransform( b3Transform t ) { b3Transform out; @@ -582,35 +578,26 @@ B3_INLINE b3Transform b3InvertTransform( b3Transform t ) return out; } -B3_INLINE b3Transform b3NormalizeTransform( b3Transform t ) -{ - b3Transform out; - out.p = t.p; - out.q = b3NormalizeQuat( t.q ); - return out; -} - +/// Transform a point. B3_INLINE b3Vec3 b3TransformPoint( b3Transform t, b3Vec3 v ) { b3Vec3 rv = b3RotateVector( t.q, v ); return b3Add( rv, t.p ); } +/// Inverse transform a point. B3_INLINE b3Vec3 b3InvTransformPoint( b3Transform t, b3Vec3 v ) { return b3InvRotateVector( t.q, b3Sub( v, t.p ) ); } -B3_INLINE b3Matrix3 b3MakeDiagonalMatrix( float a, float b, float c ) -{ - return B3_LITERAL( b3Matrix3 ){ { a, 0.0f, 0.0f }, { 0.0f, b, 0.0f }, { 0.0f, 0.0f, c } }; -} - +/// Compute the determinant of a 3-by-3 matrix. B3_INLINE float b3Det( b3Matrix3 m ) { return b3Dot( m.cx, b3Cross( m.cy, m.cz ) ); } +/// Multiply a matrix times a column vector. B3_INLINE b3Vec3 b3MulMV( b3Matrix3 m, b3Vec3 a ) { b3Vec3 b = { @@ -621,6 +608,7 @@ B3_INLINE b3Vec3 b3MulMV( b3Matrix3 m, b3Vec3 a ) return b; } +/// Negate a matrix. B3_INLINE b3Matrix3 b3NegateMat3( b3Matrix3 a ) { return B3_LITERAL( b3Matrix3 ){ @@ -630,6 +618,8 @@ B3_INLINE b3Matrix3 b3NegateMat3( b3Matrix3 a ) }; } +/// Matrix addition. +/// @return a + b B3_INLINE b3Matrix3 b3AddMM( b3Matrix3 a, b3Matrix3 b ) { return B3_LITERAL( b3Matrix3 ){ @@ -639,6 +629,8 @@ B3_INLINE b3Matrix3 b3AddMM( b3Matrix3 a, b3Matrix3 b ) }; } +/// Matrix subtraction. +/// @return a - b B3_INLINE b3Matrix3 b3SubMM( b3Matrix3 a, b3Matrix3 b ) { return B3_LITERAL( b3Matrix3 ){ @@ -648,6 +640,7 @@ B3_INLINE b3Matrix3 b3SubMM( b3Matrix3 a, b3Matrix3 b ) }; } +/// Multiply a matrix by a scalar, component-wise. B3_INLINE b3Matrix3 b3MulSM( float s, b3Matrix3 a ) { return B3_LITERAL( b3Matrix3 ){ @@ -657,6 +650,8 @@ B3_INLINE b3Matrix3 b3MulSM( float s, b3Matrix3 a ) }; } +/// Matrix multiplication. +/// @return a * b B3_INLINE b3Matrix3 b3MulMM( b3Matrix3 a, b3Matrix3 b ) { b3Matrix3 out; @@ -666,6 +661,7 @@ B3_INLINE b3Matrix3 b3MulMM( b3Matrix3 a, b3Matrix3 b ) return out; } +/// Matrix transpose. B3_INLINE b3Matrix3 b3Transpose( b3Matrix3 m ) { b3Matrix3 out; @@ -676,6 +672,7 @@ B3_INLINE b3Matrix3 b3Transpose( b3Matrix3 m ) return out; } +/// General matrix inverse. B3_INLINE b3Matrix3 b3InvertMatrix( b3Matrix3 m ) { float det = b3Det( m ); @@ -693,21 +690,23 @@ B3_INLINE b3Matrix3 b3InvertMatrix( b3Matrix3 m ) return b3Mat3_zero; } -B3_INLINE b3Vec3 b3Solve3( b3Matrix3 m, b3Vec3 x ) +/// Solve a matrix equation. +/// @return inv(m) * a +B3_INLINE b3Vec3 b3Solve3( b3Matrix3 m, b3Vec3 a ) { float det = b3Det( m ); if ( b3AbsFloat( det ) > 1000.0f * FLT_MIN ) { float invDet = 1.0f / det; - b3Matrix3 a; - a.cx = b3Cross( m.cy, m.cz ); - a.cy = b3Cross( m.cz, m.cx ); - a.cz = b3Cross( m.cx, m.cy ); + b3Matrix3 s; + s.cx = b3Cross( m.cy, m.cz ); + s.cy = b3Cross( m.cz, m.cx ); + s.cz = b3Cross( m.cx, m.cy ); b3Vec3 b = { - invDet * b3Dot( a.cx, x ), - invDet * b3Dot( a.cy, x ), - invDet * b3Dot( a.cz, x ), + invDet * b3Dot( s.cx, a ), + invDet * b3Dot( s.cy, a ), + invDet * b3Dot( s.cz, a ), }; return b; @@ -716,6 +715,7 @@ B3_INLINE b3Vec3 b3Solve3( b3Matrix3 m, b3Vec3 x ) return b3Vec3_zero; } +/// Invert a matrix. B3_INLINE b3Matrix3 b3InvertT( b3Matrix3 m ) { float det = b3Det( m ); @@ -732,32 +732,7 @@ B3_INLINE b3Matrix3 b3InvertT( b3Matrix3 m ) return b3Mat3_zero; } -B3_INLINE b3Matrix3 b3InvertSymmetric( b3Matrix3 m ) -{ - float det = b3Det( m ); - if ( b3AbsFloat( det ) > 1000.0f * FLT_MIN ) - { - float invDet = 1.0f / det; - b3Matrix3 out; - out.cx = b3MulSV( invDet, b3Cross( m.cy, m.cz ) ); - out.cy = b3MulSV( invDet, b3Cross( m.cz, m.cx ) ); - out.cz = b3MulSV( invDet, b3Cross( m.cx, m.cy ) ); - return out; - } - - return b3Mat3_zero; -} - -B3_INLINE b3Matrix3 b3Skew( b3Vec3 v ) -{ - b3Matrix3 out; - out.cx = B3_LITERAL( b3Vec3 ){ 0, v.z, -v.y }; - out.cy = B3_LITERAL( b3Vec3 ){ -v.z, 0, v.x }; - out.cz = B3_LITERAL( b3Vec3 ){ v.y, -v.x, 0 }; - - return out; -} - +/// Get the component-wise absolute value of a matrix. B3_INLINE b3Matrix3 b3AbsMatrix3( b3Matrix3 m ) { b3Matrix3 out; @@ -768,21 +743,9 @@ B3_INLINE b3Matrix3 b3AbsMatrix3( b3Matrix3 m ) return out; } -B3_INLINE float b3Trace( b3Matrix3 m ) -{ - return m.cx.x + m.cy.y + m.cz.z; -} - -B3_INLINE b3Matrix3 b3ScaleMatrix( float s, b3Matrix3 m ) -{ - return B3_LITERAL( b3Matrix3 ){ - b3MulSV( s, m.cx ), - b3MulSV( s, m.cy ), - b3MulSV( s, m.cz ), - }; -} - -// This force inline improves the performance of b3ShapeDistance +/// Make a matrix from a quaternion. This is useful if you need to +/// rotate many vectors. +/// The force inline improves the performance of b3ShapeDistance. B3_FORCE_INLINE b3Matrix3 b3MakeMatrixFromQuat( b3Quat q ) { float xx = q.v.x * q.v.x; @@ -802,9 +765,11 @@ B3_FORCE_INLINE b3Matrix3 b3MakeMatrixFromQuat( b3Quat q ) }; } -// https://en.wikipedia.org/wiki/Parallel_axis_theorem +/// Get the inertia tensor of an offset point. +/// https://en.wikipedia.org/wiki/Parallel_axis_theorem B3_API b3Matrix3 b3Steiner( float mass, b3Vec3 origin ); +/// Get the AABB of a point cloud. B3_INLINE b3AABB b3MakeAABB( const b3Vec3* points, int count, float radius ) { B3_ASSERT( count > 0 ); @@ -822,23 +787,7 @@ B3_INLINE b3AABB b3MakeAABB( const b3Vec3* points, int count, float radius ) return a; } -B3_INLINE b3AABB b3AABB_AddPoint( b3AABB a, b3Vec3 point ) -{ - return B3_LITERAL( b3AABB ){ b3Min( a.lowerBound, point ), b3Max( a.upperBound, point ) }; -} - -B3_INLINE bool b3AABB_ContainsPoint( b3AABB a, b3Vec3 point ) -{ - if ( a.lowerBound.x > point.x || point.x > a.upperBound.x ) - return false; - if ( a.lowerBound.y > point.y || point.y > a.upperBound.y ) - return false; - if ( a.lowerBound.z > point.z || point.z > a.upperBound.z ) - return false; - - return true; -} - +/// Does a fully contain b? B3_INLINE bool b3AABB_Contains( b3AABB a, b3AABB b ) { if ( a.lowerBound.x > b.lowerBound.x || b.upperBound.x > a.upperBound.x ) @@ -851,40 +800,46 @@ B3_INLINE bool b3AABB_Contains( b3AABB a, b3AABB b ) return true; } -B3_INLINE float b3AABB_Area( b3AABB bounds ) +/// Get the surface area of an axis-aligned bounding box. +B3_INLINE float b3AABB_Area( b3AABB a ) { - b3Vec3 delta = b3Sub( bounds.upperBound, bounds.lowerBound ); + b3Vec3 delta = b3Sub( a.upperBound, a.lowerBound ); return 2.0f * ( delta.x * delta.y + delta.y * delta.z + delta.z * delta.x ); } -B3_INLINE b3Vec3 b3AABB_Center( b3AABB bounds ) +/// Get the center of an axis-aligned bounding box. +B3_INLINE b3Vec3 b3AABB_Center( b3AABB a ) { - return b3MulSV( 0.5f, b3Add( bounds.upperBound, bounds.lowerBound ) ); + return b3MulSV( 0.5f, b3Add( a.upperBound, a.lowerBound ) ); } -B3_INLINE b3Vec3 b3AABB_Extents( b3AABB bounds ) +/// Get the extents (half-widths) of an axis-aligned bounding box. +B3_INLINE b3Vec3 b3AABB_Extents( b3AABB a ) { - return b3MulSV( 0.5f, b3Sub( bounds.upperBound, bounds.lowerBound ) ); + return b3MulSV( 0.5f, b3Sub( a.upperBound, a.lowerBound ) ); } -B3_INLINE b3AABB b3AABB_Union( b3AABB bounds1, b3AABB bounds2 ) +/// Get the union of two axis-aligned bounding boxes. +B3_INLINE b3AABB b3AABB_Union( b3AABB a, b3AABB b ) { b3AABB out; - out.lowerBound = b3Min( bounds1.lowerBound, bounds2.lowerBound ); - out.upperBound = b3Max( bounds1.upperBound, bounds2.upperBound ); + out.lowerBound = b3Min( a.lowerBound, b.lowerBound ); + out.upperBound = b3Max( a.upperBound, b.upperBound ); return out; } -B3_INLINE b3AABB b3AABB_Inflate( b3AABB bounds, float extension ) +/// Add uniform padding to an axis-aligned bounding box. +B3_INLINE b3AABB b3AABB_Inflate( b3AABB a, float extension ) { b3Vec3 radius = { extension, extension, extension }; b3AABB out; - out.lowerBound = b3Sub( bounds.lowerBound, radius ); - out.upperBound = b3Add( bounds.upperBound, radius ); + out.lowerBound = b3Sub( a.lowerBound, radius ); + out.upperBound = b3Add( a.upperBound, radius ); return out; } +/// Do two axis-aligned boxes overlap? B3_INLINE bool b3AABB_Overlaps( b3AABB a, b3AABB b ) { // No intersection if separated along one axis @@ -899,6 +854,9 @@ B3_INLINE bool b3AABB_Overlaps( b3AABB a, b3AABB b ) return true; } +/// Transform an axis-aligned bounding box. This can create a larger box +/// than if you recomputed the AABB of the original shape with the transform +/// applied. B3_INLINE b3AABB b3AABB_Transform( b3Transform transform, b3AABB a ) { b3Vec3 center = b3TransformPoint( transform, b3AABB_Center( a ) ); @@ -908,6 +866,7 @@ B3_INLINE b3AABB b3AABB_Transform( b3Transform transform, b3AABB a ) return out; } +/// Get the closest point on an axis-aligned bounding box. B3_INLINE b3Vec3 b3ClosestPointToAABB( b3Vec3 point, b3AABB a ) { return b3Clamp( point, a.lowerBound, a.upperBound ); @@ -937,7 +896,7 @@ B3_API bool b3IsSaneAABB( b3AABB a ); /// Is this a valid plane? Normal is a unit vector. Not Nan or infinity. B3_API bool b3IsValidPlane( b3Plane a ); -/**@}*/ +/**@}*/ // math /** * @defgroup math_cpp C++ Math @@ -949,6 +908,7 @@ B3_API bool b3IsValidPlane( b3Plane a ); #ifdef __cplusplus +/// Vector addition. B3_FORCE_INLINE b3Vec3& operator+=( b3Vec3& a, b3Vec3 b ) { a.x += b.x; @@ -957,6 +917,7 @@ B3_FORCE_INLINE b3Vec3& operator+=( b3Vec3& a, b3Vec3 b ) return a; } +/// Vector subtraction. B3_FORCE_INLINE b3Vec3& operator-=( b3Vec3& a, b3Vec3 b ) { a.x -= b.x; @@ -965,6 +926,7 @@ B3_FORCE_INLINE b3Vec3& operator-=( b3Vec3& a, b3Vec3 b ) return a; } +/// Vector scaling. B3_FORCE_INLINE b3Vec3& operator*=( b3Vec3& a, float s ) { a.x *= s; @@ -973,87 +935,42 @@ B3_FORCE_INLINE b3Vec3& operator*=( b3Vec3& a, float s ) return a; } +/// Vector negation. B3_FORCE_INLINE b3Vec3 operator-( b3Vec3 a ) { return { -a.x, -a.y, -a.z }; } +/// Vector scaling. B3_FORCE_INLINE b3Vec3 operator*( float s, b3Vec3 a ) { return { s * a.x, s * a.y, s * a.z }; } +/// Vector scaling. B3_FORCE_INLINE b3Vec3 operator*( b3Vec3 a, float s ) { return { s * a.x, s * a.y, s * a.z }; } +/// Component-wise vector multiplication. B3_FORCE_INLINE b3Vec3 operator*( b3Vec3 a, b3Vec3 b ) { return { a.x * b.x, a.y * b.y, a.z * b.z }; } +/// Vector addition. B3_FORCE_INLINE b3Vec3 operator+( b3Vec3 a, b3Vec3 b ) { return { a.x + b.x, a.y + b.y, a.z + b.z }; } +/// Vector subtraction. B3_FORCE_INLINE b3Vec3 operator-( b3Vec3 a, b3Vec3 b ) { return { a.x - b.x, a.y - b.y, a.z - b.z }; } -B3_INLINE b3Vec3 operator*( b3Matrix3 m, b3Vec3 v ) -{ - return b3MulMV( m, v ); -} - -B3_INLINE b3Matrix3& operator+=( b3Matrix3& a, b3Matrix3 b ) -{ - a = b3AddMM( a, b ); - return a; -} - -B3_INLINE b3Matrix3 operator*( b3Matrix3 a, b3Matrix3 b ) -{ - return b3MulMM( a, b ); -} - -B3_INLINE b3Matrix3 operator+( b3Matrix3 a, b3Matrix3 b ) -{ - return b3AddMM( a, b ); -} - -B3_INLINE b3Matrix3 operator-( b3Matrix3 a, b3Matrix3 b ) -{ - return b3SubMM( a, b ); -} - -B3_INLINE b3Matrix3 operator*( float s, b3Matrix3 a ) -{ - return b3MulSM( s, a ); -} - -B3_INLINE b3Quat operator+( b3Quat q1, b3Quat q2 ) -{ - return { q1.v + q2.v, q1.s + q2.s }; -} - -B3_INLINE b3Quat operator-( b3Quat q1, b3Quat q2 ) -{ - return { q1.v - q2.v, q1.s - q2.s }; -} - -B3_INLINE b3Quat operator*( float f, b3Quat q ) -{ - return { f * q.v, f * q.s }; -} - -B3_INLINE b3Quat operator*( b3Quat q, float f ) -{ - return { q.v * f, q.s * f }; -} - #endif -/**@}*/ +/**@}*/ // math_cpp diff --git a/include/box3d/types.h b/include/box3d/types.h index 45727b7..ef2f8a6 100644 --- a/include/box3d/types.h +++ b/include/box3d/types.h @@ -4,7 +4,6 @@ #pragma once #include "base.h" -#include "collision.h" #include "constants.h" #include "id.h" #include "math_functions.h" @@ -35,49 +34,104 @@ typedef void* b3EnqueueTaskCallback( b3TaskCallback* task, void* taskContext, vo /// @ingroup world typedef void b3FinishTaskCallback( void* userTask, void* userContext ); -// The user needs to be able to create debug draw shapes for multi-pass rendering to work efficiently. -// These user shapes are created and destroyed via callback so they can be bound to shape lifetime and scaling updates. typedef struct b3DebugShape b3DebugShape; + +/// The user needs to be able to create debug draw shapes for multi-pass rendering to work efficiently. +/// These user shapes are created and destroyed via callback so they can be bound to shape lifetime and scaling updates. +/// @ingroup debug_draw typedef void* b3CreateDebugShapeCallback( const b3DebugShape* debugShape, void* userContext ); typedef void b3DestroyDebugShapeCallback( void* userShape, void* userContext ); /// Optional friction mixing callback. This intentionally provides no context objects because this is called /// from a worker thread. /// @warning This function should not attempt to modify Box3D state or user application state. +/// @ingroup world typedef float b3FrictionCallback( float frictionA, uint64_t userMaterialIdA, float frictionB, uint64_t userMaterialIdB ); /// Optional restitution mixing callback. This intentionally provides no context objects because this is called /// from a worker thread. /// @warning This function should not attempt to modify Box3D state or user application state. +/// @ingroup world typedef float b3RestitutionCallback( float restitutionA, uint64_t userMaterialIdA, float restitutionB, uint64_t userMaterialIdB ); -/// Result from b3World_RayCastClosest +/// Prototype for a contact filter callback. +/// This is called when a contact pair is considered for collision. This allows you to +/// perform custom logic to prevent collision between shapes. This is only called if +/// one of the two shapes has custom filtering enabled. @see b3ShapeDef. +/// Notes: +/// - this function must be thread-safe +/// - this is only called if one of the two shapes has enabled custom filtering +/// - this is called only for awake dynamic bodies +/// Return false if you want to disable the collision +/// @warning Do not attempt to modify the world inside this callback /// @ingroup world -typedef struct b3RayResult -{ - b3ShapeId shapeId; - b3Vec3 point; - b3Vec3 normal; - uint64_t userMaterialId; - float fraction; - int triangleIndex; - int childIndex; - int nodeVisits; - int leafVisits; - bool hit; -} b3RayResult; +typedef bool b3CustomFilterFcn( b3ShapeId shapeIdA, b3ShapeId shapeIdB, void* context ); + +/// Prototype for a pre-solve callback. +/// This is called after a contact is updated. This allows you to inspect a +/// collision before it goes to the solver. +/// Notes: +/// - this function must be thread-safe +/// - this is only called if the shape has enabled pre-solve events +/// - this may be called for awake dynamic bodies and sensors +/// - this is not called for sensors +/// Return false if you want to disable the contact this step +/// This has limited information because it is used during CCD which does not have the +/// full contact manifold. +/// @warning Do not attempt to modify the world inside this callback +/// @ingroup world +typedef bool b3PreSolveFcn( b3ShapeId shapeIdA, b3ShapeId shapeIdB, b3Vec3 point, b3Vec3 normal, void* context ); + +/// Prototype callback for overlap queries. +/// Called for each shape found in the query. +/// @see b3World_OverlapAABB +/// @return false to terminate the query. +/// @ingroup world +typedef bool b3OverlapResultFcn( b3ShapeId shapeId, void* context ); + +/// Prototype callback for ray casts. +/// Called for each shape found in the query. You control how the ray cast +/// proceeds by returning a float: +/// return -1: ignore this shape and continue +/// return 0: terminate the ray cast +/// return fraction: clip the ray to this point +/// return 1: don't clip the ray and continue +/// @param shapeId the shape hit by the ray +/// @param point the point of initial intersection +/// @param normal the normal vector at the point of intersection +/// @param fraction the fraction along the ray at the point of intersection +/// @param userMaterialId the shape or triangle surface type +/// @param triangleIndex the triangle index for mesh or height field shapes or -1 for other shape types +/// @param childIndex the child shape index for compound shapes +/// @param context the user context +/// @return -1 to filter, 0 to terminate, fraction to clip the ray for closest hit, 1 to continue +/// @see b3World_CastRay +/// @ingroup world +typedef float b3CastResultFcn( b3ShapeId shapeId, b3Vec3 point, b3Vec3 normal, float fraction, uint64_t userMaterialId, + int triangleIndex, int childIndex, void* context ); /// Optional world capacities that can be use to avoid run-time allocations +/// @ingroup world typedef struct b3Capacity { + /// Number of expected static shapes. int staticShapeCount; + + /// Number of expected dynamic and kinematic shapes. int dynamicShapeCount; + + /// Number of expected static bodies. int staticBodyCount; + + /// Number of expected dynamic and kinematic bodies. int dynamicBodyCount; + + /// Number of expected contacts. int contactCount; } b3Capacity; /// World definition used to create a simulation world. Must be initialized using b3DefaultWorldDef. +/// @ingroup world typedef struct b3WorldDef { /// Gravity vector. Box3D has no up-vector defined. @@ -179,6 +233,7 @@ typedef enum b3BodyType } b3BodyType; /// Motion locks to restrict the body movement +/// @ingroup body typedef struct b3MotionLocks { /// Prevent translation along the x-axis @@ -234,7 +289,7 @@ typedef struct b3BodyDef /// Angular damping is used to reduce the angular velocity. The damping parameter /// can be larger than 1.0f but the damping effect becomes sensitive to the /// time step when the damping parameter is large. - /// Angular damping can be use slow down rotating bodies. + /// Angular damping can be used to slow down rotating bodies. float angularDamping; /// Scale the gravity applied to this body. Non-dimensional. @@ -334,23 +389,37 @@ typedef struct b3Filter /// @ingroup shape B3_API b3Filter b3DefaultFilter( void ); -/// The query filter is used to filter collisions between queries and shapes. For example, -/// you may want a ray-cast representing a projectile to hit players and the static environment -/// but not debris. +/// Material properties supported per triangle on meshes and height fields /// @ingroup shape -typedef struct b3QueryFilter +typedef struct b3SurfaceMaterial { - /// The collision category bits of this query. Normally you would just set one bit. - uint64_t categoryBits; + /// The Coulomb (dry) friction coefficient, usually in the range [0,1]. + float friction; - /// The collision mask bits. This states the shape categories that this - /// query would accept for collision. - uint64_t maskBits; -} b3QueryFilter; + /// The coefficient of restitution (bounce) usually in the range [0,1]. + /// https://en.wikipedia.org/wiki/Coefficient_of_restitution + float restitution; -/// Use this to initialize your query filter + /// The rolling resistance usually in the range [0,1]. This is only used for spheres and capsules. + float rollingResistance; + + /// The tangent velocity for conveyor belts. This is local to the shape and will be projected + /// onto the contact surface. + b3Vec3 tangentVelocity; + + /// User material identifier. This is passed with query results and to friction and restitution + /// combining functions. It is not used internally. + uint64_t userMaterialId; + + /// Custom debug draw color. Ignored if 0. The low 24 bits are RGB. The high byte may + /// carry a b3DebugMaterial preset, see b3MakeDebugColor. + /// @see b3HexColor + uint32_t customColor; +} b3SurfaceMaterial; + +/// Use this to initialize your surface material /// @ingroup shape -B3_API b3QueryFilter b3DefaultQueryFilter( void ); +B3_API b3SurfaceMaterial b3DefaultSurfaceMaterial( void ); /// Shape type /// @ingroup shape @@ -379,9 +448,10 @@ typedef enum b3ShapeType } b3ShapeType; /// Used to create a shape +/// @ingroup shape typedef struct b3ShapeDef { - /// Optional body name for debugging. Up to 31 characters (excluding null termination) + /// Optional body name for debugging. Up to B3_NAME_LENGTH characters (including null termination) const char* name; /// Use this to store application specific shape data. @@ -396,7 +466,7 @@ typedef struct b3ShapeDef /// The base surface material. Ignored for compound shapes. b3SurfaceMaterial baseMaterial; - /// The density, usually in kg/m^2. + /// The density, usually in kg/m^3. float density; /// Explosion scale for b3World_Explode. non-dimensional @@ -405,7 +475,7 @@ typedef struct b3ShapeDef /// Contact filtering data. b3Filter filter; - /// Enable custom filtering. Only one of the two shapes needs to enable custom filtering. See b2WorldDef. + /// Enable custom filtering. Only one of the two shapes needs to enable custom filtering. See b3WorldDef. bool enableCustomFiltering; /// A sensor shape generates overlap events but never generates a collision response. @@ -447,6 +517,7 @@ B3_API b3ShapeDef b3DefaultShapeDef( void ); //! @cond /// Profiling data. Times are in milliseconds. +/// @ingroup world typedef struct b3Profile { float step; @@ -475,6 +546,7 @@ typedef struct b3Profile } b3Profile; /// Counters that give details of the simulation size. +/// @ingroup world typedef struct b3Counters { int bodyCount; @@ -483,7 +555,7 @@ typedef struct b3Counters int jointCount; int islandCount; int stackUsed; - int arenaCapacity; // peak demand across all task arenas in bytes + int arenaCapacity; int staticTreeHeight; int treeHeight; int satCallCount; @@ -493,22 +565,21 @@ typedef struct b3Counters int colorCounts[24]; int manifoldCounts[B3_CONTACT_MANIFOLD_COUNT_BUCKETS]; - // Number of contacts touched by the collide pass (graph contacts + awake-set non-touching). + /// Number of contacts touched by the collide pass + /// graph contacts + awake-set non-touching int awakeContactCount; - // Number of contacts recycled in the most recent step. + /// Number of contacts recycled in the most recent step. int recycledContactCount; - // Maximum number of time of impact iterations + /// Maximum number of time of impact iterations int distanceIterations; int pushBackIterations; int rootIterations; } b3Counters; //! @endcond -/// Joint type enumeration -/// -/// This is useful because all joint types use b3JointId and sometimes you +/// Joint type enumeration. This is useful because all joint types use b3JointId and sometimes you /// want to get the type of a joint. /// @ingroup joint typedef enum b3JointType @@ -524,11 +595,11 @@ typedef enum b3JointType b3_wheelJoint, } b3JointType; -/// Base joint definition used by all joint types. -/// The local frames are measured from the body's origin -/// rather than the center of mass because: -/// 1. you might not know where the center of mass will be -/// 2. if you add/remove shapes from a body and recompute the mass, the joints will be broken +/// Base joint definition used by all joint types. The local frames are measured from the +/// body's origin rather than the center of mass because: +/// 1. You might not know where the center of mass will be. +/// 2. If you add/remove shapes from a body and recompute the mass, the joints will be broken. +/// @ingroup joint typedef struct b3JointDef { /// User data pointer @@ -568,7 +639,7 @@ typedef struct b3JointDef int internalValue; } b3JointDef; -/// Distance joint definition +/// Distance joint definition. /// Connects a point on body A with a point on body B by a segment. /// Useful for ropes and springs. /// @ingroup distance_joint @@ -587,7 +658,7 @@ typedef struct b3DistanceJointDef /// The lower spring force controls how much tension it can sustain float lowerSpringForce; - /// The upper spring force controls how much compression it an sustain + /// The upper spring force controls how much compression it can sustain float upperSpringForce; /// The spring linear stiffness Hertz, cycles per second @@ -662,7 +733,6 @@ typedef struct b3MotorJointDef B3_API b3MotorJointDef b3DefaultMotorJointDef( void ); /// A filter joint is used to disable collision between two specific bodies. -/// /// @ingroup filter_joint typedef struct b3FilterJointDef { @@ -674,18 +744,21 @@ typedef struct b3FilterJointDef /// @ingroup filter_joint B3_API b3FilterJointDef b3DefaultFilterJointDef( void ); -/// Parallel joint definition -/// Constrains the angle between axis z in body A and axis z in body B -/// using a spring. -/// Useful to keep a body upright. -/// @ingroup cone_joint +/// Parallel joint definition. Constrains the angle between axis z in body A and axis z in body B +/// using a spring. Useful to keep a body upright. +/// @ingroup parallel_joint typedef struct b3ParallelJointDef { /// Base joint definition b3JointDef base; + /// The spring stiffness Hertz, cycles per second float hertz; + + /// The spring damping ratio, non-dimensional float dampingRatio; + + /// The maximum spring torque, typically in newton-meters. float maxTorque; } b3ParallelJointDef; @@ -694,9 +767,9 @@ typedef struct b3ParallelJointDef /// @ingroup parallel_joint B3_API b3ParallelJointDef b3DefaultParallelJointDef( void ); -/// Prismatic joint definition -/// Body B may slide along the x-axis in local frame A. Body B cannot rotate relative to body A. -/// The joint translation is zero when the local frame origins coincide in world space. +/// Prismatic joint definition. Body B may slide along the x-axis in local frame A. +/// Body B cannot rotate relative to body A. The joint translation is zero when the +/// local frame origins coincide in world space. /// @ingroup prismatic_joint typedef struct b3PrismaticJointDef { @@ -736,46 +809,46 @@ typedef struct b3PrismaticJointDef } b3PrismaticJointDef; /// Use this to initialize your joint definition -/// @ingroupd prismatic_joint +/// @ingroup prismatic_joint B3_API b3PrismaticJointDef b3DefaultPrismaticJointDef( void ); -/// Revolute joint definition -/// A point on body B is fixed to a point on body A. Allows relative rotation about the z-axis. +/// Revolute joint definition. A point on body B is fixed to a point on body A. +/// Allows relative rotation about the z-axis. /// @ingroup revolute_joint typedef struct b3RevoluteJointDef { - /// Base joint definition + /// Base joint definition. b3JointDef base; /// The bodyB angle minus bodyA angle in the reference state (radians). /// This defines the zero angle for the joint limit. float targetAngle; - /// Enable a rotational spring on the revolute hinge axis + /// Enable a rotational spring on the revolute hinge axis. bool enableSpring; - /// The spring stiffness Hertz, cycles per second + /// The spring stiffness Hertz, cycles per second. float hertz; - /// The spring damping ratio, non-dimensional + /// The spring damping ratio, non-dimensional. float dampingRatio; - /// A flag to enable joint limits + /// A flag to enable joint limits. bool enableLimit; - /// The lower angle for the joint limit in radians + /// The lower angle for the joint limit in radians. float lowerAngle; - /// The upper angle for the joint limit in radians + /// The upper angle for the joint limit in radians. float upperAngle; - /// A flag to enable the joint motor + /// A flag to enable the joint motor. bool enableMotor; - /// The maximum motor torque, typically in newton-meters + /// The maximum motor torque, typically in newton-meters. float maxMotorTorque; - /// The desired motor speed in radians per second + /// The desired motor speed in radians per second. float motorSpeed; } b3RevoluteJointDef; @@ -783,8 +856,8 @@ typedef struct b3RevoluteJointDef /// @ingroup revolute_joint B3_API b3RevoluteJointDef b3DefaultRevoluteJointDef( void ); -/// Spherical joint definition -/// A point on body B is fixed to a point on body A. Allows rotation about the shared point. +/// Spherical joint definition. A point on body B is fixed to a point on body A. +/// Allows rotation about the shared point. /// @ingroup spherical_joint typedef struct b3SphericalJointDef { @@ -863,7 +936,7 @@ B3_API b3WeldJointDef b3DefaultWeldJointDef( void ); /// Wheel joint definition /// Body A is the chassis and body B is the wheel. /// The wheel rotates around the local z-axis in frame B. -/// The wheel translations along the local x-axis in frame A. +/// The wheel translates along the local x-axis in frame A. /// The wheel can optionally steer along the x-axis in frame A. /// @ingroup wheel_joint typedef struct b3WheelJointDef @@ -955,7 +1028,7 @@ typedef struct b3ExplosionDef B3_API b3ExplosionDef b3DefaultExplosionDef( void ); /** - * @defgroup events Events + * @defgroup event Events * World event types. * * Events are used to collect events that occur during the world time step. These events @@ -989,12 +1062,12 @@ typedef struct b3SensorEndTouchEvent { /// The id of the sensor shape /// @warning this shape may have been destroyed - /// @see b2Shape_IsValid + /// @see b3Shape_IsValid b3ShapeId sensorShapeId; /// The id of the shape that stopped touching the sensor shape /// @warning this shape may have been destroyed - /// @see b2Shape_IsValid + /// @see b3Shape_IsValid b3ShapeId visitorShapeId; } b3SensorEndTouchEvent; @@ -1025,8 +1098,8 @@ typedef struct b3ContactBeginTouchEvent /// Id of the second shape b3ShapeId shapeIdB; - /// The transient contact id. This contact maybe destroyed automatically when the world is modified or simulated. - /// Used b3Contact_IsValid before using this id. + /// The transient contact id. This contact may be destroyed automatically when the world is modified or simulated. + /// Use b3Contact_IsValid before using this id. b3ContactId contactId; } b3ContactBeginTouchEvent; @@ -1122,15 +1195,22 @@ typedef struct b3ContactEvents /// @note If sleeping is disabled all dynamic and kinematic bodies will trigger move events. typedef struct b3BodyMoveEvent { + /// The body user data. void* userData; + + /// The body transform. b3Transform transform; + + /// The body id. b3BodyId bodyId; + + /// Did the body fall asleep this time step? bool fellAsleep; } b3BodyMoveEvent; /// Body events are buffered in the world and are available /// as event arrays after the time step is complete. -/// Note: this date becomes invalid if bodies are destroyed +/// Note: this data becomes invalid if bodies are destroyed typedef struct b3BodyEvents { /// Array of move events @@ -1168,140 +1248,1460 @@ typedef struct b3JointEvents /// @see b3Shape_GetContactData() and b3Body_GetContactData() typedef struct b3ContactData { + /// The contact id. You may hold onto this to track a contact across time steps. + /// This id may become orphaned. Use b3Contact_IsValid before using it for other functions. b3ContactId contactId; + + /// The first shape id. b3ShapeId shapeIdA; + + /// The second shape id. b3ShapeId shapeIdB; + + /// The contact manifold. This points to internal data and may become invalid. Do not store + /// this pointer. const struct b3Manifold* manifolds; + + /// The number of contact manifolds. For mesh and height-field collision there can be multiple manifolds. int manifoldCount; } b3ContactData; -/**@}*/ +/**@}*/ // event -/// Prototype for a contact filter callback. -/// This is called when a contact pair is considered for collision. This allows you to -/// perform custom logic to prevent collision between shapes. This is only called if -/// one of the two shapes has custom filtering enabled. @see b3ShapeDef. -/// Notes: -/// - this function must be thread-safe -/// - this is only called if one of the two shapes has enabled custom filtering -/// - this is called only for awake dynamic bodies -/// Return false if you want to disable the collision -/// @warning Do not attempt to modify the world inside this callback -/// @ingroup world -typedef bool b3CustomFilterFcn( b3ShapeId shapeIdA, b3ShapeId shapeIdB, void* context ); +/** + * @defgroup query Query + * @brief Query types and functions + * + * Queries include ray casts, shapes casts, overlap, distance, and time of impact. + * @{ + */ -/// Prototype for a pre-solve callback. -/// This is called after a contact is updated. This allows you to inspect a -/// collision before it goes to the solver. -/// Notes: -/// - this function must be thread-safe -/// - this is only called if the shape has enabled pre-solve events -/// - this may be called for awake dynamic bodies and sensors -/// - this is not called for sensors -/// Return false if you want to disable the contact this step -/// This has limited information because it is used during CCD which does not have the -/// full contact manifold. -/// @warning Do not attempt to modify the world inside this callback -/// @ingroup world -typedef bool b3PreSolveFcn( b3ShapeId shapeIdA, b3ShapeId shapeIdB, b3Vec3 point, b3Vec3 normal, void* context ); +/// The query filter is used to filter collisions between queries and shapes. For example, +/// you may want a ray-cast representing a projectile to hit players and the static environment +/// but not debris. +typedef struct b3QueryFilter +{ + /// The collision category bits of this query. Normally you would just set one bit. + uint64_t categoryBits; -/// Prototype callback for overlap queries. -/// Called for each shape found in the query. -/// @see b3World_QueryAABB -/// @return false to terminate the query. -/// @ingroup world -typedef bool b3OverlapResultFcn( b3ShapeId shapeId, void* context ); + /// The collision mask bits. This states the shape categories that this + /// query would accept for collision. + uint64_t maskBits; +} b3QueryFilter; -/// Prototype callback for ray casts. -/// Called for each shape found in the query. You control how the ray cast -/// proceeds by returning a float: -/// return -1: ignore this shape and continue -/// return 0: terminate the ray cast -/// return fraction: clip the ray to this point -/// return 1: don't clip the ray and continue -/// @param shapeId the shape hit by the ray -/// @param point the point of initial intersection -/// @param normal the normal vector at the point of intersection -/// @param fraction the fraction along the ray at the point of intersection -/// @param userMaterialId the shape or triangle surface type -/// @param triangleIndex the triangle index for mesh or height field shapes or -1 for other shape types -/// @param childIndex the child shape index for compound shapes -/// @param context the user context -/// @return -1 to filter, 0 to terminate, fraction to clip the ray for closest hit, 1 to continue -/// @see b3World_CastRay -/// @ingroup world -typedef float b3CastResultFcn( b3ShapeId shapeId, b3Vec3 point, b3Vec3 normal, float fraction, uint64_t userMaterialId, - int triangleIndex, int childIndex, void* context ); +/// Use this to initialize your query filter +B3_API b3QueryFilter b3DefaultQueryFilter( void ); -// Used to collect collision planes for character movers. -// Return true to continue gathering planes. -typedef bool b3PlaneResultFcn( b3ShapeId shapeId, const b3PlaneResult* plane, int planeCount, void* context ); +/// Low level ray cast input data. +typedef struct b3RayCastInput +{ + /// Start point of the ray cast. + b3Vec3 origin; -// Used to filter shapes for shape casting character movers. -// Return true to accept the collision -typedef bool b3MoverFilterFcn( b3ShapeId shapeId, void* context ); + /// Translation of the ray cast. + /// end = start + translation. + b3Vec3 translation; + + /// The maximum fraction of the translation to consider, typically 1 + float maxFraction; +} b3RayCastInput; + +/// Result from b3World_RayCastClosest. +typedef struct b3RayResult +{ + /// The shape hit. + b3ShapeId shapeId; + + /// The world point of the hit. + b3Vec3 point; + + /// The world normal of the shape surface at the hit point. + b3Vec3 normal; + + /// The user material id at the hit point. This can be per triangle + /// if the shape is a mesh, height-field, or compound with child mesh. + uint64_t userMaterialId; + + /// The fraction of the input ray. + float fraction; + + /// The triangle index if the shape is a mesh, height-field, or compound with + /// child mesh. + int triangleIndex; + + /// The child index if the shape is a compound. + int childIndex; + + /// The number of BVH nodes visited. Diagnostic. + int nodeVisits; + + /// The number of BVH leaves visited. Diagnostic. + int leafVisits; + + /// Did the ray hit? If false, all other data is invalid. + bool hit; +} b3RayResult; + +/// A shape proxy is used by the GJK algorithm. It can represent a convex shape. +typedef struct b3ShapeProxy +{ + /// The point cloud. + const b3Vec3* points; + + /// The number of points. Do not exceed B3_MAX_SHAPE_CAST_POINTS. + int count; + + /// The external radius of the point cloud. + float radius; +} b3ShapeProxy; + +/// Low level shape cast input in generic form. This allows casting an arbitrary point +/// cloud wrap with a radius. For example, a sphere is a single point with a non-zero radius. +/// A capsule is two points with a non-zero radius. A box is four points with a zero radius. +typedef struct b3ShapeCastInput +{ + /// A generic query shape. + b3ShapeProxy proxy; + + /// The translation of the shape cast. + b3Vec3 translation; + + /// The maximum fraction of the translation to consider, typically 1. + float maxFraction; + + /// Allow shape cast to encroach when initially touching. This only works if the radius is greater than zero. + bool canEncroach; +} b3ShapeCastInput; + +/// Low level ray cast or shape-cast output data. +typedef struct b3CastOutput +{ + /// The surface normal at the hit point. + b3Vec3 normal; + + /// The surface hit point. + b3Vec3 point; + + /// The fraction of the input translation at collision. + float fraction; + + /// The number of iterations used. + int iterations; + + /// The index of the mesh or height field triangle hit. + int triangleIndex; + + /// The index of the compound child shape. + int childIndex; + + /// The material index. May be -1 for null. + int materialIndex; + + /// Did the cast hit? + bool hit; +} b3CastOutput; /// Body ray cast for ray casting a specific body with a specified transform. typedef struct b3BodyRayCastInput { + /// Start point of the ray cast b3Vec3 origin; + + /// Translation of the ray cast. + /// end = start + translation. b3Vec3 translation; + + /// The query filter bits. b3QueryFilter filter; + + /// The maximum fraction to consider along the ray. + /// end = start + fraction * translation float maxFraction; } b3BodyRayCastInput; /// Body shape cast for shape casting a specific body with a specified transform. typedef struct b3BodyShapeCastInput { + /// A generic query shape. b3ShapeProxy proxy; + + /// The translation of the shape cast. b3Vec3 translation; + + /// The query filter bits. b3QueryFilter filter; + + /// The maximum fraction to consider along the shape cast. + /// end = start + fraction * translation float maxFraction; + + /// Allow shape cast to encroach when initially touching. This only works if the radius is greater than zero. bool canEncroach; } b3BodyShapeCastInput; /// Body cast result for ray and shape casts. typedef struct b3BodyCastResult { + /// The shape hit. b3ShapeId shapeId; + + /// The world point on the shape surface. b3Vec3 point; + + /// The world normal vector on the shape surface. b3Vec3 normal; + + /// The fraction along the ray hit. + /// hit point = origin + fraction * translation float fraction; + + /// The triangle index if the shape is a mesh or height-field. int triangleIndex; + + /// The user material id at the hit point. This can be per triangle + /// if the shape is a mesh, height-field, or compound with child mesh. uint64_t userMaterialId; + + /// The number of iterations used. Diagnostic. int iterations; + + /// Did the cast hit? If false, all other fields are invalid. bool hit; } b3BodyCastResult; +/// Used to warm start the GJK simplex. If you call this function multiple times with nearby +/// transforms this might improve performance. Otherwise you can zero initialize this. +/// The distance cache must be initialized to zero on the first call. +/// Users should generally just zero initialize this structure for each call. +typedef struct b3SimplexCache +{ + /// Value use to compare length, area, volume of two simplexes. + float metric; + + // todo use an index of 0xFF as a sentinel and remove the count + /// The number of stored simplex points + uint16_t count; + + /// The cached simplex indices on shape A + uint8_t indexA[4]; + + /// The cached simplex indices on shape B + uint8_t indexB[4]; + +} b3SimplexCache; + +static const b3SimplexCache b3_emptyDistanceCache = B3_ZERO_INIT; + +/// Input parameters for b3ShapeCast +typedef struct b3ShapeCastPairInput +{ + b3ShapeProxy proxyA; ///< The proxy for shape A + b3ShapeProxy proxyB; ///< The proxy for shape B + b3Transform transformA; ///< The world transform for shape A + b3Transform transformB; ///< The world transform for shape B + b3Vec3 translationB; ///< The translation of shape B + float maxFraction; ///< The fraction of the translation to consider, typically 1 + bool canEncroach; ///< Allows shapes with a radius to move slightly closer if already touching +} b3ShapeCastPairInput; + +/// Input for b3ShapeDistance +typedef struct b3DistanceInput +{ + /// The proxy for shape A + b3ShapeProxy proxyA; + + /// The proxy for shape B + b3ShapeProxy proxyB; + + /// The world transform for shape A + b3Transform transformA; + + /// The world transform for shape B + b3Transform transformB; + + /// Should the proxy radius be considered? + bool useRadii; +} b3DistanceInput; + +/// Output for b3ShapeDistance +typedef struct b3DistanceOutput +{ + b3Vec3 pointA; ///< Closest point on shapeA + b3Vec3 pointB; ///< Closest point on shapeB + b3Vec3 normal; ///< Normal vector pointing from A to B + float distance; ///< The final distance, zero if overlapped + int iterations; ///< Number of GJK iterations used + int simplexCount; ///< The number of simplexes stored in the simplex array +} b3DistanceOutput; + +/// Simplex vertex for debugging the GJK algorithm +typedef struct b3SimplexVertex +{ + b3Vec3 wA; ///< support point in proxyA + b3Vec3 wB; ///< support point in proxyB + b3Vec3 w; ///< wB - wA + float a; ///< barycentric coordinates + int indexA; ///< wA index + int indexB; ///< wB index +} b3SimplexVertex; + +/// Simplex from the GJK algorithm +typedef struct b3Simplex +{ + b3SimplexVertex vertices[4]; ///< vertices + int count; ///< number of valid vertices +} b3Simplex; + +/// This describes the motion of a body/shape for TOI computation. Shapes are defined with respect to the body origin, +/// which may not coincide with the center of mass. However, to support dynamics we must interpolate the center of mass +/// position. +typedef struct b3Sweep +{ + b3Vec3 localCenter; ///< Local center of mass position + b3Vec3 c1; ///< Starting center of mass world position + b3Vec3 c2; ///< Ending center of mass world position + b3Quat q1; ///< Starting world rotation + b3Quat q2; ///< Ending world rotation +} b3Sweep; + +/// Time of impact input +typedef struct b3TOIInput +{ + b3ShapeProxy proxyA; ///< The proxy for shape A + b3ShapeProxy proxyB; ///< The proxy for shape B + b3Sweep sweepA; ///< The movement of shape A + b3Sweep sweepB; ///< The movement of shape B + float maxFraction; ///< Defines the sweep interval [0, tMax] +} b3TOIInput; + +/// Describes the TOI output +typedef enum b3TOIState +{ + b3_toiStateUnknown, + b3_toiStateFailed, + b3_toiStateOverlapped, + b3_toiStateHit, + b3_toiStateSeparated +} b3TOIState; + +/// Time of impact output +typedef struct b3TOIOutput +{ + /// The type of result + b3TOIState state; + + /// The hit point + b3Vec3 point; + + /// The hit normal + b3Vec3 normal; + + /// The sweep time of the collision + float fraction; + + /// The final distance + float distance; + + /// Number of outer iterations + int distanceIterations; + + /// Total number of push back iterations + int pushBackIterations; + + /// Total number of root iterations + int rootIterations; + + /// Indicates that the time of impact detected initial + /// overlap and used a fallback sphere as a last ditch effort + /// to prevent tunneling. + bool usedFallback; +} b3TOIOutput; + +/**@}*/ // query + +/** + * @defgroup tree Dynamic Tree + * The dynamic tree is a binary AABB tree to organize and query large numbers of geometric objects + * + * Box3D uses the dynamic tree internally to sort collision shapes into a binary bounding volume hierarchy. + * This data structure may have uses in games for organizing other geometry data and may be used independently + * of Box3D rigid body simulation. + * + * A dynamic AABB tree broad-phase, inspired by Nathanael Presson's btDbvt. + * A dynamic tree arranges data in a binary tree to accelerate + * queries such as AABB queries and ray casts. Leaf nodes are proxies + * with an AABB. These are used to hold a user collision object. + * Nodes are pooled and relocatable, so I use node indices rather than pointers. + * The dynamic tree is made available for advanced users that would like to use it to organize + * spatial game data besides rigid bodies. + * @{ + */ + +/// Flags for dynamic tree nodes. Internal usage. +typedef enum b3TreeNodeFlags +{ + b3_allocatedNode = 0x0001, + b3_enlargedNode = 0x0002, + b3_leafNode = 0x0004, +} b3TreeNodeFlags; + +/// Flags for dynamic tree node child indices. Internal usage. +typedef struct b3TreeNodeChildren +{ + int child1; ///< child node index 1 + int child2; ///< child node index 2 +} b3TreeNodeChildren; + +/// A node in the dynamic tree. This is private data placed here for performance reasons. +/// todo test padding to 64 bytes to avoid straddling cache lines +typedef struct b3TreeNode +{ + /// The node bounding box + b3AABB aabb; // 24 + + /// Category bits for collision filtering + uint64_t categoryBits; // 8 + + union + { + /// Children (internal node) + b3TreeNodeChildren children; + + /// User data (leaf node) + uint64_t userData; + }; // 8 + + union + { + /// The node parent index (allocated node) + int parent; + + /// The node freelist next index (free node) + int next; + }; // 4 + + /// Height of the node. Leaves have a height of 0. + uint16_t height; // 2 + + /// @see b3TreeNodeFlags + uint16_t flags; // 2 +} b3TreeNode; + +/// Dynamic tree version for compatibility testing. +#define B3_DYNAMIC_TREE_VERSION 0x8E867C390754064Bull + +/// The dynamic tree structure. This should be considered private data. +/// It is placed here for performance reasons. +typedef struct b3DynamicTree +{ + /// The dynamic tree version. Always the first field. Useful + /// if the tree is serialized. + uint64_t version; + + /// The tree nodes + b3TreeNode* nodes; + + /// The root index + int root; + + /// The number of nodes + int nodeCount; + + /// The allocated node space + int nodeCapacity; + + /// Number of proxies created + int proxyCount; + + /// Node free list + int freeList; + + /// Leaf indices for rebuild + int* leafIndices; + + /// Leaf bounding boxes for rebuild + b3AABB* leafBoxes; + + /// Leaf bounding box centers for rebuild + b3Vec3* leafCenters; + + /// Bins for sorting during rebuild + int* binIndices; + + /// Allocated space for rebuilding + int rebuildCapacity; +} b3DynamicTree; + +/// These are performance results returned by dynamic tree queries. +typedef struct b3TreeStats +{ + /// Number of internal nodes visited during the query + int nodeVisits; + + /// Number of leaf nodes visited during the query + int leafVisits; +} b3TreeStats; + +/// This function receives proxies found in the AABB query. +/// @return true if the query should continue +typedef bool b3TreeQueryCallbackFcn( int proxyId, uint64_t userData, void* context ); + +/// This function receives the minimum distance squared so far and proxy to check in the closest query. +/// @return minimum distance squared to user objects in the proxy +typedef float b3TreeQueryClosestCallbackFcn( float distanceSqrMin, int proxyId, uint64_t userData, void* context ); + +/// This function receives clipped ray cast input for a proxy. The function +/// returns the new ray fraction. +/// - return a value of 0 to terminate the ray cast +/// - return a value less than input->maxFraction to clip the ray +/// - return a value of input->maxFraction to continue the ray cast without clipping +typedef float b3TreeShapeCastCallbackFcn( const b3ShapeCastInput* input, int proxyId, uint64_t userData, void* context ); + +/// This function receives clipped ray cast input for a proxy. The function +/// returns the new ray fraction. +/// - return a value of 0 to terminate the ray cast +/// - return a value less than input->maxFraction to clip the ray +/// - return a value of input->maxFraction to continue the ray cast without clipping +typedef float b3TreeRayCastCallbackFcn( const b3RayCastInput* input, int proxyId, uint64_t userData, void* context ); + +/**@}*/ // tree + +/** + * @defgroup character Character Mover + * Character movement solver + * @{ + */ + +/// The plane between a character mover and a shape +typedef struct b3PlaneResult +{ + /// Outward pointing plane. + b3Plane plane; + + /// Closest point on the shape. May not be unique. + b3Vec3 point; + +} b3PlaneResult; + +/// These are collision planes that can be fed to b3SolvePlanes. Normally +/// this is assembled by the user from plane results in b3PlaneResult. +typedef struct b3CollisionPlane +{ + /// The collision plane between the mover and some shape. + b3Plane plane; + + /// Setting this to FLT_MAX makes the plane as rigid as possible. Lower values can + /// make the plane collision soft. Usually in meters. + float pushLimit; + + /// The push on the mover determined by b3SolvePlanes. Usually in meters. + float push; + + /// Indicates if b3ClipVector should clip against this plane. Should be false for soft collision. + bool clipVelocity; +} b3CollisionPlane; + +/// Result returned by b3SolvePlanes. +typedef struct b3PlaneSolverResult +{ + /// The final relative translation. + b3Vec3 delta; + + /// The number of iterations used by the plane solver. For diagnostics. + int iterationCount; +} b3PlaneSolverResult; + /// Body plane result for movers. typedef struct b3BodyPlaneResult { + /// The shape id on the body. b3ShapeId shapeId; + + /// The plane result. b3PlaneResult result; } b3BodyPlaneResult; -typedef struct b3ChildShape +/// Used to collect collision planes for character movers. +/// Return true to continue gathering planes. +typedef bool b3PlaneResultFcn( b3ShapeId shapeId, const b3PlaneResult* plane, int planeCount, void* context ); + +/// Used to filter shapes for shape casting character movers. +/// Return true to accept the collision +typedef bool b3MoverFilterFcn( b3ShapeId shapeId, void* context ); + +/**@}*/ // mover + +/** + * @defgroup geometry Geometry + * @brief Geometry types and algorithms + * + * Definitions of spheres, capsules, hulls, meshes, height fields, and compounds. + * @{ + */ + +/// This holds the mass data computed for a shape. +typedef struct b3MassData { + /// The shape mass + float mass; + + /// The local center of mass position. + b3Vec3 center; + + /// The inertia tensor. + b3Matrix3 inertia; // todo this should be central inertia +} b3MassData; + +/** + * @defgroup sphere Sphere + * @brief Sphere primitive + * @{ + */ + +/// A solid sphere +typedef struct b3Sphere +{ + /// The local center + b3Vec3 center; + + /// The radius + float radius; +} b3Sphere; + +/**@}*/ // sphere + +/** + * @defgroup capsule Capsule + * @brief Capsule primitive + * @{ + */ + +/// A solid capsule can be viewed as two hemispheres connected +/// by a rectangle. +typedef struct b3Capsule +{ + /// Local center of the first hemisphere + b3Vec3 center1; + + /// Local center of the second hemisphere + b3Vec3 center2; + + /// The radius of the hemispheres + float radius; +} b3Capsule; + +/**@}*/ // capsule + +/** + * @defgroup hull Convex Hull + * @brief Convex hull primitive + * @{ + */ + +/// A hull vertex. Identified by a half-edge with this +/// vertex as its tail. +typedef struct b3HullVertex +{ + /// A half-edge that has this vertex as the origin + /// Can be used along with edge twins and winding order + /// to traverse all the edges connected to this vertex. + uint8_t edge; +} b3HullVertex; + +/// Half-edge for hull data structure +typedef struct b3HullHalfEdge +{ + /// Next edge index CCW + uint8_t next; + + /// Twin edge index + uint8_t twin; + + /// index of origin vertex and point + uint8_t origin; + + /// Face to the left of this edge + uint8_t face; +} b3HullHalfEdge; + +/// A hull face. Hulls use a half-edge data structure, so a face +/// can be determined from a single half-edge index. +typedef struct b3HullFace +{ + /// An arbitrary half-edge on this face + uint8_t edge; +} b3HullFace; + +/// 64-bit hull version. Useful for validating serialized data. +#define B3_HULL_VERSION 0x8F5034CF987D4FD9ull + +/// A convex hull. +/// @note This data structure has data hanging off the end and cannot be directly copied. +typedef struct b3Hull +{ + /// Version must be first and match B3_HULL_VERSION + uint64_t version; + + /// The total number of bytes for this hull. + int byteCount; + + /// Hash of this hull (this field is zero when the hash is computed). + uint32_t hash; + + /// Axis-aligned box in local space. + b3AABB aabb; + + /// Surface area, typically in squared meters. + float surfaceArea; + + /// Volume, typically in m^3. + float volume; + + /// The radius of the largest sphere at the center. + float innerRadius; + + /// The local centroid + b3Vec3 center; + + /// The inertia tensor about the centroid. + b3Matrix3 centralInertia; + + /// The vertex count. + int vertexCount; + + /// Offset of the vertex array in bytes from the struct address. + int vertexOffset; + + /// Offset of the point array in bytes from the struct address. + int pointOffset; + + /// This is the half-edge count (double the edge count) + int edgeCount; + + /// Offset of the edge array in bytes from the struct address. + int edgeOffset; + + /// The face count. Hulls faces are convex polygons. + int faceCount; + + /// Offset of the face array in bytes from the struct address. + int faceOffset; + + /// Offset of the face plane array in bytes from the struct address. + int planeOffset; +} b3Hull; + +/// Efficient box hull +typedef struct b3BoxHull +{ + /// The embedded hull. So the offsets index into the arrays that follow. + b3Hull base; + b3HullVertex boxVertices[8]; ///< Box vertices. + b3Vec3 boxPoints[8]; ///< Box points. + b3HullHalfEdge boxEdges[24]; ///< Box half-edges. + b3HullFace boxFaces[6]; ///< Box faces. + b3Plane boxPlanes[6]; ///< Box face planes. +} b3BoxHull; + +/**@}*/ // hull + +/** + * @defgroup mesh Triangle Mesh + * @brief Triangle mesh collision shape + * @{ + */ + +/// This is used to create a re-usable collision mesh +typedef struct b3MeshDef +{ + /// Triangle vertices + b3Vec3* vertices; + + /// Triangle vertex indices. 3 for each triangle. + int32_t* indices; + + /// Triangle material index. 1 per triangle. Indexes into b3ShapeDef::materials. + /// This allows different run-time material data to be associated with different + /// instances of this mesh. + uint8_t* materialIndices; + + /// Tolerance for vertex welding in length units. + float weldTolerance; + + /// The vertex count. Must be 3 or more. + int vertexCount; + + /// The triangle count. Must be 1 or more. + int triangleCount; + + /// Optionally weld nearby vertices. + bool weldVertices; + + /// Use the median split instead of SAH to speed up mesh creation. Good + /// for meshes that are structured like a grid. + bool useMedianSplit; + + /// Compute triangle adjacency information using shared edges + bool identifyEdges; +} b3MeshDef; + +/// 64-bit mesh version. Useful for validating serialized data. +#define B3_MESH_VERSION 0x4A1E7B2C8D5F3091ull + +/// Triangle mesh edge flags. +typedef enum b3MeshEdgeFlags +{ + b3_concaveEdge1 = 0x01, + b3_concaveEdge2 = 0x02, + b3_concaveEdge3 = 0x04, + + b3_inverseConcaveEdge1 = 0x10, + b3_inverseConcaveEdge2 = 0x20, + b3_inverseConcaveEdge3 = 0x40, + + b3_allConcaveEdges = b3_concaveEdge1 | b3_concaveEdge2 | b3_concaveEdge3, + + b3_flatEdge1 = b3_concaveEdge1 | b3_inverseConcaveEdge1, + b3_flatEdge2 = b3_concaveEdge2 | b3_inverseConcaveEdge2, + b3_flatEdge3 = b3_concaveEdge3 | b3_inverseConcaveEdge3, + + b3_allFlatEdges = b3_flatEdge1 | b3_flatEdge2 | b3_flatEdge3, + +} b3MeshEdgeFlags; + +/// A mesh triangle. +typedef struct b3MeshTriangle +{ + int32_t index1; ///< Index of vertex 1. + int32_t index2; ///< Index of vertex 2. + int32_t index3; ///< Index of vertex 3. +} b3MeshTriangle; + +/// A mesh BVH node. +typedef struct b3MeshNode +{ + /// The lower bound of the node AABB. Strategic placement for SIMD. + b3Vec3 lowerBound; + + /// Anonymous union. union { - b3Capsule capsule; - const b3Hull* hull; - b3Mesh mesh; - b3Sphere sphere; - }; + /// Internal node + struct + { + /// Split axis. 0, 1, or 2. + uint32_t axis : 2; + /// Offset of the second child node. + uint32_t childOffset : 30; + } asNode; + /// Leaf node + struct + { + /// Aligned with axis above and has value of 3 if this is a leaf. + uint32_t type : 2; + + /// The number of triangles for this leaf node. + uint32_t triangleCount : 30; + } asLeaf; + } data; + + /// The upper bound of the node AABB. Strategic placement for SIMD. + b3Vec3 upperBound; + + /// The index of the leaf triangles. + uint32_t triangleOffset; +} b3MeshNode; + +/// This is a sorted triangle collision bounding volume hierarchy. +/// @note This struct has data hanging off the end and cannot be directly copied. +typedef struct b3MeshData +{ + /// Version must be first. + uint64_t version; + + /// The total number of bytes for this mesh. + int byteCount; + + /// Hash of this mesh (this field is zero when the hash is computed) + uint32_t hash; + + /// Local axis-aligned box. + b3AABB bounds; + + /// Combined surface area of all triangles. Single-sided. + float surfaceArea; + + /// The height of the bounding volume hierarchy. + int treeHeight; + + /// The number of degenerate triangles. Diagnostic. + int degenerateCount; + + /// Offset of the node array in bytes from the struct address. + int nodeOffset; + + /// The number of BVH nodes. + int nodeCount; + + /// Offset of the vertex array in bytes from the struct address. + int vertexOffset; + + /// The number of vertices. + int vertexCount; + + /// Offset of the triangle array in bytes from the struct address. + int triangleOffset; + + /// The number of triangles. + int triangleCount; + + /// Offset of the material array in bytes from the struct address. + int materialOffset; + + /// The number of materials. + int materialCount; + + /// Offset of the triangle flag array in bytes from the struct address. + int flagsOffset; +} b3MeshData; + +/// This allows mesh data to be re-used with different scales. +typedef struct b3Mesh +{ + /// Immutable pointer to the mesh data. + const b3MeshData* data; + + /// This scale may be non-uniform and have negative components. However, + /// no component may be very small in magnitude. + b3Vec3 scale; +} b3Mesh; + +/**@}*/ // mesh + +/** + * @defgroup height_field Height Field + * @brief Height field collision shape + * @{ + */ + +/// Data used to create a height field +typedef struct b3HeightFieldDef +{ + /// Grid point heights + /// count = countX * countZ + float* heights; + + /// Grid cell material + /// A value of 0xFF is reserved for holes + /// count = (countX - 1) * (countZ - 1) + uint8_t* materialIndices; + + /// The height field scale. All components must be positive values. + b3Vec3 scale; + + /// The number of grid lines along the x-axis. + int countX; + + /// The number of grid lines along the z-axis. + int countZ; + + /// Global minimum and maximum heights used for quantization. This is important + /// if you want height fields to be placed next to each other and line up exactly. + /// In that case, both height fields should use the same minimum and maximum heights. + /// All height values are clamped to this range. + /// These values are in unscaled space. + float globalMinimumHeight; + + /// The maximum. + float globalMaximumHeight; + + /// Use clock-wise winding. This effectively inverts the height-field along the y-axis. + bool clockwiseWinding; +} b3HeightFieldDef; + +/// This material index is used to designate holes in a height field. +#define B3_HEIGHT_FIELD_HOLE 0xFF + +/// 64-bit height-field version. Useful for validating serialized data. +#define B3_HEIGHT_FIELD_VERSION 0xB6E83F1D947A28C5ull + +/// A height field with compressed storage. +typedef struct b3HeightField +{ + /// Version must be first + uint64_t version; + + /// The compressed height values. + uint16_t* compressedHeights; + + /// Material indices, one for each cell. + uint8_t* materialIndices; + + /// Flags per cell. + uint8_t* flags; + + /// Hash of this height field (this field is zero when the hash is computed). + /// Pointer values above are skipped; the bulk arrays they reference and the + /// scalar block below are folded in at construction time. + uint32_t hash; + + /// The local axis-aligned bounding box. + b3AABB aabb; + + /// The minimum y value. + float minHeight; + + /// The maximum y value + float maxHeight; + + /// The quantization scale. + float heightScale; + + /// The overall scale. + b3Vec3 scale; + + /// The number of grid columns along the local x-axis. + int columnCount; + + /// The number of grid rows along the local z-axis. + int rowCount; + + /// Triangle winding. + bool clockwise; +} b3HeightField; + +/**@}*/ // height_field + +/** + * @defgroup compound Compound + * @brief Compound collision shape + * @{ + */ + +/// Definition for a capsule in a compound shape. +typedef struct b3CompoundCapsuleDef +{ + /// Local capsule. + b3Capsule capsule; + + /// Material properties. + b3SurfaceMaterial material; +} b3CompoundCapsuleDef; + +/// Definition for a convex hull in a compound shape. +typedef struct b3CompoundHullDef +{ + /// Shared hull. + const b3Hull* hull; + + /// Transform of the shared hull into compound local space. b3Transform transform; - // Index 0 is used for convex shapes. - // todo limit to 64K? + /// Material properties. + b3SurfaceMaterial material; +} b3CompoundHullDef; + +/// Definition for a triangle mesh in a compound shape. +typedef struct b3CompoundMeshDef +{ + /// Shared mesh. + const b3MeshData* meshData; + + /// Transform of the shared mesh into compound local space. + b3Transform transform; + + /// Local space non-uniform mesh scale. May have negative components. + b3Vec3 scale; + + /// Material properties. + /// This array must line up with the material indices on the triangles. + const b3SurfaceMaterial* materials; + + /// Number of materials. + int materialCount; +} b3CompoundMeshDef; + +/// Definition for a sphere in a compound shape. +typedef struct b3CompoundSphereDef +{ + /// Local sphere. + b3Sphere sphere; + + /// Material properties. + b3SurfaceMaterial material; +} b3CompoundSphereDef; + +/// Definition for creating a compound shape. All this data is fully cloned +/// into the run-time compound shape. +typedef struct b3CompoundDef +{ + /// Capsule instances. + b3CompoundCapsuleDef* capsules; + + /// Number of capsules. + int capsuleCount; + + /// Hulls instances. + b3CompoundHullDef* hulls; + + /// Number of hull instances. + int hullCount; + + /// Mesh instances. + b3CompoundMeshDef* meshes; + + /// Number of mesh instances. + int meshCount; + + /// Sphere instances. + b3CompoundSphereDef* spheres; + + /// Number of spheres. + int sphereCount; +} b3CompoundDef; + +/// The compound version depends on the tree, mesh, and hull versions. +#define B3_COMPOUND_VERSION ( 0x902AC5D34D9BD452ull ^ B3_DYNAMIC_TREE_VERSION ^ B3_MESH_VERSION ^ B3_HULL_VERSION ) + +/// Meshes used in compounds have limited space for materials. If you have +/// a mesh with many materials, you can use it outside of the compound. +#define B3_MAX_COMPOUND_MESH_MATERIALS 4 + +/// The runtime data for a compound shape. This is a potentially large yet highly optimized +/// data structure. It can contain thousands of child shapes, yet at runtime it populates +/// into the world as a single shape in the runtime broad-phase. +/// This data structure has data living off the end and must be accessed using offsets. +/// Accessors are provided for user relevant data. +typedef struct b3Compound +{ + /// The compound version is always first. + uint64_t version; + + /// The total number of bytes for this compound. + int byteCount; + + /// Offset of the tree node array in bytes from the struct address. + int nodeOffset; + + /// Immutable dynamic tree. The tree node pointer must be fixed up using the node offset + b3DynamicTree tree; + + /// Offset of the material array in bytes from the struct address. + int materialOffset; + + /// The number of materials. + int materialCount; + + /// Offset of the capsule array in bytes from the struct address. + int capsuleOffset; + + /// The number of capsules. + int capsuleCount; + + /// Offset of the hull instance array in bytes from the struct address. + int hullOffset; + + /// The number of hull instances. + int hullCount; + + /// The number of unique hulls. Diagnostic. + int sharedHullCount; + + /// Offset of the mesh instance array in bytes from the struct address. + int meshOffset; + + /// The number of mesh instances. + int meshCount; + + /// The number of unique meshes. Diagnostic. + int sharedMeshCount; + + /// Offset of the sphere array in bytes from the struct address. + int sphereOffset; + + /// The number of spheres. + int sphereCount; +} b3Compound; + +/// A capsule that lives in a compound. +typedef struct b3CompoundCapsule +{ + /// Local capsule. + b3Capsule capsule; + + /// Index to a shared material. + int materialIndex; +} b3CompoundCapsule; + +/// A hull that lives in a compound. +typedef struct b3CompoundHull +{ + /// Pointer to the unique shared hull. + const b3Hull* hull; + + /// The transform of this hull instance. + b3Transform transform; + + /// Index to a shared material. + int materialIndex; +} b3CompoundHull; + +/// A mesh with non-uniform scale that lives in a compound. +typedef struct b3CompoundMesh +{ + /// Pointer to the unique shared mesh. + const b3MeshData* meshData; + + /// The transform of this mesh instance. + b3Transform transform; + + /// Non-uniform scale of this mesh instance. + b3Vec3 scale; + + /// This is used to access the surface material from b3GetCompoundMaterials. + /// Requires an extra level of indirection. The triangle material index + /// is clamped to B3_MAX_COMPOUND_MESH_MATERIALS. + /// materialIndex = materialIndices[triangle->materialIndex] int materialIndices[B3_MAX_COMPOUND_MESH_MATERIALS]; +} b3CompoundMesh; + +/// A sphere that lives in a compound. +typedef struct b3CompoundSphere +{ + /// Local sphere. + b3Sphere sphere; + + /// Index to a shared material. + int materialIndex; +} b3CompoundSphere; + +/// Child shape of a compound +typedef struct b3ChildShape +{ + /// Tagged union. + union + { + b3Capsule capsule; ///< Capsule. + const b3Hull* hull; ///< Hull. + b3Mesh mesh; ///< Mesh. + b3Sphere sphere; ///< Sphere. + }; + + /// Transform of the shape into compound local space. + b3Transform transform; + + /// Material indices. Index 0 is used for convex shapes. + /// todo limit to 64K? + int materialIndices[B3_MAX_COMPOUND_MESH_MATERIALS]; + + /// The shape type (union tag). b3ShapeType type; } b3ChildShape; +/// Callback for compound overlap queries. typedef bool b3CompoundQueryFcn( const b3Compound* compound, int childIndex, void* context ); -B3_API b3ChildShape b3GetCompoundChild( const b3Compound* compound, int childIndex ); -B3_API void b3QueryCompound( const b3Compound* compound, b3AABB aabb, b3CompoundQueryFcn* fcn, void* context ); +/**@}*/ // compound + +/**@}*/ // geometry + +/** + * @defgroup collision Shape Collision + * Collide pairs of shapes. + * @{ + */ + +/// A manifold point is a contact point belonging to a contact manifold. +/// It holds details related to the geometry and dynamics of the contact points. +/// Box3D uses speculative collision so some contact points may be separated. +/// You may use the maxNormalImpulse to determine if there was an interaction during +/// the time step. +typedef struct b3ManifoldPoint +{ + /// Location of the contact point relative to the bodyA center of mass in world space. + b3Vec3 anchorA; + + /// Location of the contact point relative to the bodyB center of mass in world space. + b3Vec3 anchorB; + + /// The separation of the contact point, negative if penetrating + float separation; + + /// Cached separation used for contact recycling + float baseSeparation; + + /// The impulse along the manifold normal vector. Since Box3D uses sub-stepping, this is + /// result from the final sub-step. + float normalImpulse; + + /// The total normal impulse applied during sub-stepping. This is important + /// to identify speculative contact points that had an interaction in the time step. + float totalNormalImpulse; + + /// Relative normal velocity pre-solve. Used for hit events. If the normal impulse is + /// zero then there was no hit. Negative means shapes are approaching. + float normalVelocity; + + /// Local point for matching + /// Uniquely identifies a contact point between two shapes + uint32_t featureId; + + /// Triangle index if one of the shapes is a mesh or height field + int triangleIndex; + + /// Did this contact point exist in the previous step? + bool persisted; +} b3ManifoldPoint; + +/// A contact manifold describes the contact points between colliding shapes. +/// @note Box3D uses speculative collision so some contact points may be separated. +typedef struct b3Manifold +{ + /// The manifold points. There may be 1 to 4 valid points. + b3ManifoldPoint points[B3_MAX_MANIFOLD_POINTS]; + + /// The unit normal vector in world space, points from shape A to shape B + b3Vec3 normal; + + /// Central friction angular impulse (applied about the normal) + float twistImpulse; + + /// Central friction linear impulse + b3Vec3 frictionImpulse; + + /// Rolling resistance angular impulse + b3Vec3 rollingImpulse; + + /// The number of contact points, will be 0 to 4 + int pointCount; + +} b3Manifold; + +/// Cached separating axis feature. +typedef enum +{ + b3_invalidAxis = 0, + b3_backsideAxis, + b3_faceAxisA, + b3_faceAxisB, + b3_edgePairAxis, + b3_closestPointsAxis, + + /// These are for testing + b3_manualFaceAxisA, + b3_manualFaceAxisB, + b3_manualEdgePairAxis, +} b3SeparatingFeature; + +/// Cached triangle feature. +typedef enum +{ + b3_featureNone = 0, + b3_featureTriangleFace, + b3_featureHullFace, + /// v1-v2 + b3_featureEdge1, + /// v2-v3 + b3_featureEdge2, + /// v3-v1 + b3_featureEdge3, + b3_featureVertex1, + b3_featureVertex2, + b3_featureVertex3 +} b3TriangleFeature; + +/// Separating axis test cache. Provides temporal acceleration of collision routines. +typedef struct +{ + /// The separation when the cache is populated. Negative for overlap. + float separation; + + /// b3SeparatingFeature. + uint8_t type; + + /// Index of the feature on shape A. + uint8_t indexA; + + /// Index of the feature on shape B. + uint8_t indexB; + + /// Was the cache re-used? + uint8_t hit; +} b3SATCache; + +/// Contact points are always the result of two edges intersecting. +/// It can be two edges of the same shape, which is just a shape vertex. +/// Or a contact point can be the result of two edges crossing from different shapes. +/// This is designed to support hull versus hull, but it is adapted to work +/// with all shape types. The feature pair is used to identify contact points +/// for temporal coherence and warm starting. +typedef struct b3FeaturePair +{ + /// Incoming type (either edge on shape A or shape B) + uint8_t owner1; + /// Incoming edge index (into associated shape array) + uint8_t index1; + /// Outgoing type (either edge on shape A or shape B) + uint8_t owner2; + /// Outgoing edge index (into associated shape array) + uint8_t index2; +} b3FeaturePair; + +/// A local manifold point and normal in frame A. +typedef struct b3LocalManifoldPoint +{ + /// Local point in frame A. + b3Vec3 point; + + /// The contact point separation. Negative for overlap. + float separation; + + /// The feature pair for this point. + b3FeaturePair pair; + + /// The triangle index when collide with a mesh or height-field. + int triangleIndex; +} b3LocalManifoldPoint; + +/// A local manifold with no dynamic information. Used by b3Collide functions. +typedef struct b3LocalManifold +{ + /// Local normal in frame A. + b3Vec3 normal; + + /// The triangle normal. + b3Vec3 triangleNormal; + + /// The manifold points. From a point buffer. + b3LocalManifoldPoint* points; + + /// The number of manifold points. Only bounded by the buffer capacity. + int pointCount; + + /// The index of the triangle. + int triangleIndex; + + int i1; ///< Vertex 1 index. + int i2; ///< Vertex 2 index. + int i3; ///< Vertex 3 index. + + /// The squared distance of a sphere from a triangle. For ghost collision reduction. + float squaredDistance; + + /// The triangle feature involved. + b3TriangleFeature feature; + + /// b3MeshEdgeFlags. + int triangleFlags; +} b3LocalManifold; + +/**@}*/ // collision + +/** + * @defgroup debug_draw Debug Draw + * @{ + */ /// These colors are used for debug draw and mostly match the named SVG colors. /// See https://www.rapidtables.com/web/color/index.html @@ -1482,26 +2882,32 @@ B3_INLINE uint32_t b3MakeDebugColor( b3HexColor rgb, b3DebugMaterial material ) /// (B3_GRAPH_COLOR_COUNT - 1) is the overflow color. B3_API b3HexColor b3GetGraphColor( int index ); -// This is sent to the user for debug shape creation. The user should know the type in case they have -// custom sphere or capsule rendering. +/// This is sent to the user for debug shape creation. The user should know the type in case they have +/// custom sphere or capsule rendering. typedef struct b3DebugShape { + /// Shape id. b3ShapeId shapeId; + + /// Shape type. b3ShapeType type; + + /// Tagged union. union { - const b3Capsule* capsule; - const b3Compound* compound; - const b3HeightField* heightField; - const b3Hull* hull; - const b3Mesh* mesh; - const b3Sphere* sphere; + const b3Capsule* capsule; ///< Capsule shape. + const b3Compound* compound; ///< Compound shape. + const b3HeightField* heightField; ///< Height-field shape. + const b3Hull* hull; ///< Convex hull shape. + const b3Mesh* mesh; ///< Mesh shape with scale. + const b3Sphere* sphere; ///< Sphere shape. }; } b3DebugShape; +/// This struct is passed to b3World_Draw to draw a debug view of the simulation world. typedef struct b3DebugDraw { - // Draws a shape and returns true if drawing should continue + /// Draws a shape and returns true if drawing should continue bool ( *DrawShapeFcn )( void* userShape, b3Transform transform, b3HexColor color, void* context ); /// Draw a line segment. @@ -1577,6 +2983,7 @@ typedef struct b3DebugDraw void* context; } b3DebugDraw; +/// Create a debug draw struct with default values. B3_API b3DebugDraw b3DefaultDebugDraw( void ); -/**@}*/ +/**@}*/ // debug_draw diff --git a/samples/sample.cpp b/samples/sample.cpp index 9c46423..92edb00 100644 --- a/samples/sample.cpp +++ b/samples/sample.cpp @@ -31,6 +31,8 @@ #include #include +#define INFO_PANEL_WIDTH 16.0f + // Load a file. You must free the character array. static char* ReadFile( int& size, const char* filename ) { @@ -498,7 +500,7 @@ void Sample::DrawMetrics() } float fontSize = ImGui::GetFontSize(); - float menuWidth = 14.0f * fontSize; + float menuWidth = INFO_PANEL_WIDTH * fontSize; float drawerHeight = 16.0f * fontSize; float drawerWidth = m_camera->m_width - menuWidth - 1.5f * fontSize; @@ -1739,7 +1741,7 @@ static void DrawInfoPanel( SampleContext* context ) { const SampleEntry& entry = g_sampleEntries[context->sampleIndex]; float fontSize = ImGui::GetFontSize(); - float menuWidth = 16.0f * fontSize; + float menuWidth = INFO_PANEL_WIDTH * fontSize; float menuBarHeight = ImGui::GetFrameHeight(); // Full-height panel pinned under the menu bar at the right edge, matching Box2D. diff --git a/samples/sample_bodies.cpp b/samples/sample_bodies.cpp index aaad92d..898fd5c 100644 --- a/samples/sample_bodies.cpp +++ b/samples/sample_bodies.cpp @@ -385,7 +385,7 @@ public: b3Vec3 offset = { 0.0f, -1.5f, 0.0f }; // See: https://en.wikipedia.org/wiki/Parallel_axis_theorem - inertiaTensor += b3Steiner( mass, offset ); + inertiaTensor = b3AddMM(inertiaTensor, b3Steiner( mass, offset )); b3MassData massData = { .mass = mass, diff --git a/shared/human.c b/shared/human.c index 805d770..aaf4c3e 100644 --- a/shared/human.c +++ b/shared/human.c @@ -379,16 +379,16 @@ void CreateHuman( Human* human, b3WorldId worldId, b3Vec3 position, float fricti b3BodyId bodyIdA = parent->bodyId; b3BodyId bodyIdB = bone->bodyId; - b3Transform frameA = b3NormalizeTransform( bone->localFrameA ); - b3Transform frameB = b3NormalizeTransform( bone->localFrameB ); + bone->localFrameA.q = b3NormalizeQuat( bone->localFrameA.q ); + bone->localFrameB.q = b3NormalizeQuat( bone->localFrameB.q ); if ( bone->jointType == b3_revoluteJoint ) { b3RevoluteJointDef jointDef = b3DefaultRevoluteJointDef(); jointDef.base.bodyIdA = bodyIdA; jointDef.base.bodyIdB = bodyIdB; - jointDef.base.localFrameA = frameA; - jointDef.base.localFrameB = frameB; + jointDef.base.localFrameA = bone->localFrameA; + jointDef.base.localFrameB = bone->localFrameB; jointDef.enableLimit = true; jointDef.lowerAngle = bone->twistLimit.x; jointDef.upperAngle = bone->twistLimit.y; @@ -404,8 +404,8 @@ void CreateHuman( Human* human, b3WorldId worldId, b3Vec3 position, float fricti b3SphericalJointDef jointDef = b3DefaultSphericalJointDef(); jointDef.base.bodyIdA = bodyIdA; jointDef.base.bodyIdB = bodyIdB; - jointDef.base.localFrameA = frameA; - jointDef.base.localFrameB = frameB; + jointDef.base.localFrameA = bone->localFrameA; + jointDef.base.localFrameB = bone->localFrameB; jointDef.enableConeLimit = true; jointDef.coneAngle = bone->swingLimit; jointDef.enableTwistLimit = true; diff --git a/src/aabb.c b/src/aabb.c index c1d5342..6045bd8 100644 --- a/src/aabb.c +++ b/src/aabb.c @@ -3,122 +3,174 @@ #include "aabb.h" +#include "math_internal.h" + #include "box3d/math_functions.h" #include -// 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; } diff --git a/src/aabb.h b/src/aabb.h index c20dca3..97a00b1 100644 --- a/src/aabb.h +++ b/src/aabb.h @@ -5,8 +5,8 @@ #include "box3d/types.h" -// Ray cast an AABB -b3CastOutput b3RayCastAABB( b3AABB a, b3Vec3 p1, b3Vec3 p2 ); +// Ray cast an AABB. This is a custom function used by height fields. +bool b3RayCastAABB( b3AABB a, b3Vec3 p1, b3Vec3 p2, float* minFraction, float* maxFraction ); // Get the surface area (perimeter) static inline float b3Perimeter( b3AABB a ) diff --git a/src/distance.c b/src/distance.c index b0fc17e..295044b 100644 --- a/src/distance.c +++ b/src/distance.c @@ -66,93 +66,6 @@ int b3GetPointSupport( const b3Vec3* points, int count, b3Vec3 axis ) return maxIndex; } -// 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 b3IntersectRayAndAABB( b3Vec3 lowerBound, b3Vec3 upperBound, b3Vec3 p1, b3Vec3 p2, float* minFraction, - float* maxFraction ) -{ - // Ray direction and length - b3Vec3 d = b3Sub( p2, p1 ); - float rayLength = b3Length( d ); - - // Handle degenerate ray - if ( rayLength < FLT_EPSILON ) - { - // Check if point is inside AABB - if ( p1.x >= lowerBound.x && p1.x <= upperBound.x && p1.y >= lowerBound.y && p1.y <= upperBound.y && - p1.z >= lowerBound.z && p1.z <= upperBound.z ) - { - *minFraction = 0.0f; - *maxFraction = 0.0f; - return true; - } - else - { - return false; - } - } - - b3Vec3 rayDir = b3MulSV( 1.0f / rayLength, d ); - - // Slab method for ray-AABB intersection - float tMin = 0.0f; - float tMax = rayLength; - - // Test each axis - for ( int i = 0; i < 3; ++i ) - { - float rayComponent = b3GetByIndex( rayDir, i ); - float rayStart = b3GetByIndex( p1, i ); - float boxMin = b3GetByIndex( lowerBound, i ); - float boxMax = b3GetByIndex( upperBound, i ); - - 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; - } - } - } - - // Check if intersection is behind ray start - if ( tMax < 0.0f ) - { - return false; - } - - // Convert distances to fractions - *minFraction = b3ClampFloat( tMin / rayLength, 0.0f, 1.0f ); - *maxFraction = b3ClampFloat( tMax / rayLength, 0.0f, 1.0f ); - - return true; -} - static void b3BarycentricCoordsEdge( float out[3], b3Vec3 a, b3Vec3 b ) { b3Vec3 ab = b3Sub( b, a ); diff --git a/src/height_field.c b/src/height_field.c index c5a3c68..641f5d5 100644 --- a/src/height_field.c +++ b/src/height_field.c @@ -1,6 +1,7 @@ // SPDX-FileCopyrightText: 2025 Erin Catto // SPDX-License-Identifier: MIT +#include "aabb.h" #include "algorithm.h" #include "body.h" #include "core.h" @@ -615,8 +616,7 @@ b3CastOutput b3ShapeCastHeightField( const b3HeightField* heightField, const b3S b3Add( b3Add( heightField->aabb.upperBound, shapeExtents ), margin ) }; float minFraction, maxFraction; - bool intersects = b3IntersectRayAndAABB( combinedBounds.lowerBound, combinedBounds.upperBound, shapeStart, shapeEnd, - &minFraction, &maxFraction ); + bool intersects = b3RayCastAABB( combinedBounds, shapeStart, shapeEnd, &minFraction, &maxFraction ); if ( intersects == false ) { return result; diff --git a/src/math_functions.c b/src/math_functions.c index a458767..b0b72f9 100644 --- a/src/math_functions.c +++ b/src/math_functions.c @@ -236,7 +236,7 @@ b3Quat b3MakeQuatFromMatrix( const b3Matrix3* m ) b3Quat q; - float trace = b3Trace( *m ); + float trace = m->cx.x + m->cy.y + m->cz.z; if ( trace >= 0.0f ) { q.v.x = c2.z - c3.y; @@ -337,9 +337,9 @@ b3ClosestApproachResult b3ClosestApproachLines( b3Vec3 p1, b3Vec3 d1, b3Vec3 p2, float s2 = 0.0f; result.point1 = b3MulAdd( p1, s1, d1 ); - result.lambda1 = s1; + result.fraction1 = s1; result.point2 = b3MulAdd( p2, s2, d2 ); - result.lambda2 = s2; + result.fraction2 = s2; return result; } @@ -348,9 +348,9 @@ b3ClosestApproachResult b3ClosestApproachLines( b3Vec3 p1, b3Vec3 d1, b3Vec3 p2, float s2 = ( a11 * b2 - a21 * b1 ) / det; result.point1 = b3MulAdd( p1, s1, d1 ); - result.lambda1 = s1; + result.fraction1 = s1; result.point2 = b3MulAdd( p2, s2, d2 ); - result.lambda2 = s2; + result.fraction2 = s2; return result; } @@ -374,9 +374,9 @@ b3ClosestApproachResult b3ClosestApproachSegments( b3Vec3 p1, b3Vec3 q1, b3Vec3 { // Both segments degenerate into points result.point1 = p1; - result.lambda1 = 0.0f; + result.fraction1 = 0.0f; result.point2 = p2; - result.lambda2 = 0.0f; + result.fraction2 = 0.0f; return result; } @@ -387,9 +387,9 @@ b3ClosestApproachResult b3ClosestApproachSegments( b3Vec3 p1, b3Vec3 q1, b3Vec3 float s2 = b3ClampFloat( f / e, 0.0f, 1.0f ); result.point1 = p1; - result.lambda1 = 0.0f; + result.fraction1 = 0.0f; result.point2 = b3MulAdd( p2, s2, d2 ); - result.lambda2 = s2; + result.fraction2 = s2; return result; } @@ -400,9 +400,9 @@ b3ClosestApproachResult b3ClosestApproachSegments( b3Vec3 p1, b3Vec3 q1, b3Vec3 float s1 = b3ClampFloat( -c / a, 0.0f, 1.0f ); result.point1 = b3MulAdd( p1, s1, d1 ); - result.lambda1 = s1; + result.fraction1 = s1; result.point2 = p2; - result.lambda2 = 0.0f; + result.fraction2 = 0.0f; return result; } @@ -425,9 +425,9 @@ b3ClosestApproachResult b3ClosestApproachSegments( b3Vec3 p1, b3Vec3 q1, b3Vec3 } result.point1 = b3MulAdd( p1, s1, d1 ); - result.lambda1 = s1; + result.fraction1 = s1; result.point2 = b3MulAdd( p2, s2, d2 ); - result.lambda2 = s2; + result.fraction2 = s2; return result; } diff --git a/src/math_internal.h b/src/math_internal.h index 7ba4337..2d885e5 100644 --- a/src/math_internal.h +++ b/src/math_internal.h @@ -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 ) }; +} diff --git a/src/mesh_contact.c b/src/mesh_contact.c index be1426d..610d2d0 100644 --- a/src/mesh_contact.c +++ b/src/mesh_contact.c @@ -288,7 +288,14 @@ static inline bool b3IsBetterCullCandidate( float score, float separation, float return separation < bestSeparation - separationTol; } -int b3CullPoints( b3Point2D* points, int count ) +typedef struct b3Point2D +{ + b3Vec2 p; + float separation; + int originalIndex; +} b3Point2D; + +static int b3CullPoints( b3Point2D* points, int count ) { if ( count <= 1 ) { diff --git a/src/solver.c b/src/solver.c index cd0759c..a908020 100644 --- a/src/solver.c +++ b/src/solver.c @@ -764,8 +764,11 @@ static void b3FinalizeBodiesTask( int startIndex, int endIndex, int workerIndex, } else if ( island->constraintRemoveCount > 0 ) { - // body wants to sleep but its island needs splitting first - if ( body->sleepTime > taskContext->splitSleepTime ) + // Body wants to sleep but its island needs splitting first. Track the sleepiest candidate. + // Break sleep time ties using the island id to ensure determinism. The cross worker reduction + // breaks ties the same way. + if ( body->sleepTime > taskContext->splitSleepTime || + ( body->sleepTime == taskContext->splitSleepTime && body->islandId > taskContext->splitIslandId ) ) { // pick the sleepiest candidate taskContext->splitIslandId = body->islandId; diff --git a/src/triangle_manifold.c b/src/triangle_manifold.c index 015cb25..5ed5286 100644 --- a/src/triangle_manifold.c +++ b/src/triangle_manifold.c @@ -299,7 +299,7 @@ static void b3BuildTriangleAndCapsuleEdgeContact( b3LocalManifold* manifold, con b3ClosestApproachResult result = b3ClosestApproachLines( v1, triangleEdge, p1, capsuleEdge ); - if ( result.lambda1 < 0.0f || 1.0f < result.lambda1 || result.lambda2 < 0.0f || 1.0f < result.lambda2 ) + if ( result.fraction1 < 0.0f || 1.0f < result.fraction1 || result.fraction2 < 0.0f || 1.0f < result.fraction2 ) { // closest point beyond end points return; @@ -854,7 +854,7 @@ static void b3CollideHullAndTriangleEdges( b3LocalManifold* manifold, int capaci b3ClosestApproachResult result = b3ClosestApproachLines( pA, eA, pB, eB ); // Is one of the closest points outside of the associated edge segment? - if ( capacity == 0 || result.lambda1 < 0.0f || 1.0f < result.lambda1 || result.lambda2 < 0.0f || 1.0f < result.lambda2 ) + if ( capacity == 0 || result.fraction1 < 0.0f || 1.0f < result.fraction1 || result.fraction2 < 0.0f || 1.0f < result.fraction2 ) { // Invalid edge pair, no points generated B3_ASSERT( manifold->pointCount == 0 ); diff --git a/test/test_collision.c b/test/test_collision.c index 87fcea2..8fef814 100644 --- a/test/test_collision.c +++ b/test/test_collision.c @@ -9,12 +9,12 @@ static int AABBTest( void ) { b3AABB a; - a.lowerBound = ( b3Vec3 ){ -1.0f, -1.0f, -1.0f }; - a.upperBound = ( b3Vec3 ){ -2.0f, -2.0f, -2.0f }; + a.lowerBound = (b3Vec3){ -1.0f, -1.0f, -1.0f }; + a.upperBound = (b3Vec3){ -2.0f, -2.0f, -2.0f }; ENSURE( b3IsValidAABB( a ) == false ); - a.upperBound = ( b3Vec3 ){ 1.0f, 1.0f }; + a.upperBound = (b3Vec3){ 1.0f, 1.0f }; ENSURE( b3IsValidAABB( a ) == true ); b3AABB b = { { 2.0f, 2.0f }, { 4.0f, 4.0f } }; @@ -28,13 +28,12 @@ static int TestRayAABBIntersection( void ) { // Test 1: Ray passing through center of AABB { - b3Vec3 lowerBound = { -1.0f, -1.0f, -1.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { -1.0f, -1.0f, -1.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { -2.0f, 0.0f, 0.0f }; b3Vec3 p2 = { 2.0f, 0.0f, 0.0f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == true ); ENSURE( b3AbsFloat( minFraction - 0.25f ) < 0.001f ); // Enters at 25% of ray @@ -43,13 +42,12 @@ static int TestRayAABBIntersection( void ) // Test 2: Ray starting inside AABB { - b3Vec3 lowerBound = { -1.0f, -1.0f, -1.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { -1.0f, -1.0f, -1.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { 0.0f, 0.0f, 0.0f }; b3Vec3 p2 = { 2.0f, 0.0f, 0.0f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == true ); ENSURE( minFraction == 0.0f ); // Starts inside @@ -58,13 +56,12 @@ static int TestRayAABBIntersection( void ) // Test 3: Ray ending inside AABB { - b3Vec3 lowerBound = { -1.0f, -1.0f, -1.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { -1.0f, -1.0f, -1.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { -2.0f, 0.0f, 0.0f }; b3Vec3 p2 = { 0.0f, 0.0f, 0.0f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == true ); ENSURE( b3AbsFloat( minFraction - 0.5f ) < 0.001f ); // Enters at 50% of ray @@ -73,13 +70,12 @@ static int TestRayAABBIntersection( void ) // Test 4: Ray completely inside AABB { - b3Vec3 lowerBound = { -2.0f, -2.0f, -2.0f }; - b3Vec3 upperBound = { 2.0f, 2.0f, 2.0f }; + b3AABB a = { { -2.0f, -2.0f, -2.0f }, { 2.0f, 2.0f, 2.0f } }; b3Vec3 p1 = { -1.0f, 0.0f, 0.0f }; b3Vec3 p2 = { 1.0f, 0.0f, 0.0f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == true ); ENSURE( minFraction == 0.0f ); @@ -88,39 +84,36 @@ static int TestRayAABBIntersection( void ) // Test 5: Ray missing AABB { - b3Vec3 lowerBound = { 0.0f, 0.0f, 0.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { 0.0f, 0.0f, 0.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { -1.0f, 2.0f, 0.5f }; b3Vec3 p2 = { 2.0f, 2.0f, 0.5f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == false ); } // Test 6: Ray parallel to AABB face (no intersection) { - b3Vec3 lowerBound = { 0.0f, 0.0f, 0.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { 0.0f, 0.0f, 0.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { -1.0f, 2.0f, 0.5f }; b3Vec3 p2 = { 2.0f, 2.0f, 0.5f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == false ); } // Test 7: Ray parallel to AABB face (within bounds) { - b3Vec3 lowerBound = { 0.0f, 0.0f, 0.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { 0.0f, 0.0f, 0.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { -1.0f, 0.5f, 0.5f }; b3Vec3 p2 = { 2.0f, 0.5f, 0.5f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == true ); ENSURE( b3AbsFloat( minFraction - 1.0f / 3.0f ) < 0.001f ); @@ -129,13 +122,12 @@ static int TestRayAABBIntersection( void ) // Test 8: Degenerate ray (point) inside AABB { - b3Vec3 lowerBound = { 0.0f, 0.0f, 0.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { 0.0f, 0.0f, 0.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { 0.5f, 0.5f, 0.5f }; b3Vec3 p2 = { 0.5f, 0.5f, 0.5f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == true ); ENSURE( minFraction == 0.0f ); @@ -144,39 +136,36 @@ static int TestRayAABBIntersection( void ) // Test 9: Degenerate ray (point) outside AABB { - b3Vec3 lowerBound = { 0.0f, 0.0f, 0.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { 0.0f, 0.0f, 0.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { 2.0f, 2.0f, 2.0f }; b3Vec3 p2 = { 2.0f, 2.0f, 2.0f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == false ); } // Test 10: Ray pointing away from AABB { - b3Vec3 lowerBound = { 0.0f, 0.0f, 0.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { 0.0f, 0.0f, 0.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { -1.0f, 0.5f, 0.5f }; b3Vec3 p2 = { -2.0f, 0.5f, 0.5f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == false ); } // Test 11: Ray hitting corner of AABB { - b3Vec3 lowerBound = { 0.0f, 0.0f, 0.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { 0.0f, 0.0f, 0.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { -1.0f, -1.0f, -1.0f }; b3Vec3 p2 = { 2.0f, 2.0f, 2.0f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == true ); ENSURE( b3AbsFloat( minFraction - 1.0f / 3.0f ) < 0.001f ); @@ -185,13 +174,12 @@ static int TestRayAABBIntersection( void ) // Test 12: Ray grazing edge of AABB { - b3Vec3 lowerBound = { 0.0f, 0.0f, 0.0f }; - b3Vec3 upperBound = { 1.0f, 1.0f, 1.0f }; + b3AABB a = { { 0.0f, 0.0f, 0.0f }, { 1.0f, 1.0f, 1.0f } }; b3Vec3 p1 = { -1.0f, 0.0f, 0.5f }; b3Vec3 p2 = { 2.0f, 0.0f, 0.5f }; float minFraction, maxFraction; - bool hit = b3IntersectRayAndAABB( lowerBound, upperBound, p1, p2, &minFraction, &maxFraction ); + bool hit = b3RayCastAABB( a, p1, p2, &minFraction, &maxFraction ); ENSURE( hit == true ); ENSURE( b3AbsFloat( minFraction - 1.0f / 3.0f ) < 0.001f );