@woosh/meep-engine 3.31.0 → 3.33.0

package/src/shade/renderer/rasterize/expand/bucket/mesh/shader_instances_rasterization_bucket_sort.js

@@ -1,89 +1,135 @@
-import { u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
-import { COLLECTION_U32_STRUCT_READ } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
-import { MATERIAL_METADATA_STRUCT } from "../../../../material/MATERIAL_METADATA_STRUCT.js";
-import { chunk_scene_database_access } from "../../../../scene/chunk_scene_database_access.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 { chunk_rasterization_material_bucket } from "../chunk_rasterization_material_bucket.js";
-import { RASTERIZATION_BUCKET_LIMIT } from "../RASTERIZATION_BUCKET_LIMIT.js";
-import {
-    RASTERIZATION_BUCKET_SORT_OUTPUT_HEADER_STRUCT_WRITE
-} from "../RASTERIZATION_BUCKET_SORT_OUTPUT_HEADER_STRUCT_WRITE.js";
-
-
-export const RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_WRITE = WebGPUStruct.from({
-    headers: RASTERIZATION_BUCKET_SORT_OUTPUT_HEADER_STRUCT_WRITE,
-    elements: WebGPUArray.u32
-});
-
-const OFFSETS_TYPE = WebGPUArray.from(u32, RASTERIZATION_BUCKET_LIMIT);
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
-    .addStorageBuffer("materials", WebGPUArray.from(MATERIAL_METADATA_STRUCT))
-
-resources.createGroup()
-    .addStorageBuffer("input", COLLECTION_U32_STRUCT_READ)
-    .addStorageBuffer("offsets", OFFSETS_TYPE)
-    .addStorageBuffer("output", RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_WRITE, true)
-
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
-fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
-
-    let index = global_id.x;
-    
-    let input_size = min(input.count, arrayLength(&input.elements));
-    
-    if(index >= input_size){
-        return;
-    }
-    
-    let mesh_index = input.elements[index];
-
-    let mesh = scene_read_mesh(&scene_database, mesh_index);
-
-    let material = materials[mesh.material];
-    
-    let bucket_index = rasterization_material_bucket(
-        material.transparency_mode,
-        material.draw_mode,
-        material.draw_side
-    );
-    
-    let element_offset = atomicAdd(&output.headers[bucket_index].count, 1u);
-    
-    let bucket_offset = offsets[bucket_index];
-    
-    if(element_offset == 0u){
-        // first element in bucket, write offset as well
-        output.headers[bucket_index].offset = bucket_offset;
-    }
-    
-    let output_offset = bucket_offset + element_offset;
-    
-    if(output_offset < arrayLength(&output.elements)){
-        // guard against out-of-bounds access
-        output.elements[output_offset] = mesh_index;
-    }
-    
-}
-    `, [
-        chunk_rasterization_material_bucket,
-        chunk_scene_database_access,
-    ]
-);
-
-export const shader_instances_rasterization_bucket_sort = ComputeShader.from({
-    label: 'Rasterization bucket sort',
-    resources,
-    body,
+import { assert } from "../../../../../../core/assert.js";
+import { u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { MATERIAL_METADATA_STRUCT } from "../../../../material/MATERIAL_METADATA_STRUCT.js";
+import { chunk_scene_database_access } from "../../../../scene/chunk_scene_database_access.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 { chunk_rasterization_material_bucket } from "../chunk_rasterization_material_bucket.js";
+import { RASTERIZATION_BUCKET_LIMIT } from "../RASTERIZATION_BUCKET_LIMIT.js";
+import {
+    RASTERIZATION_BUCKET_SORT_OUTPUT_HEADER_STRUCT_WRITE
+} from "../RASTERIZATION_BUCKET_SORT_OUTPUT_HEADER_STRUCT_WRITE.js";
+
+
+export const RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_WRITE = WebGPUStruct.from({
+    headers: RASTERIZATION_BUCKET_SORT_OUTPUT_HEADER_STRUCT_WRITE,
+    elements: WebGPUArray.u32
+});
+
+const OFFSETS_TYPE = WebGPUArray.from(u32, RASTERIZATION_BUCKET_LIMIT);
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .addStorageBuffer("materials", WebGPUArray.from(MATERIAL_METADATA_STRUCT))
+
+resources.createGroup()
+    .addStorageBuffer("input", COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer("offsets", OFFSETS_TYPE)
+    .addStorageBuffer("output", RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_WRITE, true)
+
+
+const GROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+
+// one lane per bucket makes the workgroup's claims
+assert.lessThanOrEqual(RASTERIZATION_BUCKET_LIMIT, GROUP_SIZE);
+
+/**
+ * Every element used to claim its slot with an `atomicAdd(&output.headers[bucket].count, 1u)` of
+ * its own. The address comes from the material, so nothing aggregated it, and every survivor of a
+ * view queued on its bucket's one counter: 0.47-0.80 ns a survivor, the largest non-raster pass of
+ * a view.
+ *
+ * Instead each lane ranks itself within its workgroup, in workgroup memory, and one lane per bucket
+ * claims the workgroup's whole run with a single global atomic. Measured on a 4090 against
+ * aggregating per subgroup (a ballot per bit of the bucket index, one atomic per bucket a wave
+ * holds), at 2M rows: 62 against 63 us for 1.48M elements of one bucket, 13 against 22 us for
+ * the main view's 774K, and 62 against 107 us for the 1.48M with six buckets to a wave. Waves on
+ * mixed content hold several buckets, and a workgroup claims each of them a quarter as often.
+ */
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+var<workgroup> wg_count: array<atomic<u32>, ${RASTERIZATION_BUCKET_LIMIT}>;
+var<workgroup> wg_base: array<u32, ${RASTERIZATION_BUCKET_LIMIT}>;
+    
+@compute @workgroup_size(${GROUP_SIZE})
+fn main(
+    @builtin(global_invocation_id) global_id : vec3<u32>,
+    @builtin(local_invocation_index) local_index : u32,
+){
+    
+    let index = global_id.x;
+    
+    let input_size = min(input.count, arrayLength(&input.elements));
+    
+    // a lane past the input does not return: every lane of the workgroup has to reach the barriers
+    let valid = index < input_size;
+    
+    var mesh_index = 0u;
+    var bucket_index = 0u;
+    var rank = 0u;
+    
+    if(valid){
+        mesh_index = input.elements[index];
+    
+        let mesh = scene_read_mesh(&scene_database, mesh_index);
+    
+        let material = materials[mesh.material];
+    
+        bucket_index = rasterization_material_bucket(
+            material.transparency_mode,
+            material.draw_mode,
+            material.draw_side
+        );
+    
+        // this element's place in the workgroup's run of its bucket
+        rank = atomicAdd(&wg_count[bucket_index], 1u);
+    }
+    
+    workgroupBarrier();
+    
+    // one lane per bucket claims the workgroup's whole run with one atomic
+    if(local_index < ${RASTERIZATION_BUCKET_LIMIT}u){
+        let run_length = atomicLoad(&wg_count[local_index]);
+    
+        if(run_length > 0u){
+            let run_offset = atomicAdd(&output.headers[local_index].count, run_length);
+    
+            if(run_offset == 0u){
+                // first element in bucket, write offset as well
+                output.headers[local_index].offset = offsets[local_index];
+            }
+    
+            wg_base[local_index] = run_offset;
+        }
+    }
+    
+    workgroupBarrier();
+    
+    if(valid){
+        let output_offset = offsets[bucket_index] + wg_base[bucket_index] + rank;
+    
+        if(output_offset < arrayLength(&output.elements)){
+            // guard against out-of-bounds access
+            output.elements[output_offset] = mesh_index;
+        }
+    }
+    
+}
+    `, [
+        chunk_rasterization_material_bucket,
+        chunk_scene_database_access,
+    ]
+);
+
+export const shader_instances_rasterization_bucket_sort = ComputeShader.from({
+    label: 'Rasterization bucket sort',
+    resources,
+    body,
 })

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

