@woosh/meep-engine 3.11.2 → 3.12.0

package/src/shade/device/mock/SoftwareGPURenderPassEncoder.js

@@ -1,4 +1,6 @@
 import { normalize_dynamic_offsets } from "./normalize_dynamic_offsets.js";
+import { pipeline_immediate_size } from "./pipeline_immediate_size.js";
+import { SoftwareGPUImmediateData } from "./SoftwareGPUImmediateData.js";
 import { SoftwareGPUObjectBase } from "./SoftwareGPUObjectBase.js";
 import { write_pass_timestamp } from "./write_pass_timestamp.js";
 
@@ -79,6 +81,14 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     #scissor = null;
 
+    /**
+     * Immediate data for this pass. Per-encoder state in WebGPU, and a new pass starts over — which
+     * is why it is constructed here rather than carried in from the command encoder.
+     *
+     * @type {SoftwareGPUImmediateData}
+     */
+    #immediates;
+
     #ended = false;
 
     /**
@@ -99,6 +109,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
 
         this.#encoder = encoder;
         this.descriptor = descriptor;
+        this.#immediates = new SoftwareGPUImmediateData(encoder.device.limits.maxImmediateSize);
 
         write_pass_timestamp(descriptor, 'beginningOfPassWriteIndex');
     }
@@ -138,6 +149,22 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
         );
     }
 
+    /**
+     * @param {number} range_offset byte offset into the immediate data range
+     * @param {ArrayBuffer|ArrayBufferView} data
+     * @param {number} [data_offset] in elements if `data` is a TypedArray, bytes otherwise
+     * @param {number} [data_size] in elements if `data` is a TypedArray, bytes otherwise
+     */
+    setImmediates(range_offset, data, data_offset = 0, data_size) {
+        this.#assert_encoding();
+
+        const message = this.#immediates.write(range_offset, data, data_offset, data_size);
+
+        if (message !== null) {
+            this.#encoder.notify_pass_validation_error(message);
+        }
+    }
+
     /**
      * @param {number} slot
      * @param {GPUBuffer} buffer
@@ -206,6 +233,24 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
         this.stencil_reference = reference;
     }
 
+    /**
+     * WebGPU's *Validate immediate data*: every slot the pipeline's immediate range covers must have
+     * been written before a command reads it. The bytes default to zero but the slots do not default
+     * to set, so a forgotten `setImmediates` is a refused draw on a real device rather than a shader
+     * quietly reading zeroes. Catching it here is the whole reason the slot bookkeeping exists.
+     *
+     * @returns {void}
+     */
+    #validate_immediates() {
+        const size = pipeline_immediate_size(this.#pipeline);
+
+        if (size > 0 && !this.#immediates.isRangeSet(0, size)) {
+            this.#encoder.notify_pass_validation_error(
+                `draw: pipeline declares ${size} bytes of immediate data, and not all of it was set by setImmediates`
+            );
+        }
+    }
+
     /**
      * The state a draw would run under, copied so later state changes do not rewrite a draw already
      * recorded.
@@ -221,6 +266,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
             index_buffer: this.#index_buffer,
             viewport: this.#viewport,
             scissor: this.#scissor,
+            immediates: this.#immediates.snapshot(),
         };
     }
 
@@ -230,6 +276,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     draw(vertex_count, instance_count = 1) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.draws.push({
             ...this.#snapshot(),
@@ -246,6 +293,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     drawIndexed(index_count, instance_count = 1) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.draws.push({
             ...this.#snapshot(),
@@ -262,6 +310,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     drawIndirect(indirect_buffer, indirect_offset) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.draws.push({
             ...this.#snapshot(),
@@ -281,6 +330,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     drawIndexedIndirect(indirect_buffer, indirect_offset) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.draws.push({
             ...this.#snapshot(),

package/src/shade/device/mock/pipeline_immediate_size.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bytes of immediate data a pipeline's layout declares, or 0 when it declares none.
+ *
+ * A pipeline built with `layout: "auto"` reports 0 rather than deriving a size: deriving one would
+ * mean reading the WGSL, and nothing in this folder compiles WGSL.
+ *
+ * @param {GPUPipelineBase|null} pipeline
+ * @returns {number}
+ */
+export function pipeline_immediate_size(pipeline: GPUPipelineBase | null): number;
+//# sourceMappingURL=pipeline_immediate_size.d.ts.map

package/src/shade/device/mock/pipeline_immediate_size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline_immediate_size.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/pipeline_immediate_size.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,kDAHW,kBAAgB,IAAI,GAClB,MAAM,CAUlB"}

package/src/shade/device/mock/pipeline_immediate_size.js

