@woosh/meep-engine 3.29.0 → 3.31.0

package/src/shade/renderer/postprocess/taa/chunk_taa_tonemap.js

@@ -1,18 +1,39 @@
 import { chunk_rgb_to_luminance } from "../../shader/chunk/color/chunk_rgb_to_luminance.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 
+/**
+ * The largest value an `rgba16float` target can hold. A shading result above it stores as `+Inf`.
+ * @type {number}
+ */
+const HALF_MAX = 65504;
+
 /**
  * Slide 20 of "High Quality Temporal Supersampling" by Brian Karis at SIGGRAPH 2014.
+ *
+ * The guard on the way in is a FINITE clamp, not just a non-negative one, because the colour target
+ * is `rgba16float` and a shading result above its range stores as `+Inf` — a bright emissive, a
+ * specular lobe with a small denominator, a light with a large intensity. `rgb / (1 + luma)` is then
+ * `Inf / Inf`, which is NaN, and `rgb_to_YCoCg` spreads it across all three channels.
+ *
+ * That matters here more than it would anywhere else: the result is written to the next frame's
+ * history, and the resolve picks the valid-history branch on velocity, occlusion and screen bounds
+ * and never on the colour, so `mix(current, NaN, weight)` reproduces the NaN every frame. One frame
+ * of overbright shading leaves a pixel no camera motion clears, and a Catmull-Rom tap then spreads
+ * it into a blot.
  */
 export const chunk_taa_tonemap = CodeChunk.from(
     //language=WGSL
     `
 fn taa_tonemap(rgb: vec3<f32>) -> vec3<f32>{
-    let luma = rgb_to_luminance(rgb);
-    
-    return rgb / (1 + luma);
+    // NaN fails every comparison including with itself, so this is the componentwise "is it a
+    // number" the language gives us; +Inf is brought back to what the target could have held.
+    let finite = select(vec3<f32>(0.0), min(rgb, vec3<f32>(${HALF_MAX}f)), rgb == rgb);
+
+    let luma = rgb_to_luminance(finite);
+
+    return finite / (1 + luma);
 }
     `, [
         chunk_rgb_to_luminance
     ]
-);
+);

package/src/shade/renderer/postprocess/taa/shader_depth_occlusion_clip.d.ts

@@ -1,5 +1,13 @@
 /**
+ * 9-tap depth dilation, returning the dilated depth and the *coordinate* of the nearest sample.
+ *
  * NOTE: uses inverted depth variant
+ *
+ * The walk is {@link chunk_find_nearest_depth}, which the NSS preprocess pass shares — the two used to
+ * carry the identical offset table, batched loads, on-screen guard and reverse-Z comparison each, and
+ * differed only in returning the coordinate rather than the offset. This name is kept because it is a
+ * published export and because the coordinate is what this shader wants.
+ *
  * @see https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/54fbaafdc34716811751bea5032700e78f5a0f33/sdk/include/FidelityFX/gpu/frameinterpolation/ffx_frameinterpolation_reconstruct_dilated_velocity_and_previous_depth.h#L52
  * @type {CodeChunk}
  */

package/src/shade/renderer/postprocess/taa/shader_depth_occlusion_clip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_depth_occlusion_clip.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/taa/shader_depth_occlusion_clip.js"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,2CAFU,SAAS,CA0DjB;AAqCF,sDAaG;0BA/HuB,oCAAoC;4BAClC,6BAA6B"}
+{"version":3,"file":"shader_depth_occlusion_clip.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/taa/shader_depth_occlusion_clip.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;GAYG;AACH,2CAFU,SAAS,CAsBjB;AAqCF,sDAaG;0BApGuB,oCAAoC;4BAElC,6BAA6B"}

package/src/shade/renderer/postprocess/taa/shader_depth_occlusion_clip.js

@@ -1,6 +1,6 @@
 import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_is_on_screen_i32 } from "../../shader/chunk/texture/chunk_is_on_screen_i32.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_find_nearest_depth } from "../chunk_find_nearest_depth.js";
 import { ImageShader } from "../../shader/ImageShader.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