@@ -1 +1 @@
-{"version":3,"file":"shader_meshlets_rasterization_bucket_sort.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/rasterize/expand/bucket/meshlet/shader_meshlets_rasterization_bucket_sort.js"],"names":[],"mappings":"AA2FA,sEAIE;8BAtF4B,qCAAqC"}
+{"version":3,"file":"shader_meshlets_rasterization_bucket_sort.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/rasterize/expand/bucket/meshlet/shader_meshlets_rasterization_bucket_sort.js"],"names":[],"mappings":"AA0HA,sEAIE;8BApH4B,qCAAqC"}

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

@@ -1,3 +1,4 @@
+import { assert } from "../../../../../../core/assert.js";
 import { u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
@@ -33,52 +34,82 @@ resources.createGroup()
     .addStorageBuffer("output", RASTERIZATION_MESHLET_BUCKET_SORT_OUTPUT_STRUCT_WRITE, true)
 
 
+const GROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+
+// one lane per bucket makes the workgroup's claims
+assert.lessThanOrEqual(RASTERIZATION_BUCKET_LIMIT, GROUP_SIZE);
+
+/**
+ * The meshlet twin of {@link shader_instances_rasterization_bucket_sort}: the same workgroup
+ * histogram, for the same reason.
+ */
 const body = CodeChunk.from(
     //language=WGSL
     `
-@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
+var<workgroup> wg_count: array<atomic<u32>, ${RASTERIZATION_BUCKET_LIMIT}>;
+var<workgroup> wg_base: array<u32, ${RASTERIZATION_BUCKET_LIMIT}>;
+    
+@compute @workgroup_size(${GROUP_SIZE})
 fn main(
     @builtin(workgroup_id) workgroup_id : vec3<u32>,
     @builtin(local_invocation_index) local_index : u32,
 ){
-
+    
     // folded dispatch — see IndirectComputeCommandBuildPass
-    let index = folded_workgroup_index(workgroup_id) * ${COMPUTE_SHADER_DEFAULT_GROUP_SIZE}u + local_index;
+    let index = folded_workgroup_index(workgroup_id) * ${GROUP_SIZE}u + local_index;
     
     let input_size = min(input.count, arrayLength(&input.elements));
     
-    if(index >= input_size){
-        return;
+    // a lane past the input does not return: every lane of the workgroup has to reach the barriers
+    let valid = index < input_size;
+    
+    var bucket_index = 0u;
+    var rank = 0u;
+    
+    if(valid){
+        let mesh_index = input.elements[index].mesh;
+    
+        let mesh = scene_read_mesh(&scene_database, mesh_index);
+    
+        let material = materials[mesh.material];
+    
+        bucket_index = rasterization_material_bucket(
+            material.transparency_mode,
+            material.draw_mode,
+            material.draw_side
+        );
+    
+        // this element's place in the workgroup's run of its bucket
+        rank = atomicAdd(&wg_count[bucket_index], 1u);
     }
     
-    let meshlet_def = input.elements[index];
-
-    let mesh_index = meshlet_def.mesh;
-
-    let mesh = scene_read_mesh(&scene_database, mesh_index);
-
-    let material = materials[mesh.material];
+    workgroupBarrier();
     
-    let bucket_index = rasterization_material_bucket(
-        material.transparency_mode,
-        material.draw_mode,
-        material.draw_side
-    );
+    // one lane per bucket claims the workgroup's whole run with one atomic
+    if(local_index < ${RASTERIZATION_BUCKET_LIMIT}u){
+        let run_length = atomicLoad(&wg_count[local_index]);
     
-    let element_offset = atomicAdd(&output.headers[bucket_index].count, 1u);
+        if(run_length > 0u){
+            let run_offset = atomicAdd(&output.headers[local_index].count, run_length);
     
-    let bucket_offset = offsets[bucket_index];
+            if(run_offset == 0u){
+                // first element in bucket, write offset as well
+                output.headers[local_index].offset = offsets[local_index];
+            }
     
-    if(element_offset == 0u){
-        // first element in bucket, write offset as well
-        output.headers[bucket_index].offset = bucket_offset;
+            wg_base[local_index] = run_offset;
+        }
     }
     
-    let output_offset = bucket_offset + element_offset;
+    workgroupBarrier();
+    
+    if(valid){
+        let output_offset = offsets[bucket_index] + wg_base[bucket_index] + rank;
     
-    if(output_offset < arrayLength(&output.elements)){
-        // guard against out-of-bounds access
-        output.elements[output_offset] = meshlet_def;
+        if(output_offset < arrayLength(&output.elements)){
+            // guard against out-of-bounds access
+            output.elements[output_offset] = input.elements[index];
+        }
     }
     
 }

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,CA0J3D;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":"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"}

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

@@ -13,8 +13,8 @@ import { graph_vgeo_expand_if_enabled } from "../../geometry/virtual/runtime/gra
 import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
 import { construct_primitive_state } from "../bucket/construct_primitive_state.js";
 import { rasterization_opaque_buckets } from "../bucket/rasterization_opaque_buckets.js";
-import { rasterization_has_opaque_bucket } from "../bucket/rasterization_has_opaque_bucket.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";
 
@@ -122,29 +122,39 @@ export function graph_rasterize_scene_fast_raw({
         is_first_draw = false;
     }
 
-    // alpha-tested: reuse the existing native pass but skip HZB filtering by passing hzb=-1
-    if (job.alpha_tested_pass !== undefined) {
-        /**
-         * The opaque path's first draw is the only thing that clears the visibility-buffer colour
-         * attachments and the depth attachment — the clear values live on the opaque pass descriptor
-         * and reach the targets through its `loadOp`, and every pass after it is recorded with
-         * `load`. When the scene has no opaque bucket that draw never happens, so the first pass that
-         * does run owns the clear. The alpha-tested descriptor carries the same clear values
-         * (`[0,0,0,0]`, VIZ_BUFFER_INVALID_MESH_VALUE, DEPTH_BACKGROUND_VALUE), so handing it over
-         * changes nothing about what the targets are cleared to.
-         *
-         * Wherever an opaque bucket exists — nearly every scene — this starts true and every call
-         * below asks for `false`, exactly as before.
-         */
-        let targets_cleared = rasterization_has_opaque_bucket(active_buckets);
+    if (is_first_draw) {
+        /*
+         No opaque bucket, so no draw above cleared the target, and the rectangle holds whatever was
+         there before: in the atlas, the shadow of whatever was in the scene then; in a point light's
+         cube, which is a pooled transient, whatever the pool's last user left. The clear goes in the
+         first draw's place, and everything after this loads.
+        */
+        const cleared = graph_clear_raster_targets({
+            graph,
+            depth: target_depth,
+            color_targets: targets_color,
+            pass_descriptor: job.opaque_pass,
+            viewport,
+        });
 
+        target_depth = cleared.depth;
+        targets_color = cleared.color_targets;
+    }
 
+    // alpha-tested: reuse the existing native pass but skip HZB filtering by passing hzb=-1
+    if (job.alpha_tested_pass !== undefined) {
+        /*
+         Both alpha-tested passes load, never clear: the targets were cleared above, by the first
+         opaque draw or in its place. The clear used to be handed to the first alpha-tested draw, which
+         left a scene with neither kind of draw — nothing in it, or only transparent surfaces — with
+         nothing clearing at all.
+        */
         const alpha_tested_front = graph_rasterize_meshes_alpha_tested({
             graph,
             buckets: gr_render_buckets,
             view_ctx: view_ctx,
             render_pass_descriptor: job.alpha_tested_pass,
-            clear_target: !targets_cleared,
+            clear_target: false,
             side: ShadeDrawSide.Front,
             cull_policy: job.cull_policy,
             limits,
@@ -157,14 +167,13 @@ export function graph_rasterize_scene_fast_raw({
 
         target_depth = alpha_tested_front.depth;
         targets_color = alpha_tested_front.color_targets;
-        targets_cleared = targets_cleared || alpha_tested_front.executed;
 
         const alpha_tested_double = graph_rasterize_meshes_alpha_tested({
             graph,
             buckets: gr_render_buckets,
             view_ctx: view_ctx,
             render_pass_descriptor: job.alpha_tested_pass,
-            clear_target: !targets_cleared,
+            clear_target: false,
             side: ShadeDrawSide.Double,
             cull_policy: job.cull_policy,
             limits,
@@ -177,7 +186,6 @@ export function graph_rasterize_scene_fast_raw({
 
         target_depth = alpha_tested_double.depth;
         targets_color = alpha_tested_double.color_targets;
-        targets_cleared = targets_cleared || alpha_tested_double.executed;
     }
 
     return {target_depth, targets_color};

package/src/shade/renderer/rasterize/graph_clear_raster_targets.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Clear a rasterization's targets to what its first draw would have cleared them to, for a
+ * rasterization that has no first draw.
+ *
+ * A rasterization clears its targets through the `loadOp` of its first draw, which is its first opaque
+ * bucket's; everything after that loads. A scene with no opaque bucket has no such draw, and a scene
+ * with nothing in it has no draw at all — and no target starts a frame empty, so the frame then reads
+ * whatever it last held. The renderer's own targets outlive the frame: a mesh taken out of the scene
+ * stays in them, and so does the depth an extension wrote over the scene after the rasterizer was done.
+ * A graph transient comes out of a pool holding whatever its last user left, which is what a point
+ * light's cube faces are. This takes that draw's place.
+ *
+ * The clear values are the pass descriptor's own, so what the targets hold afterwards is exactly what
+ * the draw's clear would have left. A viewport short of the whole target fills that rectangle alone —
+ * shadow maps share an atlas, and a clear load op would erase every other map in it.
+ *
+ * @param {object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.depth depth texture resource ID
+ * @param {number[]} options.color_targets colour texture resource IDs, in the order of the pass
+ * descriptor's colour attachments
+ * @param {RenderPassDescriptor} options.pass_descriptor the pass whose first draw this stands in for;
+ * the clear values are read off it
+ * @param {number[]} [options.viewport] [x, y, width, height]; a width or height of -1 runs to the edge of
+ * the target, and [0, 0, -1, -1] is the whole target
+ * @returns {{depth: number, color_targets: number[]}} the depth and colour handles, cleared
+ */
+export function graph_clear_raster_targets({ graph, depth, color_targets, pass_descriptor, viewport, }: {
+    graph: FrameGraph;
+    depth: number;
+    color_targets: number[];
+    pass_descriptor: RenderPassDescriptor;
+    viewport?: number[];
+}): {
+    depth: number;
+    color_targets: number[];
+};
+//# sourceMappingURL=graph_clear_raster_targets.d.ts.map

package/src/shade/renderer/rasterize/graph_clear_raster_targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_clear_raster_targets.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/rasterize/graph_clear_raster_targets.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAV+B,KAAK;IACT,KAAK,EAArB,MAAM;IACY,aAAa,EAA/B,MAAM,EAAE;IAEsB,eAAe;IAE1B,QAAQ,GAA3B,MAAM,EAAE;IAEN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA4EpD"}

package/src/shade/renderer/rasterize/graph_clear_raster_targets.js

@@ -0,0 +1,105 @@
+import { assert } from "../../../core/assert.js";
+import { texture_fill_rectangle } from "../texture/util/texture_fill_rectangle.js";
+
+/**
+ * Clear a rasterization's targets to what its first draw would have cleared them to, for a
+ * rasterization that has no first draw.
+ *
+ * A rasterization clears its targets through the `loadOp` of its first draw, which is its first opaque
+ * bucket's; everything after that loads. A scene with no opaque bucket has no such draw, and a scene
+ * with nothing in it has no draw at all — and no target starts a frame empty, so the frame then reads
+ * whatever it last held. The renderer's own targets outlive the frame: a mesh taken out of the scene
+ * stays in them, and so does the depth an extension wrote over the scene after the rasterizer was done.
+ * A graph transient comes out of a pool holding whatever its last user left, which is what a point
+ * light's cube faces are. This takes that draw's place.
+ *
+ * The clear values are the pass descriptor's own, so what the targets hold afterwards is exactly what
+ * the draw's clear would have left. A viewport short of the whole target fills that rectangle alone —
+ * shadow maps share an atlas, and a clear load op would erase every other map in it.
+ *
+ * @param {object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.depth depth texture resource ID
+ * @param {number[]} options.color_targets colour texture resource IDs, in the order of the pass
+ * descriptor's colour attachments
+ * @param {RenderPassDescriptor} options.pass_descriptor the pass whose first draw this stands in for;
+ * the clear values are read off it
+ * @param {number[]} [options.viewport] [x, y, width, height]; a width or height of -1 runs to the edge of
+ * the target, and [0, 0, -1, -1] is the whole target
+ * @returns {{depth: number, color_targets: number[]}} the depth and colour handles, cleared
+ */
+export function graph_clear_raster_targets({
+                                               graph,
+                                               depth,
+                                               color_targets,
+                                               pass_descriptor,
+                                               viewport = [0, 0, -1, -1],
+                                           }) {
+    assert.defined(graph, 'graph');
+    assert.isNonNegativeInteger(depth, 'depth');
+    assert.isArray(color_targets, 'color_targets');
+    assert.equal(pass_descriptor.isRenderPassDescriptor, true, "pass_descriptor must be a RenderPassDescriptor");
+    assert.equal(color_targets.length, pass_descriptor.colorAttachments.length, 'one colour target per colour attachment of the pass');
+
+    /**
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(data, resources, context) {
+        const encoder = context.encoder;
+
+        /**
+         * @type {GPUTextureContext}
+         */
+        const depth_texture = resources.get(data.depth);
+
+        /**
+         * @type {GPUTextureContext[]}
+         */
+        const color_textures = data.color_targets.map(id => resources.get(id));
+
+        const x = viewport[0];
+        const y = viewport[1];
+        const width = viewport[2] >= 0 ? viewport[2] : depth_texture.width - x;
+        const height = viewport[3] >= 0 ? viewport[3] : depth_texture.height - y;
+
+        const is_whole_target = x === 0 && y === 0 && width === depth_texture.width && height === depth_texture.height;
+
+        if (is_whole_target) {
+            const gpu_descriptor = pass_descriptor.toGPU({
+                colorTargets: color_textures,
+                depthTarget: depth_texture,
+                loadOp: "clear",
+                storeOp: "store",
+            });
+
+            // not the draw's pipeline label: nothing is drawn
+            gpu_descriptor.label = "Clear rasterization targets";
+
+            encoder.beginRenderPass(gpu_descriptor).end();
+
+            return;
+        }
+
+        const rectangle = [x, y, width, height];
+
+        for (let i = 0; i < color_textures.length; i++) {
+            texture_fill_rectangle(encoder, color_textures[i], rectangle, pass_descriptor.colorAttachments[i].clearValue);
+        }
+
+        texture_fill_rectangle(encoder, depth_texture, rectangle, [pass_descriptor.depthStencilAttachment.depthClearValue]);
+    }
+
+    const data = {};
+
+    const pass = graph.add("clear raster targets", data, execute);
+
+    data.depth = pass.write(depth);
+    data.color_targets = color_targets.map(pass.write, pass);
+
+    return {
+        depth: data.depth,
+        color_targets: data.color_targets,
+    };
+}

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_LEDGER.md

@@ -887,3 +887,23 @@ reach — the dynamic-mesh directory, the orchestrator run with a real channel,
 93 tests — passes, and the type check is at budget. On the Metal adapter, `@builtin(sample_mask)` and
 `@interpolate(perspective, centroid)` compile and the multisampled pipeline builds; no uncaptured device
 errors, including 240 frames of a live trail on a moving path, fading in and out.
+
+## 25. A trail's draw constants go up once a frame — 2026-09-27
+
+Entry 23 left each live mesh's constants built twice — a transient uniform and a bind group of its own
+for the splat, and again for the draw — noted, not shaved. They are shaved here, as part of moving
+every dynamic mesh's per-draw constants into a table (CHANGELOG, Unreleased, Rendering): the
+occupancy, after its upload, writes the frame's `GPUDynamicMeshDrawList` — one transient storage
+buffer and one write per 1,024 draws — and the splat and the draw both bind it and name their rows by
+`first_instance`. The splat's layout is four groups now (constants, geometry, warp, volume), which is
+WebGPU's default `maxBindGroups`.
+
+**Measured** with 1,500 live meshes through the channel at 1280×720 on the RTX 4090, asserts
+stripped, paired: 9.8–11.4 ms of CPU a frame to 2.0–2.5; 3,032 copies a frame to 34 and 7,624
+`setBindGroup` to 3,131. The pictures after equal frame counts are bit-identical to before.
+
+**Verified.** `DynamicMeshAVBOITChannel.draws.spec.js` checks the splat and the draw read each mesh's own
+constants from one table, and fails with a draw pass that uploads its own copy (two tables).
+`chunk_dynamic_mesh_vertex.spec.js` runs the shared AVBOIT vertex stage on the emulator and checks a
+vertex is carried by the row its draw names. The other half of the item — the emptiness query and the
+gather both walking the first live mesh's triangles — is left as it was.

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.d.ts

@@ -12,7 +12,7 @@
  * @param {Set<number>} active_buckets IDs of buckets that have any materials that are active.
  * @param {number[]} [viewport] optional viewport definition, if not provided, will use the entire render target. Useful for drawing multiple views into the same render target.
  * @param {Readonly<Record<number, GPUCullMode>>} [cull_policy] side→cullMode mapping; defaults to {@link CullPolicy.Standard}
- * @returns {{instances_maybe:number, meshlets_maybe:number, depth:number, color_targets:number[]}} the "maybe visible" sets, and the depth and colour handles produced by the rasterization
+ * @returns {{instances_maybe:number, meshlets_maybe:number, depth:number, color_targets:number[]}} the "maybe visible" sets, and the depth and colour handles produced by the rasterization — cleared whether or not any bucket drew
  */
 export function graph_rasterize_partial_opaque({ graph, buckets, view, render_pass_descriptor, limits, depth, raster_color_targets, hzb, viewport, active_buckets, cull_policy, }: FrameGraph): {
     instances_maybe: number;

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_partial_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,gMAFa;IAAC,eAAe,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAgMjG"}
+{"version":3,"file":"graph_rasterize_partial_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;GAeG;AACH,gMAFa;IAAC,eAAe,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAmNjG"}