scene_bvh

Surface-Area-Heuristic (SAH) split top-down BVH builder for GPU ray tracing in compute shaders. Emits two flat float arrays — nodes and tris — sized for direct upload via compute.writeBuffer. The output layout is binary-compatible with lightmap_bake.shader and probe_bake.shader.

Node encoding (8 floats / 32 bytes per node):

• [0..2] bbox.min.xyz
• [3] leaf-first / inner-left index, encoded as bitcast<f32>(u32)
• [4..6] bbox.max.xyz
• [7] count (0 = inner, n > 0 = leaf with n tris starting at first)

Triangle encoding: 72 floats per triangle, padded for vec4 alignment (see Baking.TRI_FLOATS).

Exports

• SceneBVH.build(triangles: { Triangle }, opts: BuildOpts?) -> BuildResult — build a BVH over world-space triangles. Returns the flat node/tri buffers plus their counts.

Types:

• Triangle = Baking.Triangle (re-exported)
• FloatArray = { number }
• BuildOpts = { maxLeaf: number? } — default maxLeaf = 4.
• BuildResult = { nodes: FloatArray, tris: FloatArray, nodeCount: number, triCount: number }

Usage

local Baking = require("@builtin::systems.globalIllumination.baking")
local SceneBVH = require("@builtin::systems.globalIllumination.scene_bvh")

local geom = Baking.gatherSceneTriangles({})
local bvh = SceneBVH.build(geom.triangles)

compute.writeBuffer("nodes", bvh.nodes)
compute.writeBuffer("tris", bvh.tris)

Notes

• Empty triangle input produces a single-leaf BVH so the resulting buffer is always well-formed. The shader has an early-out for triCount == 0.
• The build uses a 16-bin SAH split along the largest centroid axis. Falls back to a balanced index-array split when SAH finds no useful partition (typically: all centroids coincide).
• Leaves are capped at LEAF_HARD_CAP = 32 triangles to keep the WGSL per-leaf inner loop bounded. opts.maxLeaf controls the normal cap; the hard cap is only hit when SAH bails on a node.
• The triangle stride is generous (16 pad floats reserved at the tail) so future per-tri material data can be added without changing the shader's binding stride.