Doxygen comments (#12)

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

59
docs/CMakeLists.txt Normal file
View file

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

207
docs/character.md Normal file
View file

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

502
docs/collision.md Normal file
View file

@ -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.
<!-- TODO: 3D diagram needed -->
```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.
<!-- TODO: 3D diagram needed -->
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.

157
docs/compound.md Normal file
View file

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

85
docs/extra.css Normal file
View file

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

140
docs/faq.md Normal file
View file

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

230
docs/foundation.md Normal file
View file

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

208
docs/hello.md Normal file
View file

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

243
docs/images/capsule.svg Normal file
View file

@ -0,0 +1,243 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
width="74.701591mm"
height="57.912811mm"
viewBox="0 0 74.701591 57.912812"
version="1.1"
id="svg1"
inkscape:version="1.3 (0e150ed6c4, 2023-07-21)"
sodipodi:docname="capsule.svg"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<sodipodi:namedview
id="namedview1"
pagecolor="#ffffff"
bordercolor="#000000"
borderopacity="0.25"
inkscape:showpageshadow="2"
inkscape:pageopacity="0.0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#d1d1d1"
inkscape:document-units="mm"
showgrid="true"
inkscape:zoom="1.2302679"
inkscape:cx="39.828722"
inkscape:cy="112.5771"
inkscape:window-width="1991"
inkscape:window-height="1283"
inkscape:window-x="161"
inkscape:window-y="74"
inkscape:window-maximized="0"
inkscape:current-layer="layer1"
showborder="true">
<inkscape:grid
id="grid1"
units="px"
originx="-163.45355"
originy="-465.9191"
spacingx="0.26458333"
spacingy="0.26458334"
empcolor="#0099e5"
empopacity="0.30196078"
color="#0099e5"
opacity="0.14901961"
empspacing="5"
dotted="false"
gridanglex="30"
gridanglez="30"
visible="true" />
</sodipodi:namedview>
<defs
id="defs1">
<marker
style="overflow:visible"
id="marker6"
refX="2"
refY="0"
orient="auto-start-reverse"
inkscape:stockid="Triangle arrow"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.5)"
style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
d="M 5.77,0 -2.88,5 V -5 Z"
id="path6" />
</marker>
<marker
style="overflow:visible"
id="Triangle"
refX="0"
refY="0"
orient="auto-start-reverse"
inkscape:stockid="Triangle arrow"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.5)"
style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
d="M 5.77,0 -2.88,5 V -5 Z"
id="path135" />
</marker>
</defs>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-43.247086,-123.27443)">
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1;marker-start:url(#Triangle);marker-end:url(#Triangle)"
d="M 43.862625,132.52899 V 180.5717 H 91.802184"
id="path2" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="94.56707"
y="180.37776"
id="text6"
transform="scale(0.99892594,1.0010752)"><tspan
sodipodi:role="line"
id="tspan6"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="94.56707"
y="180.37776">x</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="43.839172"
y="128.60797"
id="text7"
transform="scale(0.99892594,1.0010752)"><tspan
sodipodi:role="line"
id="tspan7"
x="43.839172"
y="128.60797"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;stroke-width:0.2">y</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="106.92114"
y="133.36127"
id="text8"
transform="scale(0.99892595,1.0010752)"><tspan
sodipodi:role="line"
id="tspan8"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="106.92114"
y="133.36127">radius</tspan></text>
<g
id="g13"
transform="rotate(44.077969,71.155285,164.2336)">
<g
id="g11">
<rect
style="fill:#d7e3f4;fill-opacity:1;stroke:none;stroke-width:0.2"
id="rect10"
width="25.965992"
height="20.089922"
x="53.587948"
y="129.86963" />
<path
style="fill:#d7e3f4;stroke:#000000;stroke-width:0.2"
id="path7"
sodipodi:type="arc"
sodipodi:cx="66.570946"
sodipodi:cy="149.70604"
sodipodi:rx="12.982997"
sodipodi:ry="12.982997"
sodipodi:start="0"
sodipodi:end="3.1415927"
sodipodi:open="true"
sodipodi:arc-type="arc"
d="m 79.553943,149.70604 a 12.982997,12.982997 0 0 1 -6.491499,11.2436 12.982997,12.982997 0 0 1 -12.982997,0 12.982997,12.982997 0 0 1 -6.491498,-11.2436" />
<path
style="fill:#d7e3f4;stroke:#000000;stroke-width:0.2"
id="path8"
sodipodi:type="arc"
sodipodi:cx="-66.570946"
sodipodi:cy="-129.86963"
sodipodi:rx="12.982997"
sodipodi:ry="12.982997"
sodipodi:start="0"
sodipodi:end="3.1415927"
sodipodi:open="true"
sodipodi:arc-type="arc"
d="m -53.587949,-129.86963 a 12.982997,12.982997 0 0 1 -6.491498,11.24361 12.982997,12.982997 0 0 1 -12.982998,0 12.982997,12.982997 0 0 1 -6.491498,-11.24361"
transform="scale(-1)" />
<path
style="fill:none;stroke:#000000;stroke-width:0.2"
d="M 53.587949,149.70604 V 129.86963"
id="path9" />
<path
style="fill:none;stroke:#000000;stroke-width:0.2"
d="M 79.553943,149.70604 V 129.86963"
id="path10" />
</g>
<g
id="g10"
transform="translate(-0.7121401)">
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1"
d="m 64.663551,128.81687 5.23907,2e-5"
id="path3" />
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1"
d="m 67.239311,126.14784 0.0438,5.54822"
id="path4" />
</g>
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1;marker-end:url(#marker6)"
d="m 66.548845,128.81689 7.978012,-8.69753"
id="path5"
sodipodi:nodetypes="cc" />
<g
id="g12"
transform="translate(-0.7121401,21.142672)">
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1"
d="m 64.663551,128.81687 5.23907,2e-5"
id="path11" />
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1"
d="m 67.239311,126.14784 0.0438,5.54822"
id="path12" />
</g>
</g>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="84.581787"
y="140.62871"
id="text9"
transform="scale(0.99892595,1.0010752)"><tspan
sodipodi:role="line"
id="tspan9"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="84.581787"
y="140.62871">center2</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="71.103676"
y="156.31134"
id="text13"
transform="scale(0.99892595,1.0010752)"><tspan
sodipodi:role="line"
id="tspan13"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="71.103676"
y="156.31134">center1</tspan></text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 11 KiB

View file

@ -0,0 +1,124 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="296.5"
height="142.84351"
id="svg4080"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="captured.svg"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\captured.png"
inkscape:export-xdpi="90"
inkscape:export-ydpi="90">
<defs
id="defs4082">
<inkscape:perspective
sodipodi:type="inkscape:persp3d"
inkscape:vp_x="0 : 526.18109 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_z="744.09448 : 526.18109 : 1"
inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
id="perspective4088" />
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="1.4142136"
inkscape:cx="-105.19711"
inkscape:cy="-99.626528"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1920"
inkscape:window-height="1138"
inkscape:window-x="-8"
inkscape:window-y="-8"
inkscape:window-maximized="1"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata4085">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-245,-431.01868)">
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect4090"
width="295.5"
height="17"
x="245.5"
y="556.36218" />
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect4602"
width="8"
height="134"
x="565.5022"
y="92.054398"
transform="rotate(39.650005)" />
<rect
y="502.45367"
x="298.04913"
height="134"
width="8"
id="rect4604"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
transform="rotate(-11.210987)" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="328"
y="465.36218"
id="text4608"><tspan
sodipodi:role="line"
id="tspan4610"
x="328"
y="465.36218"
style="font-size:12px;line-height:1.25">t=0</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="419.5"
y="465.33875"
id="text4612"><tspan
sodipodi:role="line"
id="tspan4614"
x="419.5"
y="465.33875"
style="font-size:12px;line-height:1.25">t=1</tspan></text>
<rect
transform="rotate(30.564716)"
y="182.57234"
x="547.54456"
height="134"
width="8"
id="rect2822"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:1, 2;stroke-dashoffset:0;stroke-opacity:1" />
</g>
</svg>

After

Width:  |  Height:  |  Size: 4.2 KiB

View file

@ -0,0 +1,183 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
width="63.935326mm"
height="54.758583mm"
viewBox="0 0 63.935312 54.758582"
version="1.1"
id="svg1"
inkscape:version="1.3 (0e150ed6c4, 2023-07-21)"
sodipodi:docname="center_of_mass.svg"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<sodipodi:namedview
id="namedview1"
pagecolor="#ffffff"
bordercolor="#000000"
borderopacity="0.25"
inkscape:showpageshadow="2"
inkscape:pageopacity="0.0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#d1d1d1"
inkscape:document-units="mm"
showgrid="true"
inkscape:zoom="2.4605357"
inkscape:cx="111.35786"
inkscape:cy="155.86037"
inkscape:window-width="1991"
inkscape:window-height="1283"
inkscape:window-x="688"
inkscape:window-y="281"
inkscape:window-maximized="0"
inkscape:current-layer="layer1"
showborder="true">
<inkscape:grid
id="grid1"
units="px"
originx="-293.2242"
originy="-430.03906"
spacingx="0.26458333"
spacingy="0.26458334"
empcolor="#0099e5"
empopacity="0.30196078"
color="#0099e5"
opacity="0.14901961"
empspacing="5"
dotted="false"
gridanglex="30"
gridanglez="30"
visible="true" />
</sodipodi:namedview>
<defs
id="defs1">
<marker
style="overflow:visible"
id="Triangle"
refX="0"
refY="0"
orient="auto-start-reverse"
inkscape:stockid="Triangle arrow"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.5)"
style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
d="M 5.77,0 -2.88,5 V -5 Z"
id="path135" />
</marker>
</defs>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-77.582238,-113.78116)">
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="103.4439"
y="153.98045"
id="text5"
transform="scale(0.99892595,1.0010752)"><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="103.4439"
y="153.98045"
id="tspan5">body origin</tspan></text>
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1;marker-start:url(#Triangle);marker-end:url(#Triangle)"
d="m 78.197777,119.8815 v 48.04271 h 47.939563"
id="path2" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="128.93915"
y="167.74385"
id="text6"
transform="scale(0.99892595,1.0010752)"><tspan
sodipodi:role="line"
id="tspan6"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="128.93915"
y="167.74385">x</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="78.211243"
y="115.97406"
id="text7"
transform="scale(0.99892595,1.0010752)"><tspan
sodipodi:role="line"
id="tspan7"
x="78.211243"
y="115.97406"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;stroke-width:0.2">y</tspan></text>
<g
id="g5"
transform="translate(-19.011124,19.078483)">
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1"
d="m 136.87813,117.21246 5.23907,2e-5"
id="path1" />
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1"
d="m 139.45389,114.54343 0.0438,5.54822"
id="path5" />
</g>
<g
id="g6"
transform="rotate(-23.043678,80.269077,108.82979)">
<rect
style="fill:#d7e3f4;fill-opacity:1;stroke:#000000;stroke-width:0.199999;stroke-dasharray:none;stroke-opacity:1"
id="rect6"
width="32.151703"
height="18.817886"
x="93.335541"
y="139.84744" />
<path
style="fill:none;stroke:#000000;stroke-width:0.3;stroke-dasharray:none;stroke-opacity:1;marker-start:url(#Triangle);marker-end:url(#Triangle)"
d="m 93.430501,151.96234 v 6.53583 h 6.518773"
id="path6" />
</g>
<g
id="g1"
transform="translate(-16.429863,17.42219)">
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1"
d="m 136.87813,117.21246 5.23907,2e-5"
id="path3" />
<path
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-opacity:1"
d="m 139.45389,114.54343 0.0438,5.54822"
id="path4" />
</g>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2;stroke-opacity:1"
x="130.96655"
y="127.98591"
id="text1"
transform="scale(0.99892595,1.0010752)"><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="130.96655"
y="127.98591"
id="tspan1">center</tspan><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="130.96655"
y="131.51369"
id="tspan8">of</tspan><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2"
x="130.96655"
y="135.04146"
id="tspan9">mass</tspan></text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 8.8 KiB

178
docs/images/distance.svg Normal file
View file

@ -0,0 +1,178 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="271.28311"
height="111.33035"
id="svg2"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="distance.svg"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\distance.png"
inkscape:export-xdpi="90"
inkscape:export-ydpi="90">
<defs
id="defs4">
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend"
style="overflow:visible">
<path
id="path3696"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6)"
inkscape:connector-curvature="0" />
</marker>
<marker
inkscape:stockid="Arrow2Lend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Lend"
style="overflow:visible">
<path
id="path3690"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
inkscape:connector-curvature="0" />
</marker>
<inkscape:perspective
sodipodi:type="inkscape:persp3d"
inkscape:vp_x="0 : 526.18109 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_z="744.09448 : 526.18109 : 1"
inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
id="perspective10" />
<inkscape:perspective
id="perspective2830"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
<inkscape:perspective
id="perspective2852"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
<inkscape:perspective
id="perspective3648"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
<inkscape:perspective
id="perspective4310"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend-0"
style="overflow:visible">
<path
id="path3696-9"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6)"
inkscape:connector-curvature="0" />
</marker>
<inkscape:perspective
id="perspective4342"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="2"
inkscape:cx="26.976981"
inkscape:cy="-103.40251"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1467"
inkscape:window-height="1068"
inkscape:window-x="196"
inkscape:window-y="16"
inkscape:window-maximized="0"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata7">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-209.30148,-534.31362)">
<path
style="fill:none;stroke:#000000;stroke-width:1.21355975;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.21355975, 2.4271195;stroke-dashoffset:0;stroke-opacity:1;marker-end:none"
d="m 388,603.62582 -62,0.47272"
id="path3664"
sodipodi:nodetypes="cc"
inkscape:connector-curvature="0" />
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 387,546.86218 79,-1 14,56 -91,43 z"
id="path2816"
inkscape:connector-curvature="0" />
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 246.19848,535.12334 80.64122,69.26034 -116.72691,8.47526 z"
id="path2818"
inkscape:connector-curvature="0" />
<rect
style="fill:#00ff00;fill-opacity:1;stroke-width:1.5;stroke-miterlimit:4;stroke-dasharray:none"
id="rect2820"
width="7"
height="7"
x="385.5"
y="599.36218" />
<rect
style="fill:#00ff00;fill-opacity:1;stroke-width:1.5;stroke-miterlimit:4;stroke-dasharray:none"
id="rect2820-1"
width="7"
height="7"
x="323"
y="599.86218" />
</g>
</svg>

After

Width:  |  Height:  |  Size: 6.2 KiB

126
docs/images/logo.svg Normal file
View file

@ -0,0 +1,126 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="23.160606mm"
height="19.770294mm"
viewBox="0 0 23.160606 19.770294"
version="1.1"
id="svg8"
inkscape:version="0.92.3 (2405546, 2018-03-11)"
sodipodi:docname="Logo.svg">
<defs
id="defs2" />
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="2.8"
inkscape:cx="91.164312"
inkscape:cy="2.0199043"
inkscape:document-units="mm"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:snap-grids="false"
inkscape:snap-to-guides="false"
inkscape:snap-others="false"
inkscape:object-nodes="false"
inkscape:snap-nodes="false"
inkscape:snap-global="false"
inkscape:window-width="2560"
inkscape:window-height="1377"
inkscape:window-x="-8"
inkscape:window-y="-8"
inkscape:window-maximized="1"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata5">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-4.3336132,-2.5558382)">
<rect
id="rect3724"
width="5.3740902"
height="4.9586015"
x="12.262583"
y="10.94324"
style="fill:none;stroke:#30aebf;stroke-width:0.60000002;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
inkscape:export-xdpi="208.37"
inkscape:export-ydpi="208.37" />
<rect
id="rect3724-5"
width="5.3740902"
height="4.9586015"
x="15.178779"
y="16.447105"
style="fill:none;stroke:#30aebf;stroke-width:0.60000002;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
<rect
id="rect3724-7"
width="5.3740902"
height="4.9586015"
x="9.251893"
y="16.447105"
style="fill:none;stroke:#30aebf;stroke-width:0.60000002;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
<path
style="fill:none;stroke:#8cc924;stroke-width:0.60000002;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
d="m 4.3348411,22.026134 21.1823269,-0.0867"
id="path4552"
inkscape:connector-curvature="0"
inkscape:export-xdpi="208.37"
inkscape:export-ydpi="208.37" />
<circle
style="fill:none;stroke:#dc3132;stroke-width:0.60000002;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
id="path4554"
cx="21.845764"
cy="8.3044558"
r="2.5724692"
inkscape:export-xdpi="208.37"
inkscape:export-ydpi="208.37" />
<path
style="fill:none;stroke:#eb8788;stroke-width:0.60000002;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
d="m 22.547358,4.9301842 2.104747,-2.07134"
id="path4556"
inkscape:connector-curvature="0"
inkscape:export-xdpi="208.37"
inkscape:export-ydpi="208.37" />
<path
inkscape:connector-curvature="0"
id="path4558"
d="m 24.184383,5.7319842 2.104747,-2.07134"
style="fill:none;stroke:#eb8788;stroke-width:0.60000002;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
inkscape:export-xdpi="208.37"
inkscape:export-ydpi="208.37" />
<path
style="fill:none;stroke:#eb8788;stroke-width:0.60000002;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
d="m 25.086418,7.1685542 2.104747,-2.07134"
id="path4562"
inkscape:connector-curvature="0"
inkscape:export-xdpi="208.37"
inkscape:export-ydpi="208.37" />
</g>
</svg>

After

Width:  |  Height:  |  Size: 4.4 KiB

256
docs/images/manifolds.svg Normal file
View file

@ -0,0 +1,256 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="278.64941"
height="199.68138"
id="svg2"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="manifolds.svg"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="90"
inkscape:export-ydpi="90">
<defs
id="defs4">
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend"
style="overflow:visible">
<path
id="path3696"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6)"
inkscape:connector-curvature="0" />
</marker>
<marker
inkscape:stockid="Arrow2Lend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Lend"
style="overflow:visible">
<path
id="path3690"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
inkscape:connector-curvature="0" />
</marker>
<inkscape:perspective
sodipodi:type="inkscape:persp3d"
inkscape:vp_x="0 : 526.18109 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_z="744.09448 : 526.18109 : 1"
inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
id="perspective10" />
<inkscape:perspective
id="perspective2830"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
<inkscape:perspective
id="perspective2852"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
<inkscape:perspective
id="perspective3648"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
<inkscape:perspective
id="perspective4310"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend-0"
style="overflow:visible">
<path
id="path3696-9"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6)"
inkscape:connector-curvature="0" />
</marker>
<inkscape:perspective
id="perspective4342"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="2"
inkscape:cx="107.80664"
inkscape:cy="78.632812"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1097"
inkscape:window-height="1068"
inkscape:window-x="214"
inkscape:window-y="23"
inkscape:window-maximized="0"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata7">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-208.19336,-534.31362)">
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 227,602.36218 79,-1 14,56 -91,43 z"
id="path2816"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958"
inkscape:connector-curvature="0" />
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 246.19848,535.12334 80.64122,69.26034 -116.72691,8.47526 z"
id="path2818"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958"
inkscape:connector-curvature="0" />
<rect
style="fill:#00ff00;fill-opacity:1;stroke-width:1.5;stroke-miterlimit:4;stroke-dasharray:none"
id="rect2820"
width="7"
height="7"
x="224"
y="608.36218"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958" />
<rect
style="fill:#00ff00;fill-opacity:1;stroke-width:1.5;stroke-miterlimit:4;stroke-dasharray:none"
id="rect2820-1"
width="7"
height="7"
x="303.5"
y="602.36218"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958" />
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 386,601.86218 79,-1 14,56 -91,43 z"
id="path2816-7"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958"
inkscape:connector-curvature="0" />
<circle
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
id="path2866"
transform="translate(-2,14)"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958"
cx="428.75"
cy="556.61218"
r="34.75" />
<rect
style="fill:#00ff00;fill-opacity:1;stroke-width:1.5;stroke-miterlimit:4;stroke-dasharray:none"
id="rect2820-4"
width="7"
height="7"
x="424.5"
y="602.86218"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958" />
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Mend)"
d="m 264,601.36218 v -26.5"
id="path3664"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958"
inkscape:connector-curvature="0" />
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Mend)"
d="m 427.50961,601.02437 v -26.5"
id="path3664-4"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958"
inkscape:connector-curvature="0" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="208"
y="731.86218"
id="text4330"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958"><tspan
sodipodi:role="line"
id="tspan4332"
x="208"
y="731.86218"
style="font-size:12px;line-height:1.25">two points, one normal</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="378.83105"
y="731.86218"
id="text4330-8"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\manifolds.png"
inkscape:export-xdpi="180.11958"
inkscape:export-ydpi="180.11958"><tspan
sodipodi:role="line"
id="tspan4332-8"
x="378.83105"
y="731.86218"
style="font-size:12px;line-height:1.25">one point, one normal</tspan></text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 9.9 KiB

153
docs/images/missed_toi.svg Normal file
View file

@ -0,0 +1,153 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="296.5"
height="148.6571"
id="svg4080"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="missed_toi.svg"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\missed.png"
inkscape:export-xdpi="90"
inkscape:export-ydpi="90">
<defs
id="defs4082">
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend"
style="overflow:visible">
<path
id="path3626"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6)"
inkscape:connector-curvature="0" />
</marker>
<inkscape:perspective
sodipodi:type="inkscape:persp3d"
inkscape:vp_x="0 : 526.18109 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_z="744.09448 : 526.18109 : 1"
inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
id="perspective4088" />
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="2"
inkscape:cx="-118.5"
inkscape:cy="37.499998"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1920"
inkscape:window-height="1138"
inkscape:window-x="-8"
inkscape:window-y="-8"
inkscape:window-maximized="1"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata4085">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-245,-425.20508)">
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect4090"
width="295.5"
height="17"
x="245.5"
y="556.36218" />
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect4602"
width="8"
height="134"
x="506.24817"
y="262.38239"
transform="rotate(20.920228)" />
<rect
y="542.29114"
x="223.04268"
height="134"
width="8"
id="rect4604"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
transform="rotate(-20.611746)" />
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:2, 4;stroke-dashoffset:0;stroke-opacity:1"
id="rect4606"
width="8"
height="134"
x="389"
y="429.36218" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="340.5"
y="466.36218"
id="text4608"><tspan
sodipodi:role="line"
id="tspan4610"
x="340.5"
y="466.36218"
style="font-size:12px;line-height:1.25">t=0</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="432.5"
y="466.33875"
id="text4612"><tspan
sodipodi:role="line"
id="tspan4614"
x="432.5"
y="466.33875"
style="font-size:12px;line-height:1.25">t=1</tspan></text>
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Mend)"
d="m 500.5,556.36218 v -40.5"
id="path2822"
inkscape:connector-curvature="0" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="462.5"
y="507.86218"
id="text4044"><tspan
sodipodi:role="line"
id="tspan4046"
x="462.5"
y="507.86218"
style="font-size:12px;line-height:1.25">separating axis</tspan></text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 5.4 KiB

BIN
docs/images/mover.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 106 KiB

View file

@ -0,0 +1,148 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="231.14912"
height="184.62988"
id="svg3598"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="overlap_test.svg"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\regionquery.png"
inkscape:export-xdpi="90"
inkscape:export-ydpi="90">
<defs
id="defs3600">
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend"
style="overflow:visible">
<path
id="path4314"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6)"
inkscape:connector-curvature="0" />
</marker>
<inkscape:perspective
sodipodi:type="inkscape:persp3d"
inkscape:vp_x="0 : 526.18109 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_z="744.09448 : 526.18109 : 1"
inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
id="perspective3606" />
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="4.3325546"
inkscape:cx="115.57456"
inkscape:cy="79.495605"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1920"
inkscape:window-height="1138"
inkscape:window-x="-8"
inkscape:window-y="-8"
inkscape:window-maximized="1"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata3603">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-209.87013,-406.2323)">
<rect
y="473.70428"
x="232.34212"
height="16.815773"
width="19.815773"
id="rect4120"
style="fill:none;stroke:#00d200;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="429.19492"
x="378.33273"
height="36.334541"
width="54.334541"
id="rect4122"
style="fill:none;stroke:#00d200;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="548.88507"
x="222.02287"
height="21.954247"
width="35.454247"
id="rect4124"
style="fill:none;stroke:#00d200;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="508.34296"
x="408.48077"
height="20.538485"
width="32.038483"
id="rect4126"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="524.32886"
x="306.46667"
height="61.066628"
width="43.566628"
id="rect4128"
style="fill:none;stroke:#00d200;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="429.74796"
x="292.88577"
height="66.228439"
width="33.728436"
id="rect4130"
style="fill:none;stroke:#00d200;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
style="fill:none;stroke:#00d200;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect4276"
width="33.790939"
height="30.790941"
x="374.60455"
y="547.46674" />
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect4278"
width="49.259716"
height="43.759716"
x="210.37013"
y="406.7323" />
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:2, 4;stroke-dashoffset:0;stroke-opacity:1"
id="rect2826"
width="149.5"
height="128"
x="248"
y="462.36218" />
</g>
</svg>

After

Width:  |  Height:  |  Size: 4.9 KiB

151
docs/images/raycast.svg Normal file
View file

@ -0,0 +1,151 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="248.01385"
height="218.69197"
id="svg3598"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="raycast.svg"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\raycast.png"
inkscape:export-xdpi="90"
inkscape:export-ydpi="90">
<defs
id="defs3600">
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend"
style="overflow:visible">
<path
id="path4314"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6)"
inkscape:connector-curvature="0" />
</marker>
<inkscape:perspective
sodipodi:type="inkscape:persp3d"
inkscape:vp_x="0 : 526.18109 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_z="744.09448 : 526.18109 : 1"
inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
id="perspective3606" />
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="3.6543567"
inkscape:cx="124.00693"
inkscape:cy="94.046232"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1246"
inkscape:window-height="849"
inkscape:window-x="100"
inkscape:window-y="100"
inkscape:window-maximized="0"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata3603">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-193.0054,-367.20351)">
<rect
y="473.70428"
x="232.34212"
height="16.815773"
width="19.815773"
id="rect4120"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="429.19492"
x="378.33273"
height="36.334541"
width="54.334541"
id="rect4122"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="548.88507"
x="222.02287"
height="21.954247"
width="35.454247"
id="rect4124"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="508.34296"
x="408.48077"
height="20.538485"
width="32.038483"
id="rect4126"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="524.32886"
x="306.46667"
height="61.066628"
width="43.566628"
id="rect4128"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
y="429.74796"
x="292.88577"
height="66.228439"
width="33.728436"
id="rect4130"
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect4276"
width="33.790939"
height="30.790941"
x="374.60455"
y="547.46674" />
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect4278"
width="49.259716"
height="43.759716"
x="210.37013"
y="406.7323" />
<path
style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 2;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow2Mend)"
d="m 413.96525,367.89693 -219.9305,175.4305"
id="path4282"
inkscape:connector-curvature="0" />
<path
id="path4732"
d="m 414.26779,367.59439 -86.85587,69.28175"
style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow2Mend)"
inkscape:connector-curvature="0" />
</g>
</svg>

After

Width:  |  Height:  |  Size: 5.3 KiB

BIN
docs/images/samples.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 326 KiB

View file

@ -0,0 +1,396 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
width="899.99988"
height="313.64758"
viewBox="0 0 238.12496 82.985931"
version="1.1"
id="svg1"
inkscape:version="1.3.2 (091e20e, 2023-11-25, custom)"
sodipodi:docname="simulation_loop_s.svg"
xml:space="preserve"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg"><sodipodi:namedview
id="namedview1"
pagecolor="#c8c8c8"
bordercolor="#000000"
borderopacity="0.25"
inkscape:showpageshadow="2"
inkscape:pageopacity="0.0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#d1d1d1"
inkscape:document-units="px"
showgrid="true"
inkscape:zoom="1.7652785"
inkscape:cx="418.06434"
inkscape:cy="114.71278"
inkscape:window-width="3539"
inkscape:window-height="1753"
inkscape:window-x="283"
inkscape:window-y="197"
inkscape:window-maximized="0"
inkscape:current-layer="layer1"><inkscape:grid
id="grid1"
units="px"
originx="-67.859581"
originy="60.971882"
spacingx="0.26458334"
spacingy="0.26458333"
empcolor="#0099e5"
empopacity="0.30196078"
color="#0099e5"
opacity="0.14901961"
empspacing="5"
dotted="false"
gridanglex="30"
gridanglez="30"
visible="true" /></sodipodi:namedview><defs
id="defs1"><rect
x="755.94495"
y="-183.35582"
width="105.00001"
height="74.999985"
id="rect21" /><marker
style="overflow:visible"
id="marker24"
refX="0"
refY="0"
orient="auto-start-reverse"
inkscape:stockid="Wide arrow"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid"><path
style="fill:none;stroke:context-stroke;stroke-width:1;stroke-linecap:butt"
d="M 3,-3 0,0 3,3"
transform="rotate(180,0.125,0)"
sodipodi:nodetypes="ccc"
id="path24" /></marker></defs><g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-67.859589,60.971878)"><rect
style="fill:#778899;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1"
id="rect35"
width="14.305503"
height="20.505203"
x="270.27069"
y="-30.726345"
ry="3.5633614" /><rect
style="fill:#ff7f50;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1"
id="rect20"
width="15.103508"
height="20.505203"
x="210.23834"
y="-30.726345"
ry="3.5633614" /><rect
style="fill:#808000;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1"
id="rect18"
width="20.008406"
height="20.505203"
x="160.56226"
y="-60.721878"
ry="3.5633614" /><rect
style="fill:#b22222;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1"
id="rect14"
width="18.49814"
height="22.822384"
x="161.38226"
y="-1.058338"
ry="3.9660373" /><rect
style="fill:#778899;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1"
id="rect9"
width="18.62851"
height="20.581913"
x="130.91548"
y="-30.7647"
ry="3.5766919" /><rect
style="fill:#ff7f50;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1"
id="rect6"
width="18.493967"
height="20.767418"
x="86.029556"
y="-30.857452"
ry="3.6089289" /><path
id="path3"
style="fill:#7b68ee;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none"
d="m 68.109589,-30.640411 h 13.661258 v 20.333335 H 68.109589 Z" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="75.141678"
y="-21.166664"
id="text7"><tspan
sodipodi:role="line"
id="tspan7"
x="75.141678"
y="-21.166664">find</tspan><tspan
sodipodi:role="line"
x="75.141678"
y="-16.756939"
id="tspan1">pairs</tspan></text><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="95.250015"
y="-21.657593"
id="text11"><tspan
sodipodi:role="line"
id="tspan24"
x="95.250015"
y="-21.657593">create</tspan><tspan
sodipodi:role="line"
id="tspan25"
x="95.250015"
y="-17.247868">contacts</tspan></text><path
id="path27"
style="fill:#1e90ff;stroke:#808080;stroke-width:0.499999"
d="m 109.37187,-30.640411 h 16.71443 v 20.333336 h -16.71443 z" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="117.61639"
y="-22.057625"
id="text28"><tspan
sodipodi:role="line"
id="tspan17"
x="117.61639"
y="-22.057625">narrow</tspan><tspan
sodipodi:role="line"
id="tspan18"
x="117.61639"
y="-17.6479">phase</tspan></text><path
id="path31"
style="fill:#4b0082;fill-opacity:1;stroke:#808080;stroke-width:0.499999"
d="m 154.48219,-30.640412 h 24.29216 v 20.333337 h -24.29216 z" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="166.66187"
y="-21.36344"
id="text33"><tspan
sodipodi:role="line"
id="tspan5"
x="166.66187"
y="-21.36344">solve</tspan><tspan
sodipodi:role="line"
id="tspan6"
x="166.66187"
y="-16.953714">constraints</tspan></text><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="140.17375"
y="-21.715702"
id="text35"><tspan
sodipodi:role="line"
id="tspan14"
x="140.17375"
y="-21.715702">merge</tspan><tspan
sodipodi:role="line"
x="140.17375"
y="-17.305977"
id="tspan3">islands</tspan></text><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="170.50014"
y="-51.358971"
id="text40"><tspan
sodipodi:role="line"
id="tspan40"
x="170.50014"
y="-51.358971">split</tspan><tspan
sodipodi:role="line"
id="tspan41"
x="170.50014"
y="-46.949245">island</tspan></text><path
id="path41"
style="fill:#3cb371;fill-opacity:1;stroke:#808080;stroke-width:0.499999"
d="m 183.92549,-30.640415 h 21.67162 v 20.333343 h -21.67162 z" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="194.82332"
y="-21.36344"
id="text43"><tspan
sodipodi:role="line"
id="tspan46"
x="194.82332"
y="-21.36344">update</tspan><tspan
sodipodi:role="line"
id="tspan47"
x="194.82332"
y="-16.953714">transforms</tspan></text><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="217.85814"
y="-21.36344"
id="text56"><tspan
sodipodi:role="line"
id="tspan20"
x="217.85814"
y="-21.36344">hit</tspan><tspan
sodipodi:role="line"
x="217.85814"
y="-16.953714"
id="tspan13">events</tspan></text><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="277.35712"
y="-21.705366"
id="text57"><tspan
sodipodi:role="line"
id="tspan57"
x="277.35712"
y="-21.705366">island</tspan><tspan
sodipodi:role="line"
id="tspan58"
x="277.35712"
y="-17.295641">sleep</tspan></text><path
id="path62"
style="fill:#6fac46;stroke:#808080;stroke-width:0.5"
d="m 82.564597,-50.216456 a 7.1510454,7.1510454 0 0 1 -7.151046,7.151045 7.1510454,7.1510454 0 0 1 -7.151045,-7.151045 7.1510454,7.1510454 0 0 1 7.151045,-7.151046 7.1510454,7.1510454 0 0 1 7.151046,7.151046 z" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="75.404076"
y="-51.448078"
id="text63"><tspan
sodipodi:role="line"
id="tspan62"
x="75.404076"
y="-51.448078">time</tspan><tspan
sodipodi:role="line"
id="tspan63"
x="75.404076"
y="-47.038353">step</tspan></text><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 75.469385,-42.956776 v 11.897688"
id="path20"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 81.689323,-20.504564 h 3.907019"
id="path21"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 104.57631,-20.504564 h 4.23571"
id="path22"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 178.94826,-20.504564 h 4.33851"
id="path25"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 205.4087,-20.473744 h 4.53759"
id="path26"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
style="fill:none;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 140.46822,-30.890411 -0.01,-19.380421 h 19.5209"
id="path29"
sodipodi:nodetypes="ccc" /><path
style="fill:none;fill-opacity:1;stroke:#808080;stroke-width:0.499999;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 180.57067,-50.270835 h 13.91285 l 1e-5,19.315703"
id="path32"
sodipodi:nodetypes="ccc" /><path
style="fill:none;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="M 95.513855,-10.067654 V 10.604183 H 161.38227"
id="path33"
sodipodi:nodetypes="ccc" /><path
style="fill:none;fill-opacity:1;stroke:#808080;stroke-width:0.499499;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 179.88072,10.604183 h 57.97056 V -9.6234705"
id="path34"
sodipodi:nodetypes="ccc" /><rect
style="fill:#b22222;fill-opacity:1;stroke:#808080;stroke-width:0.5;stroke-dasharray:none;stroke-opacity:1"
id="rect11"
width="13.222318"
height="20.505203"
x="230.69687"
y="-30.726345"
ry="3.5633614" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="237.22104"
y="-21.338463"
id="text12"><tspan
sodipodi:role="line"
id="tspan11"
x="237.22104"
y="-21.338463">refit</tspan><tspan
sodipodi:role="line"
id="tspan12"
x="237.22104"
y="-16.928738">BVH</tspan></text><text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,63.234734,-161.929)"
id="text20"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:13.3333px;line-height:2.3;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;white-space:pre;shape-inside:url(#rect21);display:inline;fill:#ff7f50;fill-opacity:1;stroke:#000000;stroke-width:1.88976" /><path
id="path30"
style="fill:#3cb371;fill-opacity:1;stroke:#808080;stroke-width:0.499999"
d="m 249.29401,-30.640415 h 15.62417 v 20.333343 h -15.62417 z" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="257.11472"
y="-19.158577"
id="text31"><tspan
sodipodi:role="line"
id="tspan31"
x="257.11472"
y="-19.158577">bullets</tspan></text><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 225.53822,-20.473744 h 4.53758"
id="path36"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 244.09338,-20.473744 h 4.53759"
id="path37"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 265.1201,-20.473744 h 4.53758"
id="path38"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
id="path40"
style="fill:#1e90ff;fill-opacity:1;stroke:#808080;stroke-width:0.499999"
d="m 289.92494,-30.640415 h 15.80963 v 20.333343 h -15.80963 z" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="297.82114"
y="-19.510839"
id="text42"><tspan
sodipodi:role="line"
id="tspan42"
x="297.82114"
y="-19.510839">sensors</tspan></text><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 284.72431,-20.473744 h 4.53759"
id="path42"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Hack Nerd Font';-inkscape-font-specification:'Hack Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#ffffff;stroke:none;stroke-width:3"
x="170.56067"
y="9.7186146"
id="text27"><tspan
sodipodi:role="line"
id="tspan15"
x="170.56067"
y="9.7186146">rebuild</tspan><tspan
sodipodi:role="line"
id="tspan16"
x="170.56067"
y="14.12834">BVH</tspan></text><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 126.23425,-20.504564 h 4.23571"
id="path1"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /><path
style="fill:none;fill-rule:evenodd;stroke:#808080;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker24)"
d="m 149.5911,-20.504564 h 4.33851"
id="path2"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0" /></g></svg>

After

Width:  |  Height:  |  Size: 20 KiB

View file

@ -0,0 +1,140 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="322.26855"
height="108.76013"
id="svg5128"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="skin-collision.svg">
<defs
id="defs5130" />
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="2.8"
inkscape:cx="149.63278"
inkscape:cy="38.587018"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1920"
inkscape:window-height="1148"
inkscape:window-x="-8"
inkscape:window-y="-8"
inkscape:window-maximized="1"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata5133">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-178.07143,-467.67348)">
<rect
style="fill:#d7e3f4;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect5140"
width="56.568542"
height="42.426407"
x="314.03363"
y="471.8606"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\SkinCollision.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<path
sodipodi:type="inkscape:offset"
inkscape:radius="3.2142856"
inkscape:original="M 329.9375 406.5 L 329.9375 448.9375 L 386.5 448.9375 L 386.5 406.5 L 329.9375 406.5 z "
style="fill:none;stroke:#7d7d7d;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:1, 3;stroke-dashoffset:0;stroke-opacity:1"
id="path5700"
d="M 329.9375,403.28516 A 3.214607,3.214607 0 0 0 326.72266,406.5 v 42.4375 a 3.214607,3.214607 0 0 0 3.21484,3.21484 H 386.5 a 3.214607,3.214607 0 0 0 3.21484,-3.21484 V 406.5 A 3.214607,3.214607 0 0 0 386.5,403.28516 Z"
transform="translate(-15.980776,64.888322)"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\SkinCollision.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<rect
style="fill:#d7e3f4;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect5138"
width="53.538086"
height="47.477169"
x="319.46075"
y="520.26434"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\SkinCollision.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<path
sodipodi:type="inkscape:offset"
inkscape:radius="3.2926946"
inkscape:original="M 319.75 426.21875 L 319.75 473.6875 L 373.28125 473.6875 L 373.28125 426.21875 L 319.75 426.21875 z "
style="fill:none;stroke:#7d7d7d;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:1, 3;stroke-dashoffset:0;stroke-opacity:1"
id="path5720"
d="m 319.75,422.92578 a 3.2930238,3.2930238 0 0 0 -3.29297,3.29297 v 47.46875 a 3.2930238,3.2930238 0 0 0 3.29297,3.29297 h 53.53125 a 3.2930238,3.2930238 0 0 0 3.29297,-3.29297 v -47.46875 a 3.2930238,3.2930238 0 0 0 -3.29297,-3.29297 z"
transform="translate(-0.59098611,95.046407)"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\SkinCollision.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="M 181.82746,572.53972 H 494.97475"
id="path5136"
inkscape:connector-curvature="0"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\SkinCollision.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<rect
style="fill:none;stroke:#7d7d7d;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:1, 3;stroke-dashoffset:0;stroke-opacity:1"
id="rect5750"
width="321.26855"
height="6.0714283"
x="178.57143"
y="569.86218"
ry="3.0357141"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\SkinCollision.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="393.9595"
y="501.07144"
id="text5770"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\SkinCollision.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545"><tspan
sodipodi:role="line"
id="tspan5772"
x="393.9595"
y="501.07144"
style="font-size:14px;line-height:1.25">Polygons collide</tspan><tspan
sodipodi:role="line"
x="393.9595"
y="518.57141"
id="tspan5774"
style="font-size:14px;line-height:1.25">with their skin</tspan></text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 6.2 KiB

162
docs/images/tunneling1.svg Normal file
View file

@ -0,0 +1,162 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="274.69003"
height="244.50266"
id="svg3938"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="tunnel1.svg">
<defs
id="defs3940">
<marker
inkscape:stockid="Arrow1Lend"
orient="auto"
refY="0"
refX="0"
id="Arrow1Lend"
style="overflow:visible">
<path
id="path4488"
d="M 0,0 5,-5 -12.5,0 5,5 Z"
style="fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;marker-start:none"
transform="matrix(-0.8,0,0,-0.8,-10,0)"
inkscape:connector-curvature="0" />
</marker>
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="0.98994949"
inkscape:cx="42.598267"
inkscape:cy="2.3289626"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1402"
inkscape:window-height="1069"
inkscape:window-x="299"
inkscape:window-y="26"
inkscape:window-maximized="0"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata3943">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-241.98927,-300.82514)">
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 348.57143,300.93361 54.28571,244.28572"
id="path3946"
inkscape:connector-curvature="0"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\Tunnel1.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<path
sodipodi:type="star"
style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="path3952"
sodipodi:sides="5"
sodipodi:cx="144.28571"
sodipodi:cy="343.79074"
sodipodi:r1="37.252586"
sodipodi:r2="30.137976"
sodipodi:arg1="1.0040671"
sodipodi:arg2="1.6323856"
inkscape:flatsided="true"
inkscape:rounded="0"
inkscape:randomized="0"
d="m 164.28571,375.21931 -43.71001,-2.69547 -10.94359,-42.40364 36.94651,-23.51141 33.77777,27.87278 z"
inkscape:transform-center-x="-0.70854843"
inkscape:transform-center-y="-2.876691"
transform="translate(132.85715,125.71429)"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\Tunnel1.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<path
sodipodi:type="star"
style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="path3952-2"
sodipodi:sides="5"
sodipodi:cx="144.28571"
sodipodi:cy="343.79074"
sodipodi:r1="37.252586"
sodipodi:r2="30.137976"
sodipodi:arg1="1.0040671"
sodipodi:arg2="1.6323856"
inkscape:flatsided="true"
inkscape:rounded="0"
inkscape:randomized="0"
d="m 164.28571,375.21931 -43.71001,-2.69547 -10.94359,-42.40364 36.94651,-23.51141 33.77777,27.87278 z"
inkscape:transform-center-x="-1.9942167"
inkscape:transform-center-y="1.6069069"
transform="rotate(22.495262,160.88661,1216.0763)"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\Tunnel1.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<path
style="fill:none;stroke:#000000;stroke-width:1.79999995;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:7.19999981, 7.19999981;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
d="m 290,413.79075 c 27.14286,-48.57142 84.28571,-68.57142 144.28571,-51.42857"
id="path4480"
inkscape:connector-curvature="0"
sodipodi:nodetypes="cc"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\Tunnel1.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="260"
y="533.79077"
id="text5108"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\Tunnel1.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545"><tspan
sodipodi:role="line"
id="tspan5110"
x="260"
y="533.79077"
style="font-size:14px;line-height:1.25">time0</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="466.85715"
y="472.07648"
id="text5112"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\Tunnel1.png"
inkscape:export-xdpi="179.94545"
inkscape:export-ydpi="179.94545"><tspan
sodipodi:role="line"
id="tspan5114"
x="466.85715"
y="472.07648"
style="font-size:14px;line-height:1.25">time1</tspan></text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 6.5 KiB

140
docs/images/tunneling2.svg Normal file
View file

@ -0,0 +1,140 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="234"
height="101.75"
id="svg2"
version="1.1"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
sodipodi:docname="tunneling2.svg"
inkscape:export-filename="D:\Development\Box2D\Box2D\Documentation\images\tunneling.png"
inkscape:export-xdpi="90"
inkscape:export-ydpi="90">
<defs
id="defs4">
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend"
style="overflow:visible">
<path
id="path3648"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6)"
inkscape:connector-curvature="0" />
</marker>
<inkscape:perspective
sodipodi:type="inkscape:persp3d"
inkscape:vp_x="0 : 526.18109 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_z="744.09448 : 526.18109 : 1"
inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
id="perspective10" />
<inkscape:perspective
id="perspective3602"
inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
inkscape:vp_z="1 : 0.5 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_x="0 : 0.5 : 1"
sodipodi:type="inkscape:persp3d" />
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="2"
inkscape:cx="-68"
inkscape:cy="83.750001"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1390"
inkscape:window-height="1038"
inkscape:window-x="50"
inkscape:window-y="50"
inkscape:window-maximized="0"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<metadata
id="metadata7">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-210,-490.36218)">
<rect
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="rect2816"
width="233"
height="13.5"
x="210.5"
y="541.86218" />
<circle
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="path3592"
transform="translate(7.5,3)"
cx="295.25"
cy="494.11218"
r="6.25" />
<circle
style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="path3592-1"
transform="translate(7.5,91.25)"
cx="295.25"
cy="494.11218"
r="6.25" />
<path
style="fill:none;stroke:#000000;stroke-width:0.93691868;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.93691866, 1.87383732;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow2Mend)"
d="M 302.99984,505.33064 V 577.0062"
id="path3616"
inkscape:connector-curvature="0" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
x="319"
y="499.86218"
id="text4066"><tspan
sodipodi:role="line"
id="tspan4068"
x="319"
y="499.86218"
style="font-size:12px;line-height:1.25">t=0</tspan></text>
<text
id="text4070"
y="587.86218"
x="319"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:0%;font-family:Calibri;-inkscape-font-specification:Calibri;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none"
xml:space="preserve"><tspan
sodipodi:role="line"
id="tspan4074"
x="319"
y="587.86218"
style="font-size:12px;line-height:1.25">t=1</tspan></text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 5 KiB

269
docs/layout.xml Normal file
View file

@ -0,0 +1,269 @@
<?xml version="1.0" encoding="UTF-8"?>
<doxygenlayout version="1.0">
<!-- Generated by doxygen 1.10.0 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="topics" visible="yes" title="Reference" intro=""/>
<tab type="modules" visible="yes" title="" intro="">
<tab type="modulelist" visible="yes" title="" intro=""/>
<tab type="modulemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="concepts" visible="yes" title="">
</tab>
<tab type="interfaces" visible="yes" title="">
<tab type="interfacelist" visible="yes" title="" intro=""/>
<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
</tab>
<tab type="classes" visible="yes" title="">
<tab type="classlist" visible="yes" title="" intro=""/>
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="hierarchy" visible="yes" title="" intro=""/>
<tab type="classmembers" visible="yes" title="" intro=""/>
</tab>
<tab type="structs" visible="yes" title="">
<tab type="structlist" visible="yes" title="" intro=""/>
<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
</tab>
<tab type="exceptions" visible="yes" title="">
<tab type="exceptionlist" visible="yes" title="" intro=""/>
<tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
</tab>
<tab type="files" visible="yes" title="">
<tab type="filelist" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="examples" visible="yes" title="" intro=""/>
</navindex>
<!-- Layout definition for a class page -->
<class>
<briefdescription visible="yes"/>
<includes visible="$SHOW_HEADERFILE"/>
<inheritancegraph visible="yes"/>
<collaborationgraph visible="yes"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<services title=""/>
<interfaces title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>
<privatemethods title=""/>
<privatestaticmethods title=""/>
<privateattributes title=""/>
<privatestaticattributes title=""/>
<friends title=""/>
<related title="" subtitle=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<services title=""/>
<interfaces title=""/>
<constructors title=""/>
<functions title=""/>
<related title=""/>
<variables title=""/>
<properties title=""/>
<events title=""/>
</memberdef>
<allmemberslink visible="yes"/>
<usedfiles visible="$SHOW_USED_FILES"/>
<authorsection visible="yes"/>
</class>
<!-- Layout definition for a namespace page -->
<namespace>
<briefdescription visible="yes"/>
<memberdecl>
<nestednamespaces visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<interfaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<concepts visible="yes" title=""/>
<structs visible="yes" title=""/>
<exceptions visible="yes" title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<properties title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<properties title=""/>
</memberdef>
<authorsection visible="yes"/>
</namespace>
<!-- Layout definition for a concept page -->
<concept>
<briefdescription visible="yes"/>
<includes visible="$SHOW_HEADERFILE"/>
<definition visible="yes" title=""/>
<detaileddescription title=""/>
<authorsection visible="yes"/>
</concept>
<!-- Layout definition for a file page -->
<file>
<briefdescription visible="yes"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<includegraph visible="yes"/>
<includedbygraph visible="yes"/>
<sourcelink visible="yes"/>
<memberdecl>
<interfaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<structs visible="yes" title=""/>
<exceptions visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<concepts visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<properties title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<properties title=""/>
</memberdef>
<authorsection/>
</file>
<!-- Layout definition for a group page -->
<group>
<briefdescription visible="yes"/>
<groupgraph visible="yes"/>
<memberdecl>
<nestedgroups visible="yes" title=""/>
<modules visible="yes" title=""/>
<dirs visible="yes" title=""/>
<files visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<concepts visible="yes" title=""/>
<classes visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<pagedocs/>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
</memberdef>
<authorsection visible="yes"/>
</group>
<!-- Layout definition for a C++20 module page -->
<module>
<briefdescription visible="yes"/>
<exportedmodules visible="yes"/>
<memberdecl>
<concepts visible="yes" title=""/>
<classes visible="yes" title=""/>
<enums title=""/>
<typedefs title=""/>
<functions title=""/>
<variables title=""/>
<membergroups title=""/>
</memberdecl>
<detaileddescription title=""/>
<memberdecl>
<files visible="yes"/>
</memberdecl>
</module>
<!-- Layout definition for a directory page -->
<directory>
<briefdescription visible="yes"/>
<directorygraph visible="yes"/>
<memberdecl>
<dirs visible="yes"/>
<files visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
</directory>
</doxygenlayout>

152
docs/loose_ends.md Normal file
View file

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

262
docs/overview.md Normal file
View file

@ -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);
```

5
docs/reading.md Normal file
View file

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

14
docs/recording.md Normal file
View file

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

21
docs/samples.md Normal file
View file

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

2002
docs/simulation.md Normal file

File diff suppressed because it is too large Load diff