@woosh/meep-engine 3.68.0 → 3.70.0

package/src/shade/renderer/rasterize/native/avboit/graph_avboit_unlit.js

@@ -0,0 +1,306 @@
+import { assert } from "../../../../../core/assert.js";
+import { GPUTextureUsage } from "../../../../descriptor/GPUTextureUsage.js";
+import { TextureViewDescriptor } from "../../../../descriptor/texture/TextureViewDescriptor.js";
+import { TextureResourceDescriptor } from "../../../../device/graph/TextureResourceDescriptor.js";
+import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../../../depth/DEFAULT_DEPTH_TEXTURE_VIEW.js";
+import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../../../STATIC_GRAPHICS_ENGINE_ASSETS.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../../../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { AVBOIT_UNLIT_DRAW_PASS_GROUP } from "./avboit_unlit_draw.js";
+import { AVBOIT_UNLIT_SPLAT_PASS_GROUP, AVBOIT_UNLIT_SPLAT_SAMPLES } from "./avboit_unlit_splat.js";
+import { AVBOIT_SPLAT_DUMMY_FORMAT, AVBOIT_SPLAT_VOLUME_GROUP } from "./shader_avboit_splat.js";
+
+/**
+ * The passes an `AVBOITSideChannel` of unlit straight-alpha geometry records for its splat and its draw,
+ * with everything but the draws themselves in one place: the attachments, the multisampled target of
+ * the splat, the pass-level bind groups and the frame-graph reads and writes. A channel supplies a
+ * pipeline built by `avboit_unlit_splat_pipeline` / `avboit_unlit_draw_pipeline`, the graph handles its
+ * own draws read, and a `record` callback that issues them; the dynamic meshes and the trails draw
+ * through the same passes this way, with different vertex stages.
+ *
+ * Order does not matter to either pass — the volume and the accumulators are sums — which is why
+ * nothing here sorts.
+ */
+
+/** The accumulators' and the splat target's view: one mip, the one the frame draws into. */
+const COLOR_VIEW = TextureViewDescriptor.from({ mipLevelCount: 1, baseMipLevel: 0 });
+
+/**
+ * @param {import("../../../shader/resource/ShaderResourceSetDescriptor.js").ShaderResourceSetDescriptor} resources
+ * @param {import("../../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
+ * @returns {number} where the shader declares `group`
+ */
+function group_index(resources, group) {
+    const index = resources.groups.indexOf(group);
+
+    assert.notEqual(index, -1, "the shader does not bind this pass group");
+
+    return index;
+}
+
+/**
+ * Read every handle of `inputs` in `pass`, keeping the names.
+ *
+ * @param {object} pass the pass builder
+ * @param {Object<string, number>} inputs
+ * @returns {Object<string, number>} the handles as the pass reads them
+ */
+function read_inputs(pass, inputs) {
+    const read = {};
+
+    for (const name of Object.keys(inputs)) {
+        read[name] = pass.read(inputs[name]);
+    }
+
+    return read;
+}
+
+/**
+ * @param {Object<string, number>} handles
+ * @param {object} resources the pass's resolved resources
+ * @returns {Object<string, *>} the same names, resolved
+ */
+function resolve_inputs(handles, resources) {
+    const resolved = {};
+
+    for (const name of Object.keys(handles)) {
+        resolved[name] = resources.get(handles[name]);
+    }
+
+    return resolved;
+}
+
+/**
+ * Splat a channel's unlit geometry into the voxel volume.
+ *
+ * The raster is multisampled ({@link AVBOIT_UNLIT_SPLAT_SAMPLES}), so it cannot use the volume's
+ * single-sampled splat target: the pass makes its own at the volume's resolution, never written,
+ * cleared and discarded, and hands the volume's back untouched.
+ *
+ * @param {object} params
+ * @param {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {string} params.label the pass's label; its target is labelled after it
+ * @param {import("../../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} params.pipeline
+ * from `avboit_unlit_splat_pipeline`
+ * @param {import("../../../shader/resource/ShaderResourceSetDescriptor.js").ShaderResourceSetDescriptor} params.resources
+ * the pipeline's shader resources
+ * @param {Object<string, number>} params.inputs graph handles the channel's draws read, by name
+ * @param {number} params.warp graph handle
+ * @param {number[]} params.voxel_resolution the volume's width and height, which the raster is
+ * @param {{extinction: number, overflow: number, dummy: number}} params.volume the volume, to add to
+ * @param {function(): boolean} params.is_empty asked when the pass executes; `true` records no render pass
+ * @param {function(GPURenderPassEncoder, GraphicsContext, Object<string, *>): void} params.record issues
+ * the draws into the open pass, whose pass-level groups are set, with `inputs` resolved
+ * @returns {{extinction: number, overflow: number, dummy: number}} the volume after the write
+ */
+export function graph_avboit_unlit_splat({
+                                             graph,
+                                             label,
+                                             pipeline,
+                                             resources,
+                                             inputs,
+                                             warp,
+                                             voxel_resolution,
+                                             volume,
+                                             is_empty,
+                                             record,
+                                         }) {
+    assert.isString(label, "label");
+    assert.isNonNegativeInteger(warp, "warp");
+    assert.isArrayLike(voxel_resolution, "voxel_resolution");
+    assert.defined(volume, "volume");
+    assert.isFunction(is_empty, "is_empty");
+    assert.isFunction(record, "record");
+
+    const pass_group_index = group_index(resources, AVBOIT_UNLIT_SPLAT_PASS_GROUP);
+    const volume_group_index = group_index(resources, AVBOIT_SPLAT_VOLUME_GROUP);
+
+    function execute(data, frame_resources, context) {
+        const encoder = context.encoder;
+        const graphics = context.graphics;
+
+        if (is_empty()) {
+            return;
+        }
+
+        // By name, never by position (AVBOIT ledger entry 21): the order a shader declares its
+        // bindings in is the shader's business.
+        const pass_group = AVBOIT_UNLIT_SPLAT_PASS_GROUP.generateBindings({
+            warp: frame_resources.get(data.warp),
+        }, encoder);
+
+        const volume_group = AVBOIT_SPLAT_VOLUME_GROUP.generateBindings({
+            extinction_volume: frame_resources.get(data.extinction),
+            overflow_slice: frame_resources.get(data.overflow),
+        }, encoder);
+
+        // the target is never written; it only sizes the raster and gives it its samples
+        const pass_encoder = encoder.constructRenderPass({
+            label,
+            pipeline,
+            // the pass's groups are set once, just below; the draws set their own
+            bindings: [],
+            colorAttachments: [{
+                view: frame_resources.get(data.target).obtainView(COLOR_VIEW),
+                loadOp: "clear",
+                storeOp: "discard",
+            }],
+        });
+
+        graphics.setPipelineBindGroup(pass_encoder, pipeline, pass_group_index, pass_group);
+        graphics.setPipelineBindGroup(pass_encoder, pipeline, volume_group_index, volume_group);
+
+        record(pass_encoder, graphics, resolve_inputs(data.inputs, frame_resources));
+
+        pass_encoder.end();
+    }
+
+    const pass_data = {};
+    const pass = graph.add(label, pass_data, execute);
+
+    pass_data.inputs = read_inputs(pass, inputs);
+    pass_data.warp = pass.read(warp);
+
+    pass.read(volume.extinction);
+    pass_data.extinction = pass.write(volume.extinction);
+    pass.read(volume.overflow);
+    pass_data.overflow = pass.write(volume.overflow);
+
+    const target = TextureResourceDescriptor.from({
+        resolution: voxel_resolution,
+        format: AVBOIT_SPLAT_DUMMY_FORMAT,
+        usage: GPUTextureUsage.RENDER_ATTACHMENT,
+    });
+
+    // `from` takes no sample count
+    target.sampleCount = AVBOIT_UNLIT_SPLAT_SAMPLES;
+
+    pass_data.target = pass.create(`${label} target`, target);
+
+    return {
+        extinction: pass_data.extinction,
+        overflow: pass_data.overflow,
+        // not this pass's to touch
+        dummy: volume.dummy,
+    };
+}
+
+/**
+ * Draw a channel's unlit geometry into the four accumulators, depth-tested against the opaque scene.
+ *
+ * @param {object} params
+ * @param {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {string} params.label
+ * @param {import("../../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} params.pipeline
+ * from `avboit_unlit_draw_pipeline`
+ * @param {import("../../../shader/resource/ShaderResourceSetDescriptor.js").ShaderResourceSetDescriptor} params.resources
+ * the pipeline's shader resources
+ * @param {Object<string, number>} params.inputs graph handles the channel's draws read, by name
+ * @param {import("../../../view/GPUViewContext.js").GPUViewContext} params.view_ctx
+ * @param {number} params.depth_texture graph handle of the opaque scene's depth — tested, never written
+ * @param {number} params.warp graph handle
+ * @param {number} params.integral graph handle of the integral texture
+ * @param {number} params.volumetrics_lut graph handle
+ * @param {number} params.volumetrics_metadata graph handle
+ * @param {{color: number, norm: number, extinction: number, emission: number}} params.accumulators to add to
+ * @param {function(): boolean} params.is_empty asked when the pass executes; `true` records no render pass
+ * @param {function(GPURenderPassEncoder, GraphicsContext, Object<string, *>): void} params.record issues
+ * the draws into the open pass, whose pass-level group is set, with `inputs` resolved
+ * @returns {{color: number, norm: number, extinction: number, emission: number}} the accumulators after the draw
+ */
+export function graph_avboit_unlit_draw({
+                                            graph,
+                                            label,
+                                            pipeline,
+                                            resources,
+                                            inputs,
+                                            view_ctx,
+                                            depth_texture,
+                                            warp,
+                                            integral,
+                                            volumetrics_lut,
+                                            volumetrics_metadata,
+                                            accumulators,
+                                            is_empty,
+                                            record,
+                                        }) {
+    assert.isString(label, "label");
+    assert.isNonNegativeInteger(depth_texture, "depth_texture");
+    assert.isNonNegativeInteger(warp, "warp");
+    assert.isNonNegativeInteger(integral, "integral");
+    assert.defined(accumulators, "accumulators");
+    assert.isFunction(is_empty, "is_empty");
+    assert.isFunction(record, "record");
+
+    const pass_group_index = group_index(resources, AVBOIT_UNLIT_DRAW_PASS_GROUP);
+
+    function execute(data, frame_resources, context) {
+        const encoder = context.encoder;
+        const graphics = context.graphics;
+
+        if (is_empty()) {
+            return;
+        }
+
+        // by name rather than by position, for the reason the splat gives
+        const pass_group = AVBOIT_UNLIT_DRAW_PASS_GROUP.generateBindings({
+            view: view_ctx.uniform_buffer.buffer,
+            warp: frame_resources.get(data.warp),
+            tIntegral: frame_resources.get(data.integral).obtainView(),
+            sLinear: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE),
+            volumetrics_metadata: frame_resources.get(data.volumetrics_metadata),
+            tVolumetrics: frame_resources.get(data.volumetrics_lut).obtainView(),
+            tSTBN_vec3: graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3).obtainView(),
+        }, encoder);
+
+        const attachment = (handle) => ({
+            view: frame_resources.get(handle).obtainView(COLOR_VIEW),
+            loadOp: "load",
+            storeOp: "store",
+        });
+
+        const pass_encoder = encoder.constructRenderPass({
+            label,
+            pipeline,
+            // the pass's group is set once, just below; the draws set their own
+            bindings: [],
+            colorAttachments: [
+                attachment(data.color),
+                attachment(data.norm),
+                attachment(data.extinction),
+                attachment(data.emission),
+            ],
+            depthStencilAttachment: {
+                view: frame_resources.get(data.depth).obtainView(DEFAULT_DEPTH_TEXTURE_VIEW),
+                depthReadOnly: true,
+            },
+        });
+
+        graphics.setPipelineBindGroup(pass_encoder, pipeline, pass_group_index, pass_group);
+
+        record(pass_encoder, graphics, resolve_inputs(data.inputs, frame_resources));
+
+        pass_encoder.end();
+    }
+
+    const pass_data = {};
+    const pass = graph.add(label, pass_data, execute);
+
+    pass_data.inputs = read_inputs(pass, inputs);
+    pass_data.depth = pass.read(depth_texture);
+    pass_data.warp = pass.read(warp);
+    pass_data.integral = pass.read(integral);
+    pass_data.volumetrics_lut = pass.read(volumetrics_lut);
+    pass_data.volumetrics_metadata = pass.read(volumetrics_metadata);
+
+    for (const name of ["color", "norm", "extinction", "emission"]) {
+        pass.read(accumulators[name]);
+        pass_data[name] = pass.write(accumulators[name]);
+    }
+
+    return {
+        color: pass_data.color,
+        norm: pass_data.norm,
+        extinction: pass_data.extinction,
+        emission: pass_data.emission,
+    };
+}

