@woosh/meep-engine 3.33.0 → 3.35.0

package/src/shade/renderer/rasterize/bucket/shader_gather_bucket.d.ts

@@ -0,0 +1,15 @@
+/**
+ * One bucket of a bucket-sorted collection, appended to a flat collection after the gathered
+ * buckets below it.
+ *
+ * Dispatched once per gathered bucket, in ascending id order, each sized off its own bucket's
+ * header. Where a bucket lands is the sum of the gathered buckets below it, so the output is their
+ * concatenation whatever the dispatches' timing, and not one atomic is involved.
+ *
+ * @see graph_gather_meshes_from_buckets
+ * @see shader_read_out_bucket which copies a bucket to the start of an output of its own
+ * @type {ComputeShader}
+ */
+export const shader_gather_bucket: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_gather_bucket.d.ts.map

package/src/shade/renderer/rasterize/bucket/shader_gather_bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_gather_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/shader_gather_bucket.js"],"names":[],"mappings":"AAsFA;;;;;;;;;;;GAWG;AACH,mCAFU,aAAa,CAMrB;8BAhG4B,+BAA+B"}

package/src/shade/renderer/rasterize/bucket/shader_gather_bucket.js

@@ -0,0 +1,103 @@
+import { assert } from "../../../../core/assert.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { RASTERIZATION_BUCKET_LIMIT } from "../expand/bucket/RASTERIZATION_BUCKET_LIMIT.js";
+import {
+    RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_READ
+} from "../expand/bucket/RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_READ.js";
+
+// every bucket is one bit of `gathered`
+assert.lessThanOrEqual(RASTERIZATION_BUCKET_LIMIT, 32, 'RASTERIZATION_BUCKET_LIMIT');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", WebGPUStruct.from({
+    bucket_id: u32,
+    // every bucket this gather concatenates, one bit per bucket id
+    gathered: u32,
+}));
+
+resources.createGroup()
+    .addStorageBuffer("input", RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_READ)
+    .addStorageBuffer("output", COLLECTION_U32_STRUCT_READ, true)
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+// What a bucket holds, which is not always what its header says: the classify pass counts every
+// visible mesh and writes one only while the input has room (see shader_read_out_bucket).
+fn bucket_size(bucket_id: u32) -> u32 {
+    let header = input.headers[bucket_id];
+
+    let input_capacity = arrayLength(&input.elements);
+    let available = select(0u, input_capacity - header.offset, input_capacity > header.offset);
+
+    return min(header.count, available);
+}
+
+@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
+fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
+
+    let input_index = global_id.x;
+
+    let bucket_id = settings.bucket_id;
+
+    // the bucket starts where the gathered buckets below it end — each read off its own header, so
+    // no dispatch has to hand the next one where it stopped
+    var base = 0u;
+    var below = settings.gathered & ((1u << bucket_id) - 1u);
+
+    while (below != 0u) {
+        base += bucket_size(firstTrailingBit(below));
+        below &= below - 1u;
+    }
+
+    let size = bucket_size(bucket_id);
+    let output_capacity = arrayLength(&output.elements);
+
+    /*
+     Every bucket writes the count it ends at, and the buckets are dispatched in ascending order, so
+     the last one standing wrote the total. Not only the highest: a bucket with nothing in it is a
+     dispatch of no workgroups, and writes nothing at all.
+    */
+    if (input_index == 0u) {
+        output.count = min(base + size, output_capacity);
+    }
+
+    if (input_index >= size) {
+        return;
+    }
+
+    let output_index = base + input_index;
+
+    if (output_index >= output_capacity) {
+        return;
+    }
+
+    output.elements[output_index] = input.elements[input.headers[bucket_id].offset + input_index];
+}
+    `
+);
+
+/**
+ * One bucket of a bucket-sorted collection, appended to a flat collection after the gathered
+ * buckets below it.
+ *
+ * Dispatched once per gathered bucket, in ascending id order, each sized off its own bucket's
+ * header. Where a bucket lands is the sum of the gathered buckets below it, so the output is their
+ * concatenation whatever the dispatches' timing, and not one atomic is involved.
+ *
+ * @see graph_gather_meshes_from_buckets
+ * @see shader_read_out_bucket which copies a bucket to the start of an output of its own
+ * @type {ComputeShader}
+ */
+export const shader_gather_bucket = ComputeShader.from({
+    label: 'Gather bucket',
+    resources,
+    body,
+})

package/src/shade/renderer/rasterize/expand/GPUCollectionLimits.d.ts

@@ -46,6 +46,9 @@ export class GPUCollectionLimits {
     compute_buffer_size(type: RasterizationCollectionType): number;
     destroy(): void;
     /**
+     * Read this frame's counts back once `encoder` is submitted and fold them into the limits.
+     * Resolves, never rejects, when the reading is lost to a teardown — see
+     * {@link Uint32BufferSamplingStats#readback_explicit} — and the limits then stand as they were.
      *
      * @param {ShadeGPUCommandContext} encoder
      * @param {GPUBufferAllocator} buffers

package/src/shade/renderer/rasterize/expand/GPUCollectionLimits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUCollectionLimits.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/expand/GPUCollectionLimits.js"],"names":[],"mappings":"AAsBA;;GAEG;AACH;IAyBI;;;OAGG;IACH,+BAqBC;IAtCD;;;OAGG;IACH,uCAEC;IAkCD;;;;OAIG;IACH,gBAHW,2BAA2B,GAC1B,MAAM,CAMjB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAHW,2BAA2B,SAC3B,MAAM,QAQhB;IAED;;;;OAIG;IACH,0BAHW,2BAA2B,GACzB,MAAM,CAyBlB;IA+BD,gBAEC;IAED;;;;OAIG;IACH,gBAHW,sBAAsB,WACtB,kBAAkB,iBAgB5B;;CAEJ;qCA5LY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,oCAAoC,EAAE,kBAAkB;0CANlC,yCAAyC;4CACvC,kCAAkC"}
+{"version":3,"file":"GPUCollectionLimits.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/expand/GPUCollectionLimits.js"],"names":[],"mappings":"AAsBA;;GAEG;AACH;IAyBI;;;OAGG;IACH,+BAqBC;IAtCD;;;OAGG;IACH,uCAEC;IAkCD;;;;OAIG;IACH,gBAHW,2BAA2B,GAC1B,MAAM,CAMjB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAHW,2BAA2B,SAC3B,MAAM,QAQhB;IAED;;;;OAIG;IACH,0BAHW,2BAA2B,GACzB,MAAM,CAyBlB;IA+BD,gBAEC;IAED;;;;;;;OAOG;IACH,gBAHW,sBAAsB,WACtB,kBAAkB,iBAkB5B;;CAEJ;qCAjMY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,oCAAoC,EAAE,kBAAkB;0CANlC,yCAAyC;4CACvC,kCAAkC"}

package/src/shade/renderer/rasterize/expand/GPUCollectionLimits.js

@@ -177,6 +177,9 @@ export class GPUCollectionLimits {
     }
 
     /**
+     * Read this frame's counts back once `encoder` is submitted and fold them into the limits.
+     * Resolves, never rejects, when the reading is lost to a teardown — see
+     * {@link Uint32BufferSamplingStats#readback_explicit} — and the limits then stand as they were.
      *
      * @param {ShadeGPUCommandContext} encoder
      * @param {GPUBufferAllocator} buffers
@@ -187,7 +190,9 @@ export class GPUCollectionLimits {
 
         const stats = this.#stats;
 
-        await stats.readback_explicit(encoder, buffers);
+        if (!await stats.readback_explicit(encoder, buffers)) {
+            return;
+        }
 
         this.#clamp_stats_against_runaway();
 

package/src/shade/renderer/rasterize/expand/bucket/meshlet/graph_extract_meshlets_from_bucket.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copy one bucket's meshlets out of a bucket-sorted meshlet buffer into a flat collection a raster
+ * pass can draw.
+ *
+ * The second half of expanding and cutting a view once and bucketing afterwards
+ * (CUT_PLAN_2026_09_14 §7 6b): the bucket loop that follows rasterizes each slice with its own
+ * primitive state, and nothing upstream of the sort had to know how many buckets there were.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buckets bucket-sorted meshlets, as {@link graph_sort_meshlets_by_bucket_id}
+ *     leaves them
+ * @param {number} options.bucket_id
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} the bucket's meshlets
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_extract_meshlets_from_bucket({ graph, buckets, bucket_id, limits, }: {
+    graph: FrameGraph;
+    buckets: number;
+    bucket_id: number;
+    limits: GPUCollectionLimits;
+}): number;
+//# sourceMappingURL=graph_extract_meshlets_from_bucket.d.ts.map

package/src/shade/renderer/rasterize/expand/bucket/meshlet/graph_extract_meshlets_from_bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_extract_meshlets_from_bucket.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/rasterize/expand/bucket/meshlet/graph_extract_meshlets_from_bucket.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAV+B,KAAK;IACT,OAAO,EAAvB,MAAM;IAEU,SAAS,EAAzB,MAAM;IACuB,MAAM;IACjC,MAAM,CAoElB"}

package/src/shade/renderer/rasterize/expand/bucket/meshlet/graph_extract_meshlets_from_bucket.js

@@ -0,0 +1,91 @@
+import { BufferResourceDescriptor } from "../../../../../device/graph/BufferResourceDescriptor.js";
+import { u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "../../../../gpu_primitive/indirect/STRUCT_DISPATCH_COMPUTE_COMMAND.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { build_indirect_compute_dispatch_command } from "../../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { RasterizationCollectionType } from "../../RasterizationCollectionType.js";
+import { shader_meshlets_extract_bucket } from "./shader_meshlets_extract_bucket.js";
+
+/**
+ * Copy one bucket's meshlets out of a bucket-sorted meshlet buffer into a flat collection a raster
+ * pass can draw.
+ *
+ * The second half of expanding and cutting a view once and bucketing afterwards
+ * (CUT_PLAN_2026_09_14 §7 6b): the bucket loop that follows rasterizes each slice with its own
+ * primitive state, and nothing upstream of the sort had to know how many buckets there were.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buckets bucket-sorted meshlets, as {@link graph_sort_meshlets_by_bucket_id}
+ *     leaves them
+ * @param {number} options.bucket_id
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} the bucket's meshlets
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_extract_meshlets_from_bucket({
+                                                       graph,
+                                                       buckets,
+                                                       bucket_id,
+                                                       limits,
+                                                   }) {
+
+    /**
+     *
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(data, resources, context) {
+        const encoder = context.encoder;
+
+        const buckets = resources.get(data.buckets);
+        const output = resources.get(data.output);
+        const command = resources.get(data.command);
+
+        const bucket_id = data.bucket_id;
+
+        // folded: a meshlet collection is past what one dispatch dimension reaches — see
+        // IndirectComputeCommandBuildPass
+        build_indirect_compute_dispatch_command(
+            COMPUTE_SHADER_DEFAULT_GROUP_SIZE,
+            encoder,
+            buckets,
+            // the bucketed buffer header consists of pairs of u32 values (count,offset)
+            bucket_id * (u32.size * 2),
+            command,
+            0,
+            true,
+        );
+
+        shader_meshlets_extract_bucket.dispatchIndirect({
+            encoder,
+            command,
+            bindings: {
+                bucket_index: { value: bucket_id },
+                bucket_data: buckets,
+                output: output,
+            }
+        });
+    }
+
+    const data = {};
+
+    const pass = graph.add("extract meshlets from bucket", data, execute);
+
+    data.buckets = pass.read(buckets);
+    data.bucket_id = bucket_id;
+    data.command = pass.create("command", BufferResourceDescriptor.from(
+        STRUCT_DISPATCH_COMPUTE_COMMAND.aligned_size,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+    ));
+    data.output = pass.create("output", BufferResourceDescriptor.from(
+        limits.compute_buffer_size(RasterizationCollectionType.Meshlets),
+        GPUBufferUsage.STORAGE,
+        0, 16 // clear count
+    ));
+
+    return data.output;
+}

package/src/shade/renderer/rasterize/fast/graph_gather_meshes_from_buckets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Several buckets' mesh indices out of a bucket-sorted mesh buffer, into one flat
+ * {@link COLLECTION_U32_STRUCT_READ} buffer, end to end in bucket order.
+ *
+ * What lets the fast path expand and cut a view once rather than once per opaque bucket
+ * (CUT_PLAN_2026_09_14 §7 6b): the opaque buckets are not neighbours in the sorted buffer — the
+ * transparency mode is the low bits of a bucket id — so they cannot be read out as one range.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buckets bucket-sorted meshes resource ID
+ * @param {number[]} options.bucket_ids the buckets to gather, ascending
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} resource ID of the gathered mesh list
+ */
+export function graph_gather_meshes_from_buckets({ graph, buckets, bucket_ids, limits, }: {
+    graph: FrameGraph;
+    buckets: number;
+    bucket_ids: number[];
+    limits: GPUCollectionLimits;
+}): number;
+//# sourceMappingURL=graph_gather_meshes_from_buckets.d.ts.map

package/src/shade/renderer/rasterize/fast/graph_gather_meshes_from_buckets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_gather_meshes_from_buckets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_gather_meshes_from_buckets.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH;IAN+B,KAAK;IACT,OAAO,EAAvB,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACqB,MAAM;IACjC,MAAM,CA6ElB"}

package/src/shade/renderer/rasterize/fast/graph_gather_meshes_from_buckets.js

@@ -0,0 +1,102 @@
+import { assert } from "../../../../core/assert.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import {
+    build_indirect_compute_dispatch_command,
+    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+} from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
+import { shader_gather_bucket } from "../bucket/shader_gather_bucket.js";
+
+/**
+ * Several buckets' mesh indices out of a bucket-sorted mesh buffer, into one flat
+ * {@link COLLECTION_U32_STRUCT_READ} buffer, end to end in bucket order.
+ *
+ * What lets the fast path expand and cut a view once rather than once per opaque bucket
+ * (CUT_PLAN_2026_09_14 §7 6b): the opaque buckets are not neighbours in the sorted buffer — the
+ * transparency mode is the low bits of a bucket id — so they cannot be read out as one range.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buckets bucket-sorted meshes resource ID
+ * @param {number[]} options.bucket_ids the buckets to gather, ascending
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} resource ID of the gathered mesh list
+ */
+export function graph_gather_meshes_from_buckets({
+                                                     graph,
+                                                     buckets,
+                                                     bucket_ids,
+                                                     limits,
+                                                 }) {
+    assert.isArray(bucket_ids, 'bucket_ids');
+
+    let gathered = 0;
+
+    for (let i = 0; i < bucket_ids.length; i++) {
+        const bucket_id = bucket_ids[i];
+
+        assert.isNonNegativeInteger(bucket_id, 'bucket_id');
+        assert.lessThan(bucket_id, 32, 'bucket_id');
+
+        // the count the last dispatch writes is the total only if the last is the highest
+        assert.ok(i === 0 || bucket_ids[i - 1] < bucket_id, 'bucket_ids must be ascending');
+
+        gathered |= 1 << bucket_id;
+    }
+
+    gathered >>>= 0;
+
+    /**
+     *
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(data, resources, context) {
+        const encoder = context.encoder;
+
+        const buckets = resources.get(data.buckets);
+        const output = resources.get(data.output);
+
+        for (let i = 0; i < bucket_ids.length; i++) {
+            const bucket_id = bucket_ids[i];
+            const command = resources.get(data.commands[i]);
+
+            build_indirect_compute_dispatch_command(
+                COMPUTE_SHADER_DEFAULT_GROUP_SIZE,
+                encoder,
+                buckets,
+                // the bucketed buffer header consists of pairs of u32 values (count,offset)
+                bucket_id * (u32.size * 2),
+                command,
+                0
+            );
+
+            shader_gather_bucket.dispatchIndirect({
+                encoder,
+                command,
+                bindings: {
+                    settings: { bucket_id, gathered },
+                    input: buckets,
+                    output,
+                }
+            });
+        }
+    }
+
+    const data = {};
+
+    const pass = graph.add("gather meshes from buckets", data, execute);
+
+    data.buckets = pass.read(buckets);
+    data.commands = bucket_ids.map(() => pass.create("command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR));
+    data.output = pass.create("output", BufferResourceDescriptor.from(
+        limits.compute_buffer_size(RasterizationCollectionType.Meshes),
+        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        0, 16 // clear count
+    ));
+
+    return data.output;
+}

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.d.ts

@@ -32,7 +32,8 @@ export function graph_rasterize_scene_fast_raw({ graph, meshes, limits, target_d
  * Flow:
  *  1. Frustum cull the scene meshes
  *  2. Sort culled meshes into rasterization buckets
- *  3. For each active opaque bucket: extract -> expand to meshlets -> rasterize
+ *  3. Gather every active opaque bucket -> expand to meshlets and cut, once -> rasterize a bucket
+ *     at a time
  *  4. If an alpha-tested pass is configured, rasterize it without HZB filtering
  *
  * @param {Object} options

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_scene_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CAkK3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}
+{"version":3,"file":"graph_rasterize_scene_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CAwK3D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js

@@ -1,22 +1,19 @@
 import { assert } from "../../../../core/assert.js";
-import { ShadeDrawMode } from "../../material/ShadeDrawMode.js";
 import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
-import { TransparencyMode } from "../../material/TransparencyMode.js";
 import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
 import { graph_import_texture } from "../../shader/graph/graph_import_texture.js";
 import { graph_record_stat } from "../../util/graph_record_stat.js";
 import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterization_material_bucket.js";
 import { graph_meshes_classify_buckets } from "../expand/bucket/mesh/graph_meshes_classify_buckets.js";
-import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
 import { graph_expand_meshes_to_meshlets } from "../expand/mesh/graph_expand_meshes_to_meshlets.js";
 import { graph_vgeo_expand_if_enabled } from "../../geometry/virtual/runtime/graph_vgeo_expand_if_enabled.js";
 import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
-import { construct_primitive_state } from "../bucket/construct_primitive_state.js";
+import { graph_meshlets_rasterize_by_bucket } from "../bucket/graph_meshlets_rasterize_by_bucket.js";
 import { rasterization_opaque_buckets } from "../bucket/rasterization_opaque_buckets.js";
 import { graph_mesh_frustum_cull } from "../compute/graph_mesh_frustum_cull.js";
 import { graph_clear_raster_targets } from "../graph_clear_raster_targets.js";
 import { graph_rasterize_meshes_alpha_tested } from "../native/graph_rasterize_meshes_alpha_tested.js";
-import { graph_extract_meshes_from_bucket } from "./graph_extract_meshes_from_bucket.js";
+import { graph_gather_meshes_from_buckets } from "./graph_gather_meshes_from_buckets.js";
 
 /**
  *
@@ -74,49 +71,55 @@ export function graph_rasterize_scene_fast_raw({
         active_buckets.add(bucket_id);
     }
 
-    // rasterize each active opaque bucket in a single pass, with no occlusion filtering
+    const opaque = Array.from(rasterization_opaque_buckets(active_buckets));
+
     let is_first_draw = true;
 
-    for (const { draw_mode, side, bucket_id } of rasterization_opaque_buckets(active_buckets)) {
-        const gr_bucket_meshes = graph_extract_meshes_from_bucket({
+    if (opaque.length > 0) {
+        /*
+         Every opaque bucket's meshes in one collection, expanded and cut once, then drawn a bucket at
+         a time with no occlusion filtering. The cut is the one per view (CUT_PLAN_2026_09_14 §7 6b),
+         and the ids are ascending, which is what the gather's count needs.
+        */
+        const gr_opaque_meshes = graph_gather_meshes_from_buckets({
             graph,
             buckets: gr_render_buckets,
-            bucket_id,
+            bucket_ids: opaque.map(bucket => bucket.bucket_id),
             limits,
         });
 
-        let gr_bucket_meshlets = graph_expand_meshes_to_meshlets({
+        let gr_meshlets = graph_expand_meshes_to_meshlets({
             graph,
-            input_meshes: gr_bucket_meshes,
+            input_meshes: gr_opaque_meshes,
             scene: scene_ctx,
             expected_output_size: limits.compute_buffer_size(RasterizationCollectionType.Meshlets),
             limits,
         });
 
-        // the seam: this bucket's virtual-geometry instances select their cut and append it to
-        // the same collection, which is the whole of what the rest of this function is told
-        gr_bucket_meshlets = graph_vgeo_expand_if_enabled({
+        // the seam: the view's virtual-geometry instances select their cut and append it to the
+        // same collection, which is the whole of what the rest of this function is told
+        gr_meshlets = graph_vgeo_expand_if_enabled({
             graph,
-            input_meshes: gr_bucket_meshes,
-            output_meshlets: gr_bucket_meshlets,
+            input_meshes: gr_opaque_meshes,
+            output_meshlets: gr_meshlets,
             view: view_ctx,
             limits,
         });
 
-        graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, gr_bucket_meshlets);
+        graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, gr_meshlets);
 
-        const primitive_state = construct_primitive_state(draw_mode, side, job.cull_policy);
-
-        [target_depth, targets_color] = graph_meshlets_rasterize({
+        [target_depth, targets_color] = graph_meshlets_rasterize_by_bucket({
             graph,
             view: view_ctx,
-            input_meshlets: gr_bucket_meshlets,
+            input_meshlets: gr_meshlets,
+            buckets: opaque,
             depth: target_depth,
             color_targets: targets_color,
             pass_descriptor: job.opaque_pass,
-            clear_targets: is_first_draw,
-            primitive_state,
+            clear_targets: true,
+            cull_policy: job.cull_policy,
             viewport,
+            limits,
         });
 
         is_first_draw = false;
@@ -203,7 +206,8 @@ export function graph_rasterize_scene_fast_raw({
  * Flow:
  *  1. Frustum cull the scene meshes
  *  2. Sort culled meshes into rasterization buckets
- *  3. For each active opaque bucket: extract -> expand to meshlets -> rasterize
+ *  3. Gather every active opaque bucket -> expand to meshlets and cut, once -> rasterize a bucket
+ *     at a time
  *  4. If an alpha-tested pass is configured, rasterize it without HZB filtering
  *
  * @param {Object} options

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

@@ -70,6 +70,10 @@ export type AVBOITSideChannel = {
     /**
      * draw the
      * channel's fragments into the accumulators; returns their handles after the draw.
+     * `volumetrics_irradiance` is what a fragment standing in a froxel is lit by
+     * (`chunk_volumetrics_irradiance_sh`), for a channel whose fragments are lit: the renderer's
+     * indirect lighting, whichever mode it runs, and the scene's lights, shadowed and attenuated by
+     * the fog, written by the pass that lights the fog.
      */
     avboit_draw: (args: {
         graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
@@ -80,6 +84,10 @@ export type AVBOITSideChannel = {
         integral: number;
         volumetrics_lut: number;
         volumetrics_metadata: number;
+        volumetrics_irradiance: {
+            Y: number;
+            CoCg: number;
+        };
         accumulators: {
             color: number;
             norm: number;

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

@@ -1 +1 @@
-{"version":3,"file":"AVBOITSideChannel.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAoCc,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,kBAAwB,EAAE,UAAU,MAAM,CAAC,CAAC;QAC5C,SAAe,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM;;;;;;;;kBAED,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,IAAU,EAAE,MAAM,CAAC;QACnB,aAAmB,EAAE,MAAM,CAAC;QAC5B,gBAAsB,EAAE,MAAM,EAAE,CAAC;QACjC,MAAY,EAAE;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,CAAC;KACjE,KAAK;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC;;;;;iBAKhD,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,QAAc,EAAE,OAAO,iCAAiC,EAAE,cAAc,CAAC;QACzE,MAAY,EAAE,MAAM,CAAC;QACrB,aAAmB,EAAE,MAAM,CAAC;QAC5B,IAAU,EAAE,MAAM,CAAC;QACnB,QAAc,EAAE,MAAM,CAAC;QACvB,eAAqB,EAAE,MAAM,CAAC;QAC9B,oBAA0B,EAAE,MAAM,CAAC;QACnC,YAAkB,EAAE;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAC,CAAC;KACrF,KAAK;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC;;;;;;sBAE9D,MAAM,OAAO"}
+{"version":3,"file":"AVBOITSideChannel.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAoCc,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,kBAAwB,EAAE,UAAU,MAAM,CAAC,CAAC;QAC5C,SAAe,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM;;;;;;;;kBAED,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,IAAU,EAAE,MAAM,CAAC;QACnB,aAAmB,EAAE,MAAM,CAAC;QAC5B,gBAAsB,EAAE,MAAM,EAAE,CAAC;QACjC,MAAY,EAAE;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,CAAC;KACjE,KAAK;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC;;;;;;;;;iBAKhD,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,QAAc,EAAE,OAAO,iCAAiC,EAAE,cAAc,CAAC;QACzE,MAAY,EAAE,MAAM,CAAC;QACrB,aAAmB,EAAE,MAAM,CAAC;QAC5B,IAAU,EAAE,MAAM,CAAC;QACnB,QAAc,EAAE,MAAM,CAAC;QACvB,eAAqB,EAAE,MAAM,CAAC;QAC9B,oBAA0B,EAAE,MAAM,CAAC;QACnC,sBAA4B,EAAE;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAC;QACxD,YAAkB,EAAE;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAC,CAAC;KACrF,KAAK;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC;;;;;;sBAM9D,MAAM,OAAO"}

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

@@ -62,9 +62,14 @@
  *     integral: number,
  *     volumetrics_lut: number,
  *     volumetrics_metadata: number,
+ *     volumetrics_irradiance: {Y: number, CoCg: number},
  *     accumulators: {color: number, norm: number, extinction: number, emission: number},
  * }) => {color: number, norm: number, extinction: number, emission: number}} avboit_draw draw the
  *     channel's fragments into the accumulators; returns their handles after the draw.
+ *     `volumetrics_irradiance` is what a fragment standing in a froxel is lit by
+ *     (`chunk_volumetrics_irradiance_sh`), for a channel whose fragments are lit: the renderer's
+ *     indirect lighting, whichever mode it runs, and the scene's lights, shadowed and attenuated by
+ *     the fog, written by the pass that lights the fog.
  * @property {() => boolean} [avboit_is_empty] whether the channel would add nothing this frame;
  *     asked before the orchestrator records, and a channel that answers `true` is not asked for
  *     anything else in that frame.

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

@@ -155,13 +155,16 @@ export function avboit_create_accumulators(pass: FramePassBuilder, resolution: A
  * @param {number} options.shadowmap_atlas
  * @param {number} options.volumetrics_lut
  * @param {number} options.volumetrics_metadata
+ * @param {{Y: number, CoCg: number}} options.volumetrics_irradiance the froxel irradiance volume
+ *   (`chunk_volumetrics_irradiance_sh`), for side channels that light their own fragments; the
+ *   MBOIT orchestrator ignores it
  * @param {ShadeIndirectLightingMode} options.indirect_lighting_mode
  * @param {AVBOITSettings} [options.avboit] `Renderer.avboit`; the MBOIT orchestrator ignores it
  * @param {import("./AVBOITSideChannel.js").AVBOITSideChannel[]} [options.side_channels] non-meshlet
  *   sources of transparent fragments; the MBOIT orchestrator ignores them
  * @returns {number} resource ID of the composited color texture
  */
-export function graph_rasterize_meshes_transparent_avboit({ graph, buckets, view_ctx, viewport, depth_texture, color_texture, limits, light_cluster_parameters, light_cluster_lookup, light_cluster_data, shadowmap_atlas, volumetrics_lut, volumetrics_metadata, indirect_lighting_mode, avboit, side_channels, }: {
+export function graph_rasterize_meshes_transparent_avboit({ graph, buckets, view_ctx, viewport, depth_texture, color_texture, limits, light_cluster_parameters, light_cluster_lookup, light_cluster_data, shadowmap_atlas, volumetrics_lut, volumetrics_metadata, volumetrics_irradiance, indirect_lighting_mode, avboit, side_channels, }: {
     graph: FrameGraph;
     buckets: number;
     view_ctx: GPUViewContext;
@@ -175,6 +178,10 @@ export function graph_rasterize_meshes_transparent_avboit({ graph, buckets, view
     shadowmap_atlas: number;
     volumetrics_lut: number;
     volumetrics_metadata: number;
+    volumetrics_irradiance: {
+        Y: number;
+        CoCg: number;
+    };
     indirect_lighting_mode: ShadeIndirectLightingMode;
     avboit?: AVBOITSettings;
     side_channels?: import("./AVBOITSideChannel.js").AVBOITSideChannel[];

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

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_meshes_transparent_avboit.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/graph_rasterize_meshes_transparent_avboit.js"],"names":[],"mappings":"AA4DA;;;;;GAKG;AACH,oDAHW,UAAU,MAAM,CAAC,GACf,MAAM,EAAE,CAOpB;AAED;;;;;;;;;;;;GAYG;AACH;IAT+B,KAAK;IACA,KAAK;IACd,MAAM,EAAtB,MAAM;IACqB,kBAAkB,EAA7C,UAAU,MAAM,CAAC;IACD,kBAAkB,EAAlC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,MAAM,CA4DlB;AAED;;;;;;;;;;GAUG;AACH;IAP+B,KAAK;IACT,SAAS,EAAzB,MAAM;IACY,gBAAgB,EAAlC,MAAM,EAAE;IACmB,kBAAkB,EAA7C,UAAU,MAAM,CAAC;IACQ,MAAM,GAA/B,cAAc;IACZ,MAAM,CAsDlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,6KAFa;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAiJjE;AAED;;;;;;;;;;GAUG;AACH;IAP+B,KAAK;IACT,IAAI,EAApB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,QAAQ,EAAxB,MAAM;IACY,gBAAgB,EAAlC,MAAM,EAAE;IACN,MAAM,CAoClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qUAFa;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CAwN7D;AAED;;;;;;;;GAQG;AACH,+EAHW,UAAU,MAAM,CAAC,GACf;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAe/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IAnB+B,KAAK;IACT,OAAO,EAAvB,MAAM;IACkB,QAAQ;IACd,QAAQ,EAA1B,MAAM,EAAE;IACQ,aAAa,EAA7B,MAAM;IACU,aAAa,EAA7B,MAAM;IACuB,MAAM;IACnB,wBAAwB,EAAxC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,kBAAkB,EAAlC,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,oBAAoB,EAApC,MAAM;IAC6B,sBAAsB,EAAzD,yBAAyB;IACA,MAAM,GAA/B,cAAc;IACiD,aAAa,GAA5E,OAAO,wBAAwB,EAAE,iBAAiB,EAAE;IAElD,MAAM,CAwRlB;+BA57B8B,qBAAqB;0CA9BV,uCAAuC"}
+{"version":3,"file":"graph_rasterize_meshes_transparent_avboit.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/graph_rasterize_meshes_transparent_avboit.js"],"names":[],"mappings":"AA4DA;;;;;GAKG;AACH,oDAHW,UAAU,MAAM,CAAC,GACf,MAAM,EAAE,CAOpB;AAED;;;;;;;;;;;;GAYG;AACH;IAT+B,KAAK;IACA,KAAK;IACd,MAAM,EAAtB,MAAM;IACqB,kBAAkB,EAA7C,UAAU,MAAM,CAAC;IACD,kBAAkB,EAAlC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,MAAM,CA4DlB;AAED;;;;;;;;;;GAUG;AACH;IAP+B,KAAK;IACT,SAAS,EAAzB,MAAM;IACY,gBAAgB,EAAlC,MAAM,EAAE;IACmB,kBAAkB,EAA7C,UAAU,MAAM,CAAC;IACQ,MAAM,GAA/B,cAAc;IACZ,MAAM,CAsDlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,6KAFa;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAiJjE;AAED;;;;;;;;;;GAUG;AACH;IAP+B,KAAK;IACT,IAAI,EAApB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,QAAQ,EAAxB,MAAM;IACY,gBAAgB,EAAlC,MAAM,EAAE;IACN,MAAM,CAoClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qUAFa;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CAwN7D;AAED;;;;;;;;GAQG;AACH,+EAHW,UAAU,MAAM,CAAC,GACf;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAe/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IAtB+B,KAAK;IACT,OAAO,EAAvB,MAAM;IACkB,QAAQ;IACd,QAAQ,EAA1B,MAAM,EAAE;IACQ,aAAa,EAA7B,MAAM;IACU,aAAa,EAA7B,MAAM;IACuB,MAAM;IACnB,wBAAwB,EAAxC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,kBAAkB,EAAlC,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,oBAAoB,EAApC,MAAM;IAC6B,sBAAsB,EAAzD;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC;IAGU,sBAAsB,EAAzD,yBAAyB;IACA,MAAM,GAA/B,cAAc;IACiD,aAAa,GAA5E,OAAO,wBAAwB,EAAE,iBAAiB,EAAE;IAElD,MAAM,CA8RlB;+BAr8B8B,qBAAqB;0CA9BV,uCAAuC"}