@@ -17,7 +17,15 @@ resources.createGroup()
 ;
 
 /**
+ * 9-tap depth dilation, returning the dilated depth and the *coordinate* of the nearest sample.
+ *
  * NOTE: uses inverted depth variant
+ *
+ * The walk is {@link chunk_find_nearest_depth}, which the NSS preprocess pass shares — the two used to
+ * carry the identical offset table, batched loads, on-screen guard and reverse-Z comparison each, and
+ * differed only in returning the coordinate rather than the offset. This name is kept because it is a
+ * published export and because the coordinate is what this shader wants.
+ *
  * @see https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/54fbaafdc34716811751bea5032700e78f5a0f33/sdk/include/FidelityFX/gpu/frameinterpolation/ffx_frameinterpolation_reconstruct_dilated_velocity_and_previous_depth.h#L52
  * @type {CodeChunk}
  */
@@ -30,52 +38,16 @@ fn ffx_find_nearest_depth(
     iPxSize: vec2<i32>,
     fNearestDepthCoord: ptr<function, vec2<i32>>,
 ) -> f32 {
-    const iSampleCount = 9;
-    const iSampleOffsets = array<vec2<i32>,9>(
-        vec2(  0,  0 ),
-        vec2(  1,  0 ),
-        vec2(  0,  1 ),
-        vec2(  0, -1 ),
-        vec2( -1,  0 ),
-        vec2( -1,  1 ),
-        vec2(  1,  1 ),
-        vec2( -1, -1 ),
-        vec2(  1, -1 ),
-    );
+    var nearest_offset = vec2<i32>(0, 0);
 
-    // pull out the depth loads to allow SC to batch them
-    var depth:array<f32,9>;
-    var iSampleIndex = 0;
-    for (iSampleIndex = 0; iSampleIndex < iSampleCount; iSampleIndex++) {
+    let nearest_depth = find_nearest_depth(tDepth, iPxPos, iPxSize, &nearest_offset);
 
-        let iPos = iPxPos + iSampleOffsets[iSampleIndex];
-        depth[iSampleIndex] = textureLoad(tDepth, iPos, 0).r;
-    }
+    *fNearestDepthCoord = iPxPos + nearest_offset;
 
-    // find closest depth
-    *fNearestDepthCoord = iPxPos;
-    
-    var fNearestDepth = depth[0];
-    
-    for (iSampleIndex = 1; iSampleIndex < iSampleCount; iSampleIndex++) {
-
-        let iPos = iPxPos + iSampleOffsets[iSampleIndex];
-        
-        if (is_on_screen_i32(iPos, iPxSize)) {
-
-            let fNdDepth = depth[iSampleIndex];
-            if (fNdDepth > fNearestDepth) {
-                *fNearestDepthCoord = iPos;
-                fNearestDepth = fNdDepth;
-            }
-        }
-        
-    }
-    
-    return fNearestDepth;
+    return nearest_depth;
 }
     `, [
-        chunk_is_on_screen_i32,
+        chunk_find_nearest_depth,
     ]
 );
 

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

@@ -16,9 +16,11 @@ export class RasterizationJob {
      */
     opaque_pass: RenderPassDescriptor;
     /**
-     * @type {RenderPassDescriptor}
+     * A pipeline per material template — see {@link TemplatePassDescriptor}.
+     *
+     * @type {TemplatePassDescriptor}
      */
-    alpha_tested_pass: RenderPassDescriptor;
+    alpha_tested_pass: TemplatePassDescriptor;
     /**
      * @type {RenderTarget}
      */

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

@@ -1 +1 @@
-{"version":3,"file":"RasterizationJob.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/rasterize/RasterizationJob.js"],"names":[],"mappings":";;;;AAcA;IACI,sBAAmD;IAEnD;;;;;OAKG;IACH,aAFU,SAAS,OAAO,MAAM,cAAc,CAAC,CAEb;IAElC;;OAEG;IACH,kCAAW;IACX;;OAEG;IACH,wCAAiB;IAEjB;;OAEG;IACH,4BAAa;IAEb;;;OAGG;IACH,UAFU,MAAM,EAAE,CAEV;IAER;;OAEG;IACH,yBAAQ;IAER;;;OAGG;IACH,gBAAyB;IAEzB;;;OAGG;IACH,sBAA+B;CAClC"}
+{"version":3,"file":"RasterizationJob.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/rasterize/RasterizationJob.js"],"names":[],"mappings":";;;;AAcA;IACI,sBAAmD;IAEnD;;;;;OAKG;IACH,aAFU,SAAS,OAAO,MAAM,cAAc,CAAC,CAEb;IAElC;;OAEG;IACH,kCAAW;IACX;;;;OAIG;IACH,0CAAiB;IAEjB;;OAEG;IACH,4BAAa;IAEb;;;OAGG;IACH,UAFU,MAAM,EAAE,CAEV;IAER;;OAEG;IACH,yBAAQ;IAER;;;OAGG;IACH,gBAAyB;IAEzB;;;OAGG;IACH,sBAA+B;CAClC"}

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

@@ -28,7 +28,9 @@ export class RasterizationJob {
      */
     opaque_pass
     /**
-     * @type {RenderPassDescriptor}
+     * A pipeline per material template — see {@link TemplatePassDescriptor}.
+     *
+     * @type {TemplatePassDescriptor}
      */
     alpha_tested_pass
 

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

@@ -0,0 +1,57 @@
+/**
+ * @typedef {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../../device/pipeline/RenderPipelineManager.js").RenderPipelineManager} RenderPipelineManager
+ * @typedef {import("../material/template/ShadeMaterialTemplate.js").ShadeMaterialTemplate} ShadeMaterialTemplate
+ */
+/**
+ * A pass that draws materials of any template — the alpha-tested visibility and shadow passes, the
+ * transparent ones — and its pipeline for each template: the pass's own vertex stage and harness
+ * around the template's functions, with the template's group 0.
+ *
+ * Group 0 is laid out exactly as it is in the template's G-buffer pipeline, so the material's one
+ * bind group serves this pass too, and the pass binds it without building anything.
+ *
+ * The pass asks for a pipeline only when the template changes between consecutive materials, and
+ * the answer is held per device, per template and per cull mode, so a pass never clones or hashes a
+ * pipeline descriptor to find the one it already has.
+ */
+export class TemplatePassDescriptor extends RenderPassDescriptor {
+    /**
+     * @param {string} label names the render pass, which has no one pipeline to take a name from
+     * @param {function(ShadeMaterialTemplate): RenderPipelineDescriptor} build a template's pipeline,
+     *        at the pass's default primitive state
+     */
+    constructor(label: string, build: (arg0: ShadeMaterialTemplate) => RenderPipelineDescriptor);
+    /**
+     * The inherited single-pipeline helpers have no one pipeline to use here: the pass picks one per
+     * template, through {@link obtain_pipeline}.
+     */
+    begin(): void;
+    /**
+     * See {@link begin}.
+     */
+    drawIndirect(): void;
+    /**
+     * @param {ShadeMaterialTemplate} template
+     * @returns {RenderPipelineDescriptor}
+     */
+    template_pipeline_descriptor(template: ShadeMaterialTemplate): RenderPipelineDescriptor;
+    /**
+     * @param {RenderPipelineManager} render_pipelines
+     * @param {ShadeMaterialTemplate} template
+     * @param {GPUCullMode} cull_mode
+     * @returns {GPURenderPipeline}
+     */
+    obtain_pipeline(render_pipelines: RenderPipelineManager, template: ShadeMaterialTemplate, cull_mode: GPUCullMode): GPURenderPipeline;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isTemplatePassDescriptor: boolean;
+    #private;
+}
+export type RenderPipelineDescriptor = import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export type RenderPipelineManager = import("../../device/pipeline/RenderPipelineManager.js").RenderPipelineManager;
+export type ShadeMaterialTemplate = import("../material/template/ShadeMaterialTemplate.js").ShadeMaterialTemplate;
+import { RenderPassDescriptor } from "../shader/pass/RenderPassDescriptor.js";
+//# sourceMappingURL=TemplatePassDescriptor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TemplatePassDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/rasterize/TemplatePassDescriptor.js"],"names":[],"mappings":"AAKA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH;IAgBI;;;;OAIG;IACH,mBAJW,MAAM,gBACG,qBAAqB,KAAG,wBAAwB,EAWnE;IAED;;;OAGG;IACH,cAEC;IAED;;OAEG;IACH,qBAEC;IAED;;;OAGG;IACH,uCAHW,qBAAqB,GACnB,wBAAwB,CAYpC;IAED;;;;;OAKG;IACH,kCALW,qBAAqB,YACrB,qBAAqB,6CAsC/B;IAGL;;;OAGG;IACH,mCAFU,OAAO,CAEwC;;CANxD;uCAxHY,OAAO,8DAA8D,EAAE,wBAAwB;oCAC/F,OAAO,gDAAgD,EAAE,qBAAqB;oCAC9E,OAAO,+CAA+C,EAAE,qBAAqB;qCALrD,wCAAwC"}

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

@@ -0,0 +1,133 @@
+import { assert } from "../../../core/assert.js";
+import { PrimitiveState } from "../../descriptor/pipeline/render/PrimitiveState.js";
+import { rp_rewrite_for_primitive_state } from "../../device/pipeline/rp_rewrite_for_primitive_state.js";
+import { RenderPassDescriptor } from "../shader/pass/RenderPassDescriptor.js";
+
+/**
+ * @typedef {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../../device/pipeline/RenderPipelineManager.js").RenderPipelineManager} RenderPipelineManager
+ * @typedef {import("../material/template/ShadeMaterialTemplate.js").ShadeMaterialTemplate} ShadeMaterialTemplate
+ */
+
+/**
+ * A pass that draws materials of any template — the alpha-tested visibility and shadow passes, the
+ * transparent ones — and its pipeline for each template: the pass's own vertex stage and harness
+ * around the template's functions, with the template's group 0.
+ *
+ * Group 0 is laid out exactly as it is in the template's G-buffer pipeline, so the material's one
+ * bind group serves this pass too, and the pass binds it without building anything.
+ *
+ * The pass asks for a pipeline only when the template changes between consecutive materials, and
+ * the answer is held per device, per template and per cull mode, so a pass never clones or hashes a
+ * pipeline descriptor to find the one it already has.
+ */
+export class TemplatePassDescriptor extends RenderPassDescriptor {
+    /**
+     * @type {function(ShadeMaterialTemplate): RenderPipelineDescriptor}
+     */
+    #build;
+
+    /**
+     * @type {Map<ShadeMaterialTemplate, RenderPipelineDescriptor>}
+     */
+    #descriptors = new Map();
+
+    /**
+     * @type {WeakMap<RenderPipelineManager, Map<ShadeMaterialTemplate, Map<GPUCullMode, GPURenderPipeline>>>}
+     */
+    #pipelines = new WeakMap();
+
+    /**
+     * @param {string} label names the render pass, which has no one pipeline to take a name from
+     * @param {function(ShadeMaterialTemplate): RenderPipelineDescriptor} build a template's pipeline,
+     *        at the pass's default primitive state
+     */
+    constructor(label, build) {
+        super();
+
+        assert.isString(label, 'label');
+        assert.isFunction(build, 'build');
+
+        this.label = label;
+        this.#build = build;
+    }
+
+    /**
+     * The inherited single-pipeline helpers have no one pipeline to use here: the pass picks one per
+     * template, through {@link obtain_pipeline}.
+     */
+    begin() {
+        throw new Error(`'${this.label}' has a pipeline per material template and cannot begin with one; take it from obtain_pipeline`);
+    }
+
+    /**
+     * See {@link begin}.
+     */
+    drawIndirect() {
+        throw new Error(`'${this.label}' has a pipeline per material template and cannot draw with one; take it from obtain_pipeline`);
+    }
+
+    /**
+     * @param {ShadeMaterialTemplate} template
+     * @returns {RenderPipelineDescriptor}
+     */
+    template_pipeline_descriptor(template) {
+        let descriptor = this.#descriptors.get(template);
+
+        if (descriptor === undefined) {
+            descriptor = this.#build(template);
+
+            this.#descriptors.set(template, descriptor);
+        }
+
+        return descriptor;
+    }
+
+    /**
+     * @param {RenderPipelineManager} render_pipelines
+     * @param {ShadeMaterialTemplate} template
+     * @param {GPUCullMode} cull_mode
+     * @returns {GPURenderPipeline}
+     */
+    obtain_pipeline(render_pipelines, template, cull_mode) {
+        let by_template = this.#pipelines.get(render_pipelines);
+
+        if (by_template === undefined) {
+            by_template = new Map();
+
+            this.#pipelines.set(render_pipelines, by_template);
+        }
+
+        let by_cull_mode = by_template.get(template);
+
+        if (by_cull_mode === undefined) {
+            by_cull_mode = new Map();
+
+            by_template.set(template, by_cull_mode);
+        }
+
+        let pipeline = by_cull_mode.get(cull_mode);
+
+        if (pipeline === undefined) {
+            const descriptor = rp_rewrite_for_primitive_state(
+                this.template_pipeline_descriptor(template),
+                PrimitiveState.from({
+                    topology: "triangle-list",
+                    cullMode: cull_mode,
+                })
+            );
+
+            pipeline = render_pipelines.obtain(descriptor);
+
+            by_cull_mode.set(cull_mode, pipeline);
+        }
+
+        return pipeline;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+TemplatePassDescriptor.prototype.isTemplatePassDescriptor = true;

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

@@ -1 +1 @@
-{"version":3,"file":"construct_primitive_state.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/construct_primitive_state.js"],"names":[],"mappings":"AAsDA;;;;;;GAMG;AACH,qDALW,aAAa,QACb,aAAa,gBACb,SAAS,OAAO,MAAM,cAAc,CAAC,GACnC,cAAc,CAgB1B;;;;;;;;;;;;;;;;;;yBAjDS,SAAS,OAAO,MAAM,cAAc,CAAC;;;;;;;;;AAe/C;;;;;;;GAOG;AACH,yCAFU,cAAc,aAAa,CAAC,CAKnC;8BAnD2B,iCAAiC;8BACjC,iCAAiC;+BAFhC,uDAAuD"}
+{"version":3,"file":"construct_primitive_state.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/construct_primitive_state.js"],"names":[],"mappings":"AA4DA;;;;;;GAMG;AACH,qDALW,aAAa,QACb,aAAa,gBACb,SAAS,OAAO,MAAM,cAAc,CAAC,GACnC,cAAc,CA2B1B;;;;;;;;;;;;;;;;;;yBA5DS,SAAS,OAAO,MAAM,cAAc,CAAC;;;;;;;;;AAe/C;;;;;;;GAOG;AACH,yCAFU,cAAc,aAAa,CAAC,CAKnC;8BAzD2B,iCAAiC;8BACjC,iCAAiC;+BAFhC,uDAAuD"}

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

@@ -3,6 +3,12 @@ import { ShadeDrawMode } from "../../material/ShadeDrawMode.js";
 import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
 
 
+/**
+ * The only draw mode the meshlet rasterizer can express. A meshlet IS a cluster of triangles —
+ * there is no points or lines path through it, in either the opaque or the transparent pipeline.
+ *
+ * @type {Object<number, GPUPrimitiveTopology>}
+ */
 const lut_topology = {
     [ShadeDrawMode.Triangles]: "triangle-list",
 };
@@ -68,6 +74,17 @@ export function construct_primitive_state(
     const cullMode = cull_policy[side];
     const topology = lut_topology[draw_mode];
 
+    if (topology === undefined) {
+        // Not an assert: it is stripped, and this is precisely the case that used to pass silently
+        // in a shipped build. PrimitiveState.from substitutes DEFAULT_TOPOLOGY for an undefined
+        // one, so a Points or Lines material drew as triangles through the opaque path — while the
+        // transparent path, which hard-codes Triangles into its bucket filter, put the same
+        // material in a bucket no pass ever reads and dropped it on the floor without a word.
+        throw new Error(
+            `Draw mode ${draw_mode} has no topology: the meshlet rasterizer is triangle-only`
+        );
+    }
+
     return PrimitiveState.from({
         cullMode,
         topology,

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

@@ -1 +1 @@
-{"version":3,"file":"prepare_meshlet_draw_commands_by_material.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AACH,uKAJa;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,wBAAwB,EAAE,MAAM,CAAA;CAAC,CAgUnH"}
+{"version":3,"file":"prepare_meshlet_draw_commands_by_material.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AACH,uKAJa;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,wBAAwB,EAAE,MAAM,CAAA;CAAC,CA0VnH"}

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

@@ -58,6 +58,14 @@ export function graph_prepare_meshlet_draw_commands_by_material({
     assert.defined(materials, 'materials');
     assert.isNonNegativeInteger(bucket_id, 'bucket_index');
 
+    // Bound as the vec2u immediate of the meshlet filter, so a negative reads as ~4.3e9 and every
+    // meshlet overlaps a texel centre: the small-object rejection arm goes quiet without a word.
+    // graph_rasterize_meshes_alpha_tested used to forward the [0, 0, -1, -1] viewport sentinel
+    // here, and the main view never sets a viewport.
+    assert.isArrayLike(resolution, 'resolution');
+    assert.isPositiveInteger(resolution[0], 'resolution[0]');
+    assert.isPositiveInteger(resolution[1], 'resolution[1]');
+
     const copy_bucket_data = {};
 
     /**
@@ -141,8 +149,13 @@ export function graph_prepare_meshlet_draw_commands_by_material({
     graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, meshlets);
 
     if (hzb !== -1 && camera !== -1) {
-        // filter meshlets
-        const command = graph_build_indirect_dispatch_command(graph, meshlets, COMPUTE_SHADER_DEFAULT_GROUP_SIZE)
+        /*
+         Folded: a meshlet collection is past what one dispatch dimension reaches. See
+         IndirectComputeCommandBuildPass — and note that folding is only safe because
+         shader_hzb_meshlet_filter_1way_full reads its index through grid3d_to_index, which is the
+         other half of this change and not separable from it.
+        */
+        const command = graph_build_indirect_dispatch_command(graph, meshlets, COMPUTE_SHADER_DEFAULT_GROUP_SIZE, true)
 
 
         /**
@@ -216,8 +229,21 @@ export function graph_prepare_meshlet_draw_commands_by_material({
         usage: GPUBufferUsage.STORAGE,
     });
 
-    // 3. Build meshlet iterator command to be used in later passes
-    const meshlet_iterator_command = graph_build_indirect_dispatch_command(graph, meshlets, COMPUTE_SHADER_DEFAULT_GROUP_SIZE);
+    /*
+     3. Build meshlet iterator command to be used in later passes
+
+     Folded, like the filter above. This one drives three passes — the count and sort below and
+     the AVBOIT occupancy prepass the transparent path runs off the same collection — and all three
+     read their index through grid3d_to_index.
+
+     Clamping, which is what this did, silently covers the first 65,535 * 128 = 8,388,480 meshlets
+     of the bucket and no more: the count pass sees a prefix, the sort pass sees the same prefix,
+     and the draw commands built from the truncated prefix sum ask for fewer instances than the
+     collection holds. Nothing errors and no counter moves, because the collection's own count is
+     written by a different pass. The alpha-tested bucket is the foliage bucket, and the opaque
+     side hit exactly this and was folded for it.
+    */
+    const meshlet_iterator_command = graph_build_indirect_dispatch_command(graph, meshlets, COMPUTE_SHADER_DEFAULT_GROUP_SIZE, true);
 
     // 4. build meshlet counts by material
     const count_by_material_data = {};

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

@@ -0,0 +1,21 @@
+/**
+ * Whether the scene has anything in an opaque rasterization bucket.
+ *
+ * The opaque path clears the visibility-buffer colour attachments and the depth attachment on its
+ * first draw, and it is the only thing that does — every later pass is recorded with `load`. So a
+ * scene whose materials are all alpha-tested or transparent, which is an ordinary thing (a
+ * foliage-only vegetation view, a glass preview, a point light whose only casters are billboards),
+ * used to draw over the previous frame's contents: geometry depth-tested against stale occluders,
+ * and every pixel the alpha-tested pass did not cover keeping last frame's mesh and triangle ids for
+ * the deferred shading to resolve as real surfaces.
+ *
+ * This is what lets the composer hand the clear to the first pass that will actually run.
+ *
+ * @param {Set<number>} active_buckets bucket ids any material in the scene asks for
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function rasterization_has_opaque_bucket(active_buckets: Set<number>): boolean;
+//# sourceMappingURL=rasterization_has_opaque_bucket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rasterization_has_opaque_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/rasterization_has_opaque_bucket.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,gEANW,IAAI,MAAM,CAAC,GACT,OAAO,CAWnB"}

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

@@ -0,0 +1,28 @@
+import { rasterization_opaque_buckets } from "./rasterization_opaque_buckets.js";
+
+/**
+ * Whether the scene has anything in an opaque rasterization bucket.
+ *
+ * The opaque path clears the visibility-buffer colour attachments and the depth attachment on its
+ * first draw, and it is the only thing that does — every later pass is recorded with `load`. So a
+ * scene whose materials are all alpha-tested or transparent, which is an ordinary thing (a
+ * foliage-only vegetation view, a glass preview, a point light whose only casters are billboards),
+ * used to draw over the previous frame's contents: geometry depth-tested against stale occluders,
+ * and every pixel the alpha-tested pass did not cover keeping last frame's mesh and triangle ids for
+ * the deferred shading to resolve as real surfaces.
+ *
+ * This is what lets the composer hand the clear to the first pass that will actually run.
+ *
+ * @param {Set<number>} active_buckets bucket ids any material in the scene asks for
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function rasterization_has_opaque_bucket(active_buckets) {
+    for (const _bucket of rasterization_opaque_buckets(active_buckets)) {
+        return true;
+    }
+
+    return false;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"shader_count_meshlets_by_material.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/shader_count_meshlets_by_material.js"],"names":[],"mappings":"AAgEA,8DAIE;8BAzD4B,+BAA+B"}
+{"version":3,"file":"shader_count_meshlets_by_material.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/shader_count_meshlets_by_material.js"],"names":[],"mappings":"AAsEA,8DAIE;8BA9D4B,+BAA+B"}