package/src/shade/renderer/rasterize/native/avboit/shader_avboit_splat.d.ts

@@ -10,11 +10,20 @@ export const AVBOIT_SPLAT_BIND_GROUP_VOLUME: number;
  * @type {GPUTextureFormat}
  */
 export const AVBOIT_SPLAT_DUMMY_FORMAT: GPUTextureFormat;
+/**
+ * The voxel volume a splat adds its extinction into: the packed counts and the per-channel first
+ * overflow, both atomics, so fragment-only. Every splat that writes through `avboit_splat_slice` binds
+ * this group.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const AVBOIT_SPLAT_VOLUME_GROUP: ShaderResourceGroupDescriptor;
 /**
  * One pipeline per template that can be drawn forward.
  *
  * @type {TemplatePassDescriptor}
  */
 export const shader_avboit_splat: TemplatePassDescriptor;
+import { ShaderResourceGroupDescriptor } from "../../../shader/resource/ShaderResourceGroupDescriptor.js";
 import { TemplatePassDescriptor } from "../../TemplatePassDescriptor.js";
 //# sourceMappingURL=shader_avboit_splat.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/shader_avboit_splat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/shader_avboit_splat.js"],"names":[],"mappings":"AA8BA;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;GAIG;AACH,yDAAmD;AA8HnD;;;;GAIG;AACH,kCAFU,sBAAsB,CA+B7B;uCApLoC,iCAAiC"}