@@ -0,0 +1,18 @@
+/**
+ * Bytes of immediate data a pipeline's layout declares, or 0 when it declares none.
+ *
+ * A pipeline built with `layout: "auto"` reports 0 rather than deriving a size: deriving one would
+ * mean reading the WGSL, and nothing in this folder compiles WGSL.
+ *
+ * @param {GPUPipelineBase|null} pipeline
+ * @returns {number}
+ */
+export function pipeline_immediate_size(pipeline) {
+    const layout = pipeline?.descriptor?.layout;
+
+    if (layout === undefined || layout === null || layout === "auto") {
+        return 0;
+    }
+
+    return layout.immediateSize ?? 0;
+}

package/src/shade/device/pipeline/PipelineLayoutManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PipelineLayoutManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/PipelineLayoutManager.js"],"names":[],"mappings":"AAGA;IAMI;;;OAGG;IACH,+BAEC;IAoBD;;;;OAIG;IACH,2DAFa,4BAA0B,SAAS,CAI/C;IAgBD;;;;OAIG;IACH,iFAKC;IAED;;;;OAIG;IACH,8EAEC;;CAkBJ"}
+{"version":3,"file":"PipelineLayoutManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/PipelineLayoutManager.js"],"names":[],"mappings":"AAGA;IAMI;;;OAGG;IACH,+BAEC;IAoBD;;;;OAIG;IACH,2DAFa,4BAA0B,SAAS,CAI/C;IAgBD;;;;OAIG;IACH,iFAKC;IAED;;;;OAIG;IACH,8EAEC;;CAmBJ"}

package/src/shade/device/pipeline/PipelineLayoutManager.js

@@ -89,6 +89,7 @@ export class PipelineLayoutManager {
         return this.#device.createPipelineLayout({
             label: descriptor.label,
             bindGroupLayouts,
+            immediateSize: descriptor.immediateSize,
         });
 
     }

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAqBA,2CAA4C;AA4D5C;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAOpB;8BApG2B,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAqBA,2CAA4C;AA4D5C;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAMpB;8BAnG2B,wCAAwC"}

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js

@@ -100,5 +100,4 @@ export const shader_blas_audit_leaf_triangles = ComputeShader.from({
     label: "BLAS/AuditLeafTriangles",
     resources,
     body,
-    group_size: [BLAS_AUDIT_WORKGROUP_SIZE, 1, 1],
 });

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_points.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_points.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_points.js"],"names":[],"mappings":"AAkBA,4CAA6C;AAE7C;;GAEG;AACH,0CAFU,YAAY,CAOG;AA8CzB;;;;;;;;;;;;;GAaG;AACH,uCAFU,aAAa,CAOpB;6BA3F0B,4CAA4C;8BAE3C,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_points.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_points.js"],"names":[],"mappings":"AAkBA,4CAA6C;AAE7C;;GAEG;AACH,0CAFU,YAAY,CAOG;AA8CzB;;;;;;;;;;;;;GAaG;AACH,uCAFU,aAAa,CAMpB;6BA1F0B,4CAA4C;8BAE3C,wCAAwC"}

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_points.js

@@ -90,5 +90,4 @@ export const shader_blas_audit_points = ComputeShader.from({
     label: "BLAS/AuditPoints",
     resources,
     body,
-    group_size: [BLAS_POINTS_WORKGROUP_SIZE, 1, 1],
 });

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_visibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_visibility.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_visibility.js"],"names":[],"mappings":"AAyBA,gDAAiD;AAEjD;;GAEG;AACH,8CAFU,YAAY,CASO;AA0E7B;;;;;;;;;;;;;;;;GAgBG;AACH,2CAFU,aAAa,CAOpB;6BAnI0B,4CAA4C;8BAE3C,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_visibility.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_visibility.js"],"names":[],"mappings":"AAyBA,gDAAiD;AAEjD;;GAEG;AACH,8CAFU,YAAY,CASO;AA0E7B;;;;;;;;;;;;;;;;GAgBG;AACH,2CAFU,aAAa,CAMpB;6BAlI0B,4CAA4C;8BAE3C,wCAAwC"}

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_visibility.js

