@woosh/meep-engine 3.28.0 → 3.30.0

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":"AAmBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0I3D;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,CA0J3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}

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

@@ -13,6 +13,7 @@ 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_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";
@@ -123,13 +124,27 @@ export function graph_rasterize_scene_fast_raw({
 
     // 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);
+
 
         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: false,
+            clear_target: !targets_cleared,
             side: ShadeDrawSide.Front,
             cull_policy: job.cull_policy,
             limits,
@@ -142,13 +157,14 @@ 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: false,
+            clear_target: !targets_cleared,
             side: ShadeDrawSide.Double,
             cull_policy: job.cull_policy,
             limits,
@@ -161,6 +177,7 @@ 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/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":"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,CAmMjG"}
+{"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"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js

@@ -3,7 +3,6 @@ import { noop } from "../../../../core/function/noop.js";
 import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
 import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { shader_hzb_mesh_filter_2way } from "../cull/hzb/shader_hzb_mesh_filter_2way.js";
-import { U32_CONTAINER_STRUCT } from "../../shader/type/U32_CONTAINER_STRUCT.js";
 import { ShadeDrawMode } from "../../material/ShadeDrawMode.js";
 import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
 import { TransparencyMode } from "../../material/TransparencyMode.js";
@@ -96,16 +95,11 @@ export function graph_rasterize_partial_opaque({
             0
         );
 
-        // TODO(chrome-153): transient uniform, not an immediate value — see the shader.
-        const u_bucket_index = encoder.allocateTransientValueBuffer(U32_CONTAINER_STRUCT, {
-            value: bucket_index,
-        });
-
         // split 2 ways
         shader_hzb_mesh_filter_2way.dispatchIndirect({
             encoder,
             bindings: {
-                bucket_index: u_bucket_index,
+                bucket_index: { value: bucket_index },
                 camera_previous,
                 bucket_data: buckets,
                 scene_database: scene_ctx.scene_database_buffer,
@@ -187,7 +181,9 @@ export function graph_rasterize_partial_opaque({
 
         // ----------
 
-        const gr_command_iterate_meshlets_0 = graph_build_indirect_dispatch_command(graph, meshlet_expansion_0, COMPUTE_SHADER_DEFAULT_GROUP_SIZE);
+        // folded: a meshlet collection is past what one dispatch dimension reaches — see
+        // IndirectComputeCommandBuildPass
+        const gr_command_iterate_meshlets_0 = graph_build_indirect_dispatch_command(graph, meshlet_expansion_0, COMPUTE_SHADER_DEFAULT_GROUP_SIZE, true);
 
         const pass_data_meshlets_1 = new MeshletFilter2WayPassData();
 

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

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_remaining_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js"],"names":[],"mappings":"AAgGA;;;;;;;;;;;;;;;;;GAiBG;AACH,kOAFa;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAkGlD"}
+{"version":3,"file":"graph_rasterize_remaining_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js"],"names":[],"mappings":"AA6FA;;;;;;;;;;;;;;;;;GAiBG;AACH,kOAFa;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAkGlD"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js

@@ -9,7 +9,6 @@ import { graph_record_stat } from "../../util/graph_record_stat.js";
 import { build_indirect_compute_dispatch_command } from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
 import { graph_sort_meshlets_by_bucket_id } from "../expand/bucket/meshlet/graph_sort_meshlets_by_bucket_id.js";
 import { shader_meshlets_extract_bucket } from "../expand/bucket/meshlet/shader_meshlets_extract_bucket.js";
-import { U32_CONTAINER_STRUCT } from "../../shader/type/U32_CONTAINER_STRUCT.js";
 import { graph_mesh_filter_one_way } from "../expand/graph_mesh_filter_one_way.js";
 import { graph_meshlets_filter_one_way } from "../expand/graph_meshlets_filter_one_way.js";
 import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
@@ -49,6 +48,8 @@ function graph_extract_meshlets_from_bucket({
 
         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,
@@ -56,19 +57,15 @@ function graph_extract_meshlets_from_bucket({
             // the bucketed buffer header consists of pairs of u32 values (count,offset)
             bucket_id * (u32.size * 2),
             command,
-            0
+            0,
+            true,
         );
 
-        // TODO(chrome-153): transient uniform, not an immediate value — see the shader.
-        const u_bucket_index = encoder.allocateTransientValueBuffer(U32_CONTAINER_STRUCT, {
-            value: bucket_id,
-        });
-
         shader_meshlets_extract_bucket.dispatchIndirect({
             encoder,
             command,
             bindings: {
-                bucket_index: u_bucket_index,
+                bucket_index: { value: bucket_id },
                 bucket_data: buckets,
                 output: output,
             }

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

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_scene.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;GAWG;AACH;IAN+B,KAAK;IACC,GAAG;IACA,MAAM;IACjC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0MrE"}
+{"version":3,"file":"graph_rasterize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_scene.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;GAWG;AACH;IAN+B,KAAK;IACC,GAAG;IACA,MAAM;IACjC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0NrE"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_scene.js

@@ -11,6 +11,7 @@ import { RasterizationCollectionType } from "../expand/RasterizationCollectionTy
 import { graph_rasterize_meshes_alpha_tested } from "../native/graph_rasterize_meshes_alpha_tested.js";
 import { graph_rasterize_partial_opaque } from "./graph_rasterize_partial_opaque.js";
 import { graph_rasterize_remaining_opaque } from "./graph_rasterize_remaining_opaque.js";
+import { rasterization_has_opaque_bucket } from "../bucket/rasterization_has_opaque_bucket.js";
 
 /**
  * TODO:
@@ -155,13 +156,27 @@ export function graph_rasterize_scene({
 
 
     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);
+
 
         const alpha_tested_front = graph_rasterize_meshes_alpha_tested({
             graph,
             buckets: gr_render_buckets,
             view_ctx,
             render_pass_descriptor: job.alpha_tested_pass,
-            clear_target: false,
+            clear_target: !targets_cleared,
             side: ShadeDrawSide.Front,
             cull_policy: job.cull_policy,
             limits,
@@ -174,13 +189,14 @@ export function graph_rasterize_scene({
 
         gr_texture_depth = alpha_tested_front.depth;
         raster_color_targets = 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,
             render_pass_descriptor: job.alpha_tested_pass,
-            clear_target: false,
+            clear_target: !targets_cleared,
             side: ShadeDrawSide.Double,
             cull_policy: job.cull_policy,
             limits,
@@ -193,6 +209,7 @@ export function graph_rasterize_scene({
 
         gr_texture_depth = alpha_tested_double.depth;
         raster_color_targets = alpha_tested_double.color_targets;
+        targets_cleared = targets_cleared || alpha_tested_double.executed;
 
         if (alpha_tested_front.executed || alpha_tested_double.executed) {
 

package/src/shade/renderer/shader/type/WebGPUStruct.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebGPUStruct.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/type/WebGPUStruct.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH;IAqMI;;;;;;;;;;;;;;OAcG;IACH,8BAHW,MAAM,GACL,YAAY,CAiCvB;IAED;;;;OAIG;IACH,6BAHc,eAAe,KACjB,YAAY,CAiBvB;IA9PD;;;OAGG;IACH,uBAEC;IAVD,kBAEC;IAUD;;;OAGG;IACH,iBAFU,eAAe,EAAE,CAEf;IAmBZ;;;;OAIG;IACH,YAHW,YAAY,GACV,IAAI,CAYhB;IAED;;;OAGG;IACH,SAFY,YAAY,CAUvB;IAED;;;;;;;;OAQG;IACH,kBAJa,MAAM,CA+BlB;IAED;;;;;;OAMG;IACH,QAFa,IAAI,CAoChB;IAED,4BAYC;IAqGD;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAKnB;IAGD;;;;;OAKG;IACH,gBAJW,MAAM,GACL,eAAe,CAa1B;IA8GL;;;OAGG;IACH,mBAFU,OAAO,CAEc;;CAN9B;2BAza0B,iBAAiB;gCAEZ,sBAAsB"}
+{"version":3,"file":"WebGPUStruct.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/type/WebGPUStruct.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH;IAiNI;;;;;;;;;;;;;;OAcG;IACH,8BAHW,MAAM,GACL,YAAY,CAiCvB;IAED;;;;OAIG;IACH,6BAHc,eAAe,KACjB,YAAY,CAiBvB;IA1QD;;;OAGG;IACH,uBAEC;IAVD,kBAEC;IAUD;;;OAGG;IACH,iBAFU,eAAe,EAAE,CAEf;IAmBZ;;;;OAIG;IACH,YAHW,YAAY,GACV,IAAI,CAwBhB;IAED;;;OAGG;IACH,SAFY,YAAY,CAUvB;IAED;;;;;;;;OAQG;IACH,kBAJa,MAAM,CA+BlB;IAED;;;;;;OAMG;IACH,QAFa,IAAI,CAoChB;IAED,4BAYC;IAqGD;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAKnB;IAGD;;;;;OAKG;IACH,gBAJW,MAAM,GACL,eAAe,CAa1B;IA8GL;;;OAGG;IACH,mBAFU,OAAO,CAEc;;CAN9B;2BArb0B,iBAAiB;gCAEZ,sBAAsB"}

package/src/shade/renderer/shader/type/WebGPUStruct.js

@@ -83,6 +83,18 @@ export class WebGPUStruct extends WebGPUType {
         this.#size = other.#size;
         this.#align = other.#align;
 
+        /**
+         * Carried with the layout it describes. Without it a clone claimed a size and per-field
+         * offsets while reading as unbuilt, and `pack()` — which reorders the fields and then
+         * rebuilds only `if (this.#is_built)` — left the declaration in the packed order and the
+         * offsets in the unpacked one. WGSL would lay a field out at one address and
+         * `write_struct_value` seek to another, with no error anywhere.
+         */
+        this.#is_built = other.#is_built;
+
+        //the cached WGSL text belongs to the struct that built it
+        this.#declaration_chunk = undefined;
+
         this.fields = other.fields.map(f => f.clone());
 
         return this;

package/src/shade/renderer/shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Default per-frame shadow refresh budget, measured in **views** (one cube face counts as one
+ * view, one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
+ * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
+ * keeps the cost of the refresh step roughly proportional to how much work we're asking the
+ * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
+ * equivalent work to 6 spot lights.
+ *
+ * Directional lights are always refreshed unconditionally (they drive the whole scene) and
+ * their view cost is charged against the budget, so they effectively reduce the pool available
+ * for local lights that frame.
+ *
+ * Unused budget is carried over between frames when demand exceeds supply. This lets a light
+ * that's too expensive to fit in a single frame (e.g. a point needing 6 views when only 2 are
+ * free) eventually get its turn without permanently starving other lights.
+ *
+ * Only the starting value: what a scene actually spends is
+ * {@link GPUSceneShadowmapContext.update_budget}, which the renderer pushes from
+ * {@link Renderer.shadow_update_budget} every frame. Raise it to keep more lights current for more
+ * raster work per frame, lower it to spend less.
+ *
+ * @type {number}
+ */
+export const DEFAULT_SHADOWMAP_UPDATE_BUDGET: number;
+//# sourceMappingURL=DEFAULT_SHADOWMAP_UPDATE_BUDGET.d.ts.map

package/src/shade/renderer/shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DEFAULT_SHADOWMAP_UPDATE_BUDGET.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8CAFU,MAAM,CAEiC"}

package/src/shade/renderer/shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.js

@@ -0,0 +1,24 @@
+/**
+ * Default per-frame shadow refresh budget, measured in **views** (one cube face counts as one
+ * view, one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
+ * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
+ * keeps the cost of the refresh step roughly proportional to how much work we're asking the
+ * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
+ * equivalent work to 6 spot lights.
+ *
+ * Directional lights are always refreshed unconditionally (they drive the whole scene) and
+ * their view cost is charged against the budget, so they effectively reduce the pool available
+ * for local lights that frame.
+ *
+ * Unused budget is carried over between frames when demand exceeds supply. This lets a light
+ * that's too expensive to fit in a single frame (e.g. a point needing 6 views when only 2 are
+ * free) eventually get its turn without permanently starving other lights.
+ *
+ * Only the starting value: what a scene actually spends is
+ * {@link GPUSceneShadowmapContext.update_budget}, which the renderer pushes from
+ * {@link Renderer.shadow_update_budget} every frame. Raise it to keep more lights current for more
+ * raster work per frame, lower it to spend less.
+ *
+ * @type {number}
+ */
+export const DEFAULT_SHADOWMAP_UPDATE_BUDGET = 8;

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.d.ts

@@ -50,6 +50,16 @@ export class GPUSceneShadowmapContext {
      * @type {boolean}
      */
     use_tetrahedron_point_shadows: boolean;
+    /**
+     * @param {number} v views per frame, at least one. A higher budget keeps more lights current
+     *        and rasterizes more per frame; a lower one refreshes fewer of them per frame and
+     *        leaves the rest sampling older depth until their turn comes around.
+     */
+    set update_budget(v: number);
+    /**
+     * @returns {number} views this scene may spend refreshing shadowmaps each frame
+     */
+    get update_budget(): number;
     /**
      * @returns {number} number of shadowmaps rasterized in the most recent draw pass
      */

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneShadowmapContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js"],"names":[],"mappings":"AAyGA;;GAEG;AACH;IAoNI;;;;;;;;OAQG;IACH,sBAPW,eAAe,aACf,eAAe,SAGf,kBAAkB,EA+D5B;IAxRD,2BAAwG;IAExG;;;OAGG;IACH,SAFU,iBAAiB,CAEnB;IAQR;;;;;;;;OAQG;IACH,qBAFU,WAAW,CAED;IAsCpB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;;;;;;OAUG;IACH,+BAFU,OAAO,CAEqB;IA2EtC;;OAEG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,oCAEC;IAED;;;;;OAKG;IACH,oCAEC;IAkGD;;;;;OAKG;IACH,iCAMC;IAgHD;;;;OAIG;IACH,eAHW,KAAK,GACH,SAAS,GAAC,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,6BAPW,MAAM,SAEN,eAAe,eACf,MAAM,mBACN,UAAU,MAAM,CAAC,QAgE3B;IAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,kBAFW,sBAAsB,QAsFhC;IAsbD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBALa,OAAO,CAwOnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAiBC;;CACJ;qCA38CY,OAAO,2CAA2C,EAAE,sBAAsB;8BAC1E,OAAO,0BAA0B,EAAE,eAAe;qBAClD,OAAO,wBAAwB,EAAE,MAAM;iCACvC,OAAO,mCAAmC,EAAE,kBAAkB;oBAC9D,OAAO,4BAA4B,EAAE,KAAK;8BAC1C,OAAO,gCAAgC,EAAE,eAAe;wBACxD,OAAO,gBAAgB,EAAE,SAAS;oCA7DX,+DAA+D;kCAkBjE,oCAAoC;4BAG1C,2BAA2B;kBAtBrC,wCAAwC"}
+{"version":3,"file":"GPUSceneShadowmapContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js"],"names":[],"mappings":"AAsFA;;GAEG;AACH;IAgPI;;;;;;;;OAQG;IACH,sBAPW,eAAe,aACf,eAAe,SAGf,kBAAkB,EA+D5B;IApTD,2BAAwG;IAExG;;;OAGG;IACH,SAFU,iBAAiB,CAEnB;IAQR;;;;;;;;OAQG;IACH,qBAFU,WAAW,CAED;IAsCpB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;;;;;;OAUG;IACH,+BAFU,OAAO,CAEqB;IA2BtC;;;;OAIG;IACH,6BAIC;IAhBD;;OAEG;IACH,4BAEC;IA8ED;;OAEG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,oCAEC;IAED;;;;;OAKG;IACH,oCAEC;IAkGD;;;;;OAKG;IACH,iCAMC;IAgHD;;;;OAIG;IACH,eAHW,KAAK,GACH,SAAS,GAAC,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,6BAPW,MAAM,SAEN,eAAe,eACf,MAAM,mBACN,UAAU,MAAM,CAAC,QAgE3B;IAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,kBAFW,sBAAsB,QAsFhC;IAsbD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBALa,OAAO,CAwOnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAiBC;;CACJ;qCAn9CY,OAAO,2CAA2C,EAAE,sBAAsB;8BAC1E,OAAO,0BAA0B,EAAE,eAAe;qBAClD,OAAO,wBAAwB,EAAE,MAAM;iCACvC,OAAO,mCAAmC,EAAE,kBAAkB;oBAC9D,OAAO,4BAA4B,EAAE,KAAK;8BAC1C,OAAO,gCAAgC,EAAE,eAAe;wBACxD,OAAO,gBAAgB,EAAE,SAAS;oCA9DX,+DAA+D;kCAkBjE,oCAAoC;4BAG1C,2BAA2B;kBAtBrC,wCAAwC"}

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js

@@ -30,6 +30,7 @@ import {
     shader_csm_caster_range_accumulate,
     shader_csm_caster_range_publish,
 } from "./csm/shader/shader_csm_caster_range.js";
+import { DEFAULT_SHADOWMAP_UPDATE_BUDGET } from "./DEFAULT_SHADOWMAP_UPDATE_BUDGET.js";
 import { DirectionalLightShadowmap } from "./DirectionalLightShadowmap.js";
 import { POINT_SHADOW_CUBE_COLS, POINT_SHADOW_CUBE_ROWS } from "./POINT_SHADOW_CUBE_LAYOUT.js";
 import {
@@ -83,26 +84,6 @@ const DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION = [
  */
 const DEFAULT_SHADOWMAP_LOCAL_RESOLUTION = 128;
 
-/**
- * Per-frame shadow refresh budget, measured in **views** (one cube face counts as one view,
- * one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
- * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
- * keeps the cost of the refresh step roughly proportional to how much work we're asking the
- * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
- * equivalent work to 6 spot lights.
- *
- * Directional lights are always refreshed unconditionally (they drive the whole scene) and
- * their view cost is charged against the budget, so they effectively reduce the pool available
- * for local lights that frame.
- *
- * Unused budget is carried over between frames when demand exceeds supply — see
- * {@link GPUSceneShadowmapContext.#budget_carry_over}. This lets a light that's too expensive
- * to fit in a single frame (e.g. a point needing 6 views when only 2 are free) eventually get
- * its turn without permanently starving other lights.
- * @type {number}
- */
-const SHADOWMAP_UPDATE_BUDGET = 8;
-
 /**
  * Shadows for a single scene
  */
@@ -200,6 +181,34 @@ export class GPUSceneShadowmapContext {
      */
     #current_frame_index = -1;
 
+    /**
+     * Per-frame refresh budget in views, spent by {@link select_for_draw} on top of
+     * {@link #budget_carry_over}. Defaults to {@link DEFAULT_SHADOWMAP_UPDATE_BUDGET}, which is
+     * also where the view accounting is written down; the renderer pushes its own
+     * {@link Renderer.shadow_update_budget} here before each frame's light update, alongside
+     * {@link enabled}.
+     * @type {number}
+     */
+    #update_budget = DEFAULT_SHADOWMAP_UPDATE_BUDGET;
+
+    /**
+     * @returns {number} views this scene may spend refreshing shadowmaps each frame
+     */
+    get update_budget() {
+        return this.#update_budget;
+    }
+
+    /**
+     * @param {number} v views per frame, at least one. A higher budget keeps more lights current
+     *        and rasterizes more per frame; a lower one refreshes fewer of them per frame and
+     *        leaves the rest sampling older depth until their turn comes around.
+     */
+    set update_budget(v) {
+        assert.isPositiveInteger(v, 'update_budget');
+
+        this.#update_budget = v;
+    }
+
     /**
      * View-budget surplus carried forward from prior frames. Accumulates whenever we had
      * non-directional candidates that couldn't fit in the per-frame budget (i.e. a point light
@@ -602,7 +611,7 @@ export class GPUSceneShadowmapContext {
         // Steps 4 and 5: score every map and greedy-fill the view budget in score order. See
         // ShadowmapDrawSelector for why this is a heap drain rather than a sort — the budget
         // consumes a handful of winners out of however many candidates the scene has.
-        const budget_total = SHADOWMAP_UPDATE_BUDGET + this.#budget_carry_over;
+        const budget_total = this.#update_budget + this.#budget_carry_over;
         const selector = this.#selector;
 
         selector.select(shadowmaps, frame_index, budget_total);

package/src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.d.ts

@@ -47,10 +47,16 @@ export class WebGPUMipmapGenerator {
      * @param {GPUTexture} texture - Texture to generate mipmaps for.
      * @param {GPUTextureDescriptor} texture_descriptor - GPUTextureDescriptor the texture was created with.
      * @param {TextureFilterType} [filter]
-     * @param {GPUCommandEncoder} [commandEncoder]
+     * @param {GPUCommandEncoder} [commandEncoder] when supplied, the commands are recorded rather
+     *   than submitted, so the scratch resources outlive this call and `release_after_submit` is
+     *   required
+     * @param {{destroy: function():void}[]} [release_after_submit] where the scratch buffer and
+     *   textures go when the encoder is the caller's; destroy them once it has submitted
      * @returns {GPUTexture} - The originally passed texture
      */
-    generateMipmap(texture: GPUTexture, texture_descriptor: GPUTextureDescriptor, filter?: TextureFilterType, commandEncoder?: GPUCommandEncoder): GPUTexture;
+    generateMipmap(texture: GPUTexture, texture_descriptor: GPUTextureDescriptor, filter?: TextureFilterType, commandEncoder?: GPUCommandEncoder, release_after_submit?: {
+        destroy: () => void;
+    }[]): GPUTexture;
     #private;
 }
 import { HashMap } from "../../../../core/collection/map/HashMap.js";

package/src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebGPUMipmapGenerator.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.js"],"names":[],"mappings":"AAkMA;;;GAGG;AACH;IAqDI;;;OAGG;IACH,+BAWC;IAnED;;OAEG;IACH,kBAAM;IAEN;;;;OAIG;IACH,oBAFU,QAAQ,eAAe,oBAAoB,CAE3B;IAE1B;;OAEG;IACH,oBAAQ;IAgCR,gBAGC;IA6DD;;;;;OAKG;IACH,yEAFW,iBAAiB,QAY3B;IAED;;;OAGG;IACH,wBAFW,MAAM,QAyBhB;IAED;;OAEG;IACH,cAEC;IAmGG,qBAiBE;IAEF,oBAGE;IAGN;;;;;;;;OAQG;IACH,uFAJW,iBAAiB,kDA0X3B;;CACJ;wBAl2BuB,4CAA4C;AA2CpE;IAEI;;OAEG;IACH,yBAAO;IAEP;;OAEG;IACH;;;;QA1BA;;WAEG;;QAEH;;WAEG;;QAEH;;WAEG;;;;MAgBI;IAEP;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAMlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAOjB;CAEJ;kCAjEiC,yBAAyB"}
+{"version":3,"file":"WebGPUMipmapGenerator.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.js"],"names":[],"mappings":"AAkMA;;;GAGG;AACH;IAqDI;;;OAGG;IACH,+BAWC;IAnED;;OAEG;IACH,kBAAM;IAEN;;;;OAIG;IACH,oBAFU,QAAQ,eAAe,oBAAoB,CAE3B;IAE1B;;OAEG;IACH,oBAAQ;IAgCR,gBAGC;IA6DD;;;;;OAKG;IACH,yEAFW,iBAAiB,QAY3B;IAED;;;OAGG;IACH,wBAFW,MAAM,QAyBhB;IAED;;OAEG;IACH,cAEC;IAmGG,qBAiBE;IAEF,oBAGE;IAGN;;;;;;;;;;;;OAYG;IACH,uFARW,iBAAiB,6DAIjB;QAAC,OAAO,QAAa,IAAI,CAAA;KAAC,EAAE,cAyZtC;;CACJ;wBAr4BuB,4CAA4C;AA2CpE;IAEI;;OAEG;IACH,yBAAO;IAEP;;OAEG;IACH;;;;QA1BA;;WAEG;;QAEH;;WAEG;;QAEH;;WAEG;;;;MAgBI;IAEP;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAMlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAOjB;CAEJ;kCAjEiC,yBAAyB"}

package/src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.js

@@ -490,17 +490,35 @@ export class WebGPUMipmapGenerator {
      * @param {GPUTexture} texture - Texture to generate mipmaps for.
      * @param {GPUTextureDescriptor} texture_descriptor - GPUTextureDescriptor the texture was created with.
      * @param {TextureFilterType} [filter]
-     * @param {GPUCommandEncoder} [commandEncoder]
+     * @param {GPUCommandEncoder} [commandEncoder] when supplied, the commands are recorded rather
+     *   than submitted, so the scratch resources outlive this call and `release_after_submit` is
+     *   required
+     * @param {{destroy: function():void}[]} [release_after_submit] where the scratch buffer and
+     *   textures go when the encoder is the caller's; destroy them once it has submitted
      * @returns {GPUTexture} - The originally passed texture
      */
     generateMipmap(
         texture,
         texture_descriptor,
         filter = TextureFilterType.Linear,
-        commandEncoder
+        commandEncoder,
+        release_after_submit
     ) {
         assert.defined(texture, 'texture');
         assert.defined(texture_descriptor, 'texture descriptor');
+
+        /**
+         * An ordinary throw, not an assert: a caller that supplies its own encoder has to say where
+         * the scratch resources go, because we cannot destroy them — its commands reference them and
+         * it has not submitted yet. Getting this wrong loses the caller's whole command buffer with
+         * no error of any kind, so it is not a check that may be stripped.
+         */
+        if (commandEncoder !== undefined && !Array.isArray(release_after_submit)) {
+            throw new Error(
+                "generateMipmap with a caller-supplied commandEncoder needs a `release_after_submit` array: "
+                + "the scratch resources outlive this call and must be destroyed once the caller has submitted"
+            );
+        }
         assert.enum(filter, TextureFilterType, 'filter');
 
         const mip_level_count = texture.mipLevelCount;
@@ -848,22 +866,39 @@ export class WebGPUMipmapGenerator {
             }
         }
 
+        /**
+         * Nothing here has run yet when the encoder is the caller's: the commands are recorded, and
+         * the caller submits later. `finish()`/`submit()` validate that every resource a command
+         * buffer touches is still alive, so destroying these inline had the whole command buffer
+         * rejected — not just the mips, but every pass the caller recorded in the same context, and
+         * silently, because WebGPU validation errors do not throw. The branch that was written to be
+         * careful, and the only one, was the one that got it wrong.
+         *
+         * So: when we made the encoder we submit and release; when we did not, the temporaries go to
+         * the caller's release list, to be destroyed once it has submitted.
+         *
+         * @param {{destroy: function():void}} resource
+         */
+        const release = created_command_encoder
+            ? resource => resource.destroy()
+            : resource => release_after_submit.push(resource);
+
         if (created_command_encoder) {
             device.queue.submit([commandEncoder.finish()]);
         } else {
-            parameters_buffer.destroy();
+            release(parameters_buffer);
         }
 
         if (texture !== decoded_texture) {
-            decoded_texture.destroy();
+            release(decoded_texture);
         }
 
         if (texture !== mip_texture) {
-            mip_texture.destroy();
+            release(mip_texture);
         }
 
         if (need_separate_forward_target) {
-            forward_texture.destroy();
+            release(forward_texture);
         }
 
         return texture;