+{"version":3,"file":"shader_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/shader_avboit_splat.js"],"names":[],"mappings":"AA8BA;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;GAIG;AACH,yDAAmD;AASnD;;;;;;GAMG;AACH,wCAFU,6BAA6B,CAEsC;AAqH7E;;;;GAIG;AACH,kCAFU,sBAAsB,CA+B7B;8CArM2C,2DAA2D;uCAUlE,iCAAiC"}

package/src/shade/renderer/rasterize/native/avboit/shader_avboit_splat.js

@@ -49,14 +49,21 @@ view_group
     .addStorageBuffer("warp", AVBOIT_WARP_STRUCT)
 ;
 
-const volume_group = new ShaderResourceGroupDescriptor();
+/**
+ * The voxel volume a splat adds its extinction into: the packed counts and the per-channel first
+ * overflow, both atomics, so fragment-only. Every splat that writes through `avboit_splat_slice` binds
+ * this group.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const AVBOIT_SPLAT_VOLUME_GROUP = new ShaderResourceGroupDescriptor();
 
-volume_group
+AVBOIT_SPLAT_VOLUME_GROUP
     .addStorageBuffer("extinction_volume", WebGPUArray.from(atomic_u32), true)
     .addStorageBuffer("overflow_slice", WebGPUArray.from(atomic_u32), true)
 ;
 
-const pass_groups = [view_group, volume_group];
+const pass_groups = [view_group, AVBOIT_SPLAT_VOLUME_GROUP];
 
 /*
  The layout is built group by group rather than with one visibility for every group: WebGPU refuses
@@ -67,7 +74,7 @@ const pass_groups = [view_group, volume_group];
 */
 const pass_layouts = [
     view_group.generateBindGroupLayoutDescriptor(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-    volume_group.generateBindGroupLayoutDescriptor(GPUShaderStage.FRAGMENT),
+    AVBOIT_SPLAT_VOLUME_GROUP.generateBindGroupLayoutDescriptor(GPUShaderStage.FRAGMENT),
 ];
 
 const shader_vertex = ShaderDescriptor.from({

package/src/shade/renderer/scene/GPUInstancesAccelerationStructure.d.ts

@@ -1,5 +1,9 @@
 /**
- * Top-Level Acceleration Structure (TLAS)
+ * Top-Level Acceleration Structure (TLAS): a BVH8 over the scene's instances, in the layout of
+ * {@link BVH8_TREE_BUFFER_LAYOUT}. A leaf's payload is a row of the scene database's `meshes` table.
+ *
+ * A build makes a binary tree over the rows' world boxes (`graph_bvh_build_lbvh`), which lives for
+ * the length of the build, and encodes it three levels to a node (`graph_bvh8_encode_from_bvh2`).
  */
 export class GPUInstancesAccelerationStructure {
     /**
@@ -49,9 +53,9 @@ export class GPUInstancesAccelerationStructure {
      */
     invalidate(): void;
     /**
-     * The bounds of everything in the tree, read back from its root node: the box the GPU built
-     * the tree under, the union of every live row's bounds as the bounds pass derived them — the
-     * whole scene, whoever placed what. For a consumer that sizes work by the scene once, a probe
+     * The bounds of everything in the tree, read back from its header: the box the GPU built the
+     * tree under, the union of every live row's bounds as the bounds pass derived them — the whole
+     * scene, whoever placed what. For a consumer that sizes work by the scene once, a probe
      * placement or a bake; a frame-loop reader wants the scene database's readback service.
      *
      * Resolves once the copy has landed and been mapped, which is after the device has finished

package/src/shade/renderer/scene/GPUInstancesAccelerationStructure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUInstancesAccelerationStructure.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUInstancesAccelerationStructure.js"],"names":[],"mappings":"AAoCA;;GAEG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAKzB;IA+DD;;;OAGG;IACH,sBAFW,eAAe,EAqBzB;IAzED,cAIC;IAOD;;;OAGG;IACH,wBAEC;IAmED;;;;OAIG;IACH,oBAFW,MAAM,QAUhB;IAED;;;;;OAKG;IACH,uBAFW,MAAM,QAUhB;IAED;;;;OAIG;IACH,uBAFW,MAAM,QAOhB;IA8CD;;;;OAIG;IACH;;;OAGG;IACH,mBAEC;IAiGD;;;;;;;;;;;;OAYG;IACH,0BAHW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,GAChC,QAAQ,OAAO,CAAC,CA0C5B;IAED;;;OAGG;IACH,wDAFW,sBAAsB,QAMhC;IAED;;;;;;OAMG;IACH,mDAHW,sBAAsB,QAShC;IAED;;;OAGG;IACH,gBAKC;;CACJ;8BApaY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;uCATrB,wCAAwC"}
+{"version":3,"file":"GPUInstancesAccelerationStructure.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUInstancesAccelerationStructure.js"],"names":[],"mappings":"AAqDA;;;;;;GAMG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAMzB;IA+DD;;;OAGG;IACH,sBAFW,eAAe,EAoBzB;IAxED,cAIC;IAOD;;;OAGG;IACH,wBAEC;IAkED;;;;OAIG;IACH,oBAFW,MAAM,QAUhB;IAED;;;;;OAKG;IACH,uBAFW,MAAM,QAUhB;IAED;;;;OAIG;IACH,uBAFW,MAAM,QAOhB;IA8CD;;;;OAIG;IACH;;;OAGG;IACH,mBAEC;IA4GD;;;;;;;;;;;;OAYG;IACH,0BAHW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,GAChC,QAAQ,OAAO,CAAC,CAqC5B;IAED;;;OAGG;IACH,wDAFW,sBAAsB,QAMhC;IAED;;;;;;OAMG;IACH,mDAHW,sBAAsB,QAShC;IAED;;;OAGG;IACH,gBAKC;;CACJ;8BAlbY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;uCAtBrB,wCAAwC"}

package/src/shade/renderer/scene/GPUInstancesAccelerationStructure.js

@@ -3,9 +3,22 @@ import { FrameGraph } from "../../../engine/graphics/render/frame_graph/FrameGra
 import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { ensure_buffer_capacity } from "../geometry/make_temp_gpu_buffer.js";
-import { BVH_HEADER_WORDS, BVH_NODE_STRIDE_WORDS, bvh_buffer_size } from "../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
-import { BVH_NULL_NODE, bvh_tree_views, read_bvh_node } from "../gpu_primitive/bvh/check_bvh_structure.js";
+import { bvh_buffer_size } from "../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
 import { enquire_bvh_build_lbvh_pipelines, graph_bvh_build_lbvh } from "../gpu_primitive/bvh/graph_bvh_build_lbvh.js";
+import {
+    BVH8_TREE_BOUNDS_HIGH_WORD,
+    BVH8_TREE_BOUNDS_LOW_WORD,
+    BVH8_TREE_HEADER_WORDS,
+    BVH8_TREE_LEAF_COUNT_WORD,
+    BVH8_TREE_NODE_STRIDE_WORDS,
+    BVH8_TREE_ORDER_OFFSET_WORD,
+    bvh8_tree_buffer_size
+} from "../gpu_primitive/bvh8/BVH8_TREE_BUFFER_LAYOUT.js";
+import {
+    enquire_bvh8_encode_pipelines,
+    graph_bvh8_encode_from_bvh2
+} from "../gpu_primitive/bvh8/graph_bvh8_encode_from_bvh2.js";
+import { graph_create_buffer } from "../shader/graph/graph_create_buffer.js";
 import { shader_bvh_extract_instance_leaves } from "./shader_bvh_extract_instance_leaves.js";
 
 /**
@@ -14,10 +27,14 @@ import { shader_bvh_extract_instance_leaves } from "./shader_bvh_extract_instanc
  */
 
 /**
- * `root = BVH_NULL_NODE` — an empty tree, in the four bytes every consumer already reads that way.
+ * A tree of no instances, as every walk reads it: a header that counts none, and one node with every
+ * slot empty. The payloads would start behind that node.
+ *
  * @type {Uint32Array}
  */
-const EMPTY_TREE = Uint32Array.from([0xffffffff]);
+const EMPTY_TREE = new Uint32Array(BVH8_TREE_HEADER_WORDS + BVH8_TREE_NODE_STRIDE_WORDS);
+
+EMPTY_TREE[BVH8_TREE_ORDER_OFFSET_WORD] = BVH8_TREE_HEADER_WORDS + BVH8_TREE_NODE_STRIDE_WORDS;
 
 /**
  * The scene-bounds cell before anything has been merged into it: +inf for the three minima, -inf
@@ -35,7 +52,11 @@ const SCENE_BOUNDS_SEED = Uint32Array.from([
 ]);
 
 /**
- * Top-Level Acceleration Structure (TLAS)
+ * Top-Level Acceleration Structure (TLAS): a BVH8 over the scene's instances, in the layout of
+ * {@link BVH8_TREE_BUFFER_LAYOUT}. A leaf's payload is a row of the scene database's `meshes` table.
+ *
+ * A build makes a binary tree over the rows' world boxes (`graph_bvh_build_lbvh`), which lives for
+ * the length of the build, and encodes it three levels to a node (`graph_bvh8_encode_from_bvh2`).
  */
 export class GPUInstancesAccelerationStructure {
 
@@ -47,6 +68,7 @@ export class GPUInstancesAccelerationStructure {
     static enquirePipelines(enquiry) {
         enquiry.compute.push(shader_bvh_extract_instance_leaves.pipeline);
         enquire_bvh_build_lbvh_pipelines(enquiry);
+        enquire_bvh8_encode_pipelines(enquiry);
     }
 
 
@@ -129,9 +151,8 @@ export class GPUInstancesAccelerationStructure {
             usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
         });
 
-        // A fresh buffer holds zeroes, and zero is a root word naming node 0 — a tree that was never
-        // built would read as one with a root of zero bounds. Empty, until the first build says
-        // otherwise.
+        // A fresh buffer holds zeroes, which is a tree of no instances but for where its payloads start.
+        // Empty, until the first build says otherwise.
         device.queue.writeBuffer(this.#buffer, 0, EMPTY_TREE);
     }
 
@@ -262,7 +283,7 @@ export class GPUInstancesAccelerationStructure {
         this.#buffer = ensure_buffer_capacity(
             device,
             this.#buffer,
-            bvh_buffer_size(Math.max(1, element_count)),
+            bvh8_tree_buffer_size(element_count),
             1024,
             1024,
             1.2
@@ -290,8 +311,8 @@ export class GPUInstancesAccelerationStructure {
             scene_database_buffer
         );
 
-        const nodes = graph.import_resource(
-            "tlas/nodes",
+        const tree = graph.import_resource(
+            "tlas/tree",
             BufferResourceDescriptor.fromBuffer(this.#buffer),
             this.#buffer
         );
@@ -318,13 +339,24 @@ export class GPUInstancesAccelerationStructure {
             GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
         ));
 
-        graph_bvh_build_lbvh({
+        // the binary tree is this build's alone
+        const binary = graph_bvh_build_lbvh({
             graph,
             leaf_bounds: extract_data.leaf_bounds,
             leaf_payload: extract_data.leaf_payload,
             scene_bounds: extract_data.scene_bounds,
             element_count,
-            nodes,
+            nodes: graph_create_buffer(graph, "tlas/binary tree", BufferResourceDescriptor.from(
+                bvh_buffer_size(element_count),
+                GPUBufferUsage.STORAGE
+            )),
+        });
+
+        graph_bvh8_encode_from_bvh2({
+            graph,
+            tree: binary.nodes,
+            leaf_count: element_count,
+            out: tree,
         });
 
         if (cmd_ctx !== undefined) {
@@ -340,9 +372,9 @@ export class GPUInstancesAccelerationStructure {
     }
 
     /**
-     * The bounds of everything in the tree, read back from its root node: the box the GPU built
-     * the tree under, the union of every live row's bounds as the bounds pass derived them — the
-     * whole scene, whoever placed what. For a consumer that sizes work by the scene once, a probe
+     * The bounds of everything in the tree, read back from its header: the box the GPU built the
+     * tree under, the union of every live row's bounds as the bounds pass derived them — the whole
+     * scene, whoever placed what. For a consumer that sizes work by the scene once, a probe
      * placement or a bake; a frame-loop reader wants the scene database's readback service.
      *
      * Resolves once the copy has landed and been mapped, which is after the device has finished
@@ -356,8 +388,7 @@ export class GPUInstancesAccelerationStructure {
         assert.isArrayLike(target, 'target');
         assert.greaterThanOrEqual(target.length, 6, 'target.length < 6');
 
-        // the root word and node 0 — the root by the builder's construction
-        const byte_size = (BVH_HEADER_WORDS + BVH_NODE_STRIDE_WORDS) * Uint32Array.BYTES_PER_ELEMENT;
+        const byte_size = BVH8_TREE_HEADER_WORDS * Uint32Array.BYTES_PER_ELEMENT;
 
         const allocator = this.#graphics.buffer_allocator_readback;
         const staging = allocator.get(byte_size);
@@ -369,24 +400,20 @@ export class GPUInstancesAccelerationStructure {
 
         await staging.mapAsync(GPUMapMode.READ, 0, byte_size);
 
-        const { words, floats } = bvh_tree_views(new Uint32Array(staging.getMappedRange(0, byte_size)));
-        const root = words[0];
-
-        let found = false;
-
-        if (root !== BVH_NULL_NODE) {
-            assert.equal(root, 0, 'the tree\'s root is not node 0');
+        const mapped = staging.getMappedRange(0, byte_size);
 
-            const node = read_bvh_node(words, floats, root);
+        const words = new Uint32Array(mapped);
+        const floats = new Float32Array(mapped);
 
-            target[0] = node.low[0];
-            target[1] = node.low[1];
-            target[2] = node.low[2];
-            target[3] = node.high[0];
-            target[4] = node.high[1];
-            target[5] = node.high[2];
+        const found = words[BVH8_TREE_LEAF_COUNT_WORD] !== 0;
 
-            found = true;
+        if (found) {
+            target[0] = floats[BVH8_TREE_BOUNDS_LOW_WORD];
+            target[1] = floats[BVH8_TREE_BOUNDS_LOW_WORD + 1];
+            target[2] = floats[BVH8_TREE_BOUNDS_LOW_WORD + 2];
+            target[3] = floats[BVH8_TREE_BOUNDS_HIGH_WORD];
+            target[4] = floats[BVH8_TREE_BOUNDS_HIGH_WORD + 1];
+            target[5] = floats[BVH8_TREE_BOUNDS_HIGH_WORD + 2];
         }
 
         allocator.release(staging);

package/src/shade/renderer/scene/verify_gpu_tlas_build.d.ts

@@ -2,14 +2,14 @@
  * End-to-end verification of the GPU TLAS build against a real scene database.
  *
  * Builds a synthetic `meshes` table, drives the TLAS through the same calls `GPUSceneContext`
- * makes, reads the tree back and checks it: root word, every node reachable once, every mesh row
- * present exactly once as a leaf payload, every internal box containing its children, and the root
- * containing every instance's world AABB — which is the statement that the extraction pass read the
- * table correctly and the scene-bounds cell was seeded, not zeroed.
+ * makes, reads the tree back and checks it ({@link check_bvh8_tree}): the header, every node
+ * reachable once, every mesh row present exactly once as a leaf's payload, every slot holding the
+ * world AABBs of the instances under it, and the header's box the box of them all — which is the
+ * statement that the extraction pass read the table correctly and the scene-bounds cell was seeded,
+ * not zeroed.
  *
  * Then it exercises the three things only the integration has: a pure movement (rebuild, no rows
- * upload), a removal (a leaf really goes away), and an emptied TLAS (the host-written empty-tree
- * word).
+ * upload), a removal (a leaf really goes away), and an emptied TLAS (the host-written empty tree).
  *
  * @param {GraphicsContext} graphics
  * @returns {Promise<void>}

package/src/shade/renderer/scene/verify_gpu_tlas_build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_gpu_tlas_build.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/verify_gpu_tlas_build.js"],"names":[],"mappings":"AA4NA;;;;;;;;;;;;;;;GAeG;AACH,kEAFa,QAAQ,IAAI,CAAC,CAmHzB"}
+{"version":3,"file":"verify_gpu_tlas_build.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/verify_gpu_tlas_build.js"],"names":[],"mappings":"AA8LA;;;;;;;;;;;;;;;GAeG;AACH,kEAFa,QAAQ,IAAI,CAAC,CAmHzB"}