@@ -1,134 +1,133 @@
-import { f32, u32, vec3f } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
-import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    BVH_NODE_CHILD_2_WORD,
-    BVH_NODE_STRIDE_WORDS
-} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
-import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { BVH_TRAVERSAL_STACK_SIZE } from "../../renderer/shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
-import {
-    chunk_ray_query_blas_nearest
-} from "../../renderer/shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
-import {
-    chunk_geometry_read_triangle_vertices
-} from "../../renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_vertices.js";
-import { RAY_STRUCT } from "../../renderer/shader/chunk/geometry/ray/RAY_STRUCT.js";
-import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
-import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../renderer/geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
-import {
-    MESHLET_METADATA_STRUCT
-} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-
-export const BLAS_VISIBILITY_WORKGROUP_SIZE = 64;
-
-/**
- * @type {WebGPUStruct}
- */
-export const BLAS_VISIBILITY_SETTINGS_STRUCT = WebGPUStruct.from({
-    origin: vec3f,
-    leaf_count: u32,
-    node_word_offset: u32,
-    leaf_nodes_offset: u32,
-    geometry_index: u32,
-    tmax: f32,
-}, "BlasVisibilitySettings");
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addUniform("settings", BLAS_VISIBILITY_SETTINGS_STRUCT)
-    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
-    .addStorageBuffer("blas_lookup", WebGPUArray.from(u32), false)
-    .addStorageBuffer("blas_data", WebGPUArray.from(BVH2_NODE_STRUCT), false)
-    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
-    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
-    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE, false)
-    .addStorageBuffer("nodes", WebGPUArray.from(f32), false)
-    // per leaf: the parametric t the traversal came back with, negative for a miss
-    .addStorageBuffer("out_t", WebGPUArray.from(f32), true)
-    // per leaf: the triangle the traversal returned, or 0xFFFFFFFF
-    .addStorageBuffer("out_triangle", WebGPUArray.from(u32), true)
-    // per leaf: the distance to the point the ray was aimed at, which the answer cannot exceed
-    .addStorageBuffer("out_expected_t", WebGPUArray.from(f32), true);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
-const NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
-
-@compute @workgroup_size(${BLAS_VISIBILITY_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
-    let i = gid.x;
-
-    if (i >= settings.leaf_count) {
-        return;
-    }
-
-    let leaf_node = leaf_nodes[settings.leaf_nodes_offset + i];
-
-    let node_word = settings.node_word_offset + leaf_node * NODE_STRIDE;
-
-    let meshlet_triangle_id = bitcast<u32>(nodes[node_word + NODE_CHILD_2]);
-
-    let triangle = geometry_read_triangle_vertices(
-        geometries[settings.geometry_index],
-        meshlet_triangle_id
-    );
-
-    // Aim at the triangle's own centroid, which is strictly inside it. The ray provably intersects
-    // this triangle, so the traversal has to come back with *something* — this one, or something
-    // occluding it. A miss is not a geometric possibility; it is the traversal failing to reach a
-    // leaf whose box, by construction, the ray passes through.
-    let centre = (triangle.a.position + triangle.b.position + triangle.c.position) / 3.0;
-
-    var ray: ${RAY_STRUCT.wgsl_ref};
-
-    ray.origin = settings.origin;
-    ray.direction = normalize(centre - settings.origin);
-    ray.tmax = settings.tmax;
-
-    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
-
-    let hit = ray_query_blas_nearest(ray, settings.geometry_index, &stack, 0u);
-
-    out_t[i] = hit.t;
-    out_triangle[i] = select(0xFFFFFFFFu, hit.triangle, hit.t >= 0.0);
-
-    // The ray was aimed at a point on this triangle, so the nearest surface along it is at most
-    // this far. An answer beyond it is not an occlusion and not a miss — it is the traversal
-    // walking past a surface it was pointed at, which is what a hole in the traced image is.
-    out_expected_t[i] = length(centre - settings.origin);
-}
-`, [
-    RAY_STRUCT.declaration_chunk,
-    chunk_geometry_read_triangle_vertices,
-    chunk_ray_query_blas_nearest,
-]);
-
-/**
- * Ask the traversal, once per triangle, whether it can find that triangle.
- *
- * Every structural check on the tree has passed, which narrows the fault to the traversal itself —
- * and traversal is the one thing no readback of the tree can exercise. So this runs the real
- * `ray_query_blas_nearest`, the same function the path tracer calls, along a ray whose answer is
- * known in advance.
- *
- * The ray goes from the camera to a triangle's centroid. That point is inside the triangle, so the
- * ray intersects it, so the query must return a hit — this triangle if nothing is in front, some
- * other one if something is. Only a miss is impossible, and a miss is therefore a traversal that
- * failed to reach a leaf whose box it was inside.
- *
- * Which triangles miss, and where they are, is the whole diagnosis.
- *
- * @type {ComputeShader}
- */
-export const shader_blas_audit_visibility = ComputeShader.from({
-    label: "BLAS/AuditVisibility",
-    resources,
-    body,
-    group_size: [BLAS_VISIBILITY_WORKGROUP_SIZE, 1, 1],
-});
+import { f32, u32, vec3f } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { BVH_TRAVERSAL_STACK_SIZE } from "../../renderer/shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
+import {
+    chunk_ray_query_blas_nearest
+} from "../../renderer/shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
+import {
+    chunk_geometry_read_triangle_vertices
+} from "../../renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_vertices.js";
+import { RAY_STRUCT } from "../../renderer/shader/chunk/geometry/ray/RAY_STRUCT.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../renderer/geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+
+export const BLAS_VISIBILITY_WORKGROUP_SIZE = 64;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BLAS_VISIBILITY_SETTINGS_STRUCT = WebGPUStruct.from({
+    origin: vec3f,
+    leaf_count: u32,
+    node_word_offset: u32,
+    leaf_nodes_offset: u32,
+    geometry_index: u32,
+    tmax: f32,
+}, "BlasVisibilitySettings");
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("settings", BLAS_VISIBILITY_SETTINGS_STRUCT)
+    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
+    .addStorageBuffer("blas_lookup", WebGPUArray.from(u32), false)
+    .addStorageBuffer("blas_data", WebGPUArray.from(BVH2_NODE_STRUCT), false)
+    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
+    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
+    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE, false)
+    .addStorageBuffer("nodes", WebGPUArray.from(f32), false)
+    // per leaf: the parametric t the traversal came back with, negative for a miss
+    .addStorageBuffer("out_t", WebGPUArray.from(f32), true)
+    // per leaf: the triangle the traversal returned, or 0xFFFFFFFF
+    .addStorageBuffer("out_triangle", WebGPUArray.from(u32), true)
+    // per leaf: the distance to the point the ray was aimed at, which the answer cannot exceed
+    .addStorageBuffer("out_expected_t", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
+const NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
+
+@compute @workgroup_size(${BLAS_VISIBILITY_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let i = gid.x;
+
+    if (i >= settings.leaf_count) {
+        return;
+    }
+
+    let leaf_node = leaf_nodes[settings.leaf_nodes_offset + i];
+
+    let node_word = settings.node_word_offset + leaf_node * NODE_STRIDE;
+
+    let meshlet_triangle_id = bitcast<u32>(nodes[node_word + NODE_CHILD_2]);
+
+    let triangle = geometry_read_triangle_vertices(
+        geometries[settings.geometry_index],
+        meshlet_triangle_id
+    );
+
+    // Aim at the triangle's own centroid, which is strictly inside it. The ray provably intersects
+    // this triangle, so the traversal has to come back with *something* — this one, or something
+    // occluding it. A miss is not a geometric possibility; it is the traversal failing to reach a
+    // leaf whose box, by construction, the ray passes through.
+    let centre = (triangle.a.position + triangle.b.position + triangle.c.position) / 3.0;
+
+    var ray: ${RAY_STRUCT.wgsl_ref};
+
+    ray.origin = settings.origin;
+    ray.direction = normalize(centre - settings.origin);
+    ray.tmax = settings.tmax;
+
+    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
+
+    let hit = ray_query_blas_nearest(ray, settings.geometry_index, &stack, 0u);
+
+    out_t[i] = hit.t;
+    out_triangle[i] = select(0xFFFFFFFFu, hit.triangle, hit.t >= 0.0);
+
+    // The ray was aimed at a point on this triangle, so the nearest surface along it is at most
+    // this far. An answer beyond it is not an occlusion and not a miss — it is the traversal
+    // walking past a surface it was pointed at, which is what a hole in the traced image is.
+    out_expected_t[i] = length(centre - settings.origin);
+}
+`, [
+    RAY_STRUCT.declaration_chunk,
+    chunk_geometry_read_triangle_vertices,
+    chunk_ray_query_blas_nearest,
+]);
+
+/**
+ * Ask the traversal, once per triangle, whether it can find that triangle.
+ *
+ * Every structural check on the tree has passed, which narrows the fault to the traversal itself —
+ * and traversal is the one thing no readback of the tree can exercise. So this runs the real
+ * `ray_query_blas_nearest`, the same function the path tracer calls, along a ray whose answer is
+ * known in advance.
+ *
+ * The ray goes from the camera to a triangle's centroid. That point is inside the triangle, so the
+ * ray intersects it, so the query must return a hit — this triangle if nothing is in front, some
+ * other one if something is. Only a miss is impossible, and a miss is therefore a traversal that
+ * failed to reach a leaf whose box it was inside.
+ *
+ * Which triangles miss, and where they are, is the whole diagnosis.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_audit_visibility = ComputeShader.from({
+    label: "BLAS/AuditVisibility",
+    resources,
+    body,
+});