Interface TraceModuleOptions

Which child any-hit enters first when the ray hits both, compiled in like rayMasks (see AnyHitOrder). Default 'far'. Closest-hit always enters the nearer one. Answers are the same either way.

The counted walk (walk-counters.ts), compiled in beside the walk: bvhTraceClosestCounted(ray) and bvhTraceAnyCounted(ray) (and their *Masked(ray, mask) forms unless rayMasks: false) return a BvhWalkCounts: the hit (t, instance, triangle) and the walk's work (steps, meshNodes, topLevelNodes, instanceEntries, triangleTests, instancesWithHit), for heat maps and tools. The same walk with counters added, so the same hits. Default false: nothing is added, and the module is the same text; with it, every other declaration is the same text too.

The scene's node format (docs/internals/design/compressed-nodes.md), compiled in like rayMasks: 'quantized' (the default, DEFAULT_NODE_FORMAT: 32-byte nodes decoded on the frame read once per instance entered) or 'f32' (64-byte nodes). It must match the buffers: a scene assembled or a SceneTrees made without a nodeFormat is quantized too; pass SceneTrees.nodeFormat or TraceSceneData.nodeFormat to be sure. Only bvhLoadMeshNode and the instance entry's frame read differ; it is the same walk, with the same bindings.

Indexed only: the positions buffer's layout, 'vec4' (the default) or 'packed'.

How the ray walk decodes quantized mesh nodes, compiled in like rayMasks (see QuantizedDecode). Default 'exact': the walk's text is unchanged. 'folded' needs nodeFormat: 'quantized' and an anyHitOrder other than 'larger'.

The spatial queries (query-wgsl.ts; docs/tracing/gpu-queries.mdx), compiled in beside the walk: bvhClosestPoint(point, maxDistance) -> BvhClosestHit, bvhIntersectsSphere(center, radius), bvhIntersectsBox(boxMin, boxMax) and bvhIntersectsOrientedBox(center, halfSize, rotation), and the inside test, bvhRayCrossings(origin, direction), bvhInsideVotes(point) and bvhIsInside(point) (docs/tracing/sdf.mdx), with *Masked forms unless rayMasks: false. Default false: the module is the ray walk alone, as before the queries existed.

Instance masks against ray masks. Default true: the module also has bvhTraceClosestMasked(ray, mask) and bvhTraceAnyMasked(ray, mask), and the walk skips an instance whose (instanceMask & rayMask) == 0. False compiles masks out: no *Masked functions, no mask test in the walk, instance masks are ignored, and the filter sees rayMask as all ones. It is the same walk either way, with the mask code left out.

A shapecast over the caller's hooks: WGSL declaring

fn bvhShapecastBounds(bounds: BvhShapecastBounds) -> f32   // < 0 skips the box; else a score, the lower entered first
fn bvhShapecastKeep(score: f32) -> bool                    // asked when a pushed box is popped; false skips it
fn bvhShapecastTriangle(triangle: BvhShapecastTriangle) -> bool   // true stops the cast

which the module includes, with bvhShapecast() -> bool (and bvhShapecastMasked(mask)) walking the scene with them in world space. '' compiles the walk with the hooks left for the kernel to declare. Default: no shapecast.

Where the module's three bindings land. Default: group 0, bindings 0-2.

The triangle filter, fn bvhTrianglePasses(candidate: BvhCandidate) -> bool, included in the module. Default: DEFAULT_TRIANGLE_FILTER_WGSL (every triangle blocks). null leaves it out, for a kernel that declares bvhTrianglePasses itself. It must not call a walk (bvhTrace*, bvhClosestPoint, bvhIntersects*, bvhShapecast): a nested walk overwrites the private node frame of quantized nodes that the outer walk is still reading.

The scene's triangle format (docs/internals/design/indexed-leaves.md), compiled in like rayMasks: 'records' (the default, 48-byte records, three bindings) or 'indexed' (16-byte indexed triangles read through the scene's positions buffer, a fourth binding after the top level, TRACE_MODULE_ENTRIES_INDEXED). Only the triangle loading differs; it is the same walk.