Skip to main content

Module bvh

Expand description

Static BVH (Bounding Volume Hierarchy) / AABB-tree builder and traversal.

Provides a deterministic, caller-buffered BVH over 3D AABBs built by Morton-code spatial sorting followed by a median split. (This is not a Surface Area Heuristic build — no per-split surface-area cost is evaluated; see build_recursive, which splits each range at its Morton-sorted median. A true SAH build remains a possible future improvement.) The tree is built once and queried many times — suitable for static scenes.

§Layout

The BVH is stored as a flat array of nodes. Internal nodes store two child indices; leaf nodes store a range of primitive indices. The node array is repr(C) and POD for direct GPU staging.

§Determinism

The builder sorts primitives by Morton code, then recursively partitions each range at its median. Two builds from the same input produce byte-identical node arrays.

Structs§

BvhNode
BVH node: 48 bytes, repr(C), naturally aligned.

Enums§

BvhError
Errors raised by the BVH builder.

Constants§

BVH_NODE_SIZE
Node size in bytes.
MAX_BVH_DEPTH
Maximum BVH depth (bounded by 2^21 primitives → 21 levels).

Functions§

build_bvh_recursive
Build a BVH using the recursive builder (correct, deterministic).
query_closest
Query the BVH for the closest primitive to a point.
query_overlap
Query the BVH for all primitives whose AABB overlaps query_bbox.