@woosh/meep-engine 3.29.0 → 3.31.0

package/src/shade/renderer/global_illumination/probe/octahedral/sample/chunk_lpv_atlas_patch_texel_coord.js

@@ -0,0 +1,38 @@
+import { chunk_index_to_grid2d } from "../../../../shader/chunk/grid/chunk_index_to_grid2d.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+
+/**
+ * Where a probe's texel sits in the atlas.
+ *
+ * The atlas stores every probe with a one-texel border on each side, so the pitch between patches
+ * is `probe_resolution + 2` and the patch's own texel `(0, 0)` is one in from its origin. That is
+ * {@link GPUProbeAtlas#padded_probe_resolution}, and it is the one thing a caller must not have to
+ * remember: the reader used to take the PITCH as its argument, so one caller passed
+ * `probe_resolution + 2` and pre-added the border to the texel while the other passed the bare
+ * resolution and nothing — computing the wrong patches-per-row AND the wrong patch origin, which is
+ * a different probe entirely. The padding is applied here, once, and the argument is the probe
+ * resolution both callers already have.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_lpv_atlas_patch_texel_coord = CodeChunk.from(
+    //language=WGSL
+    `
+fn lpv_atlas_patch_texel_coord(
+    patch_index: u32,
+    patch_texel: vec2<u32>,
+    atlas_resolution: vec2<u32>,
+    probe_resolution: u32
+) -> vec2<u32>{
+    // one texel of border on each side, so bilinear sampling at the patch edge stays inside it
+    let patch_pitch = probe_resolution + 2u;
+
+    let atlas_resolution_in_patches = atlas_resolution / patch_pitch;
+
+    let patch_grid = index_to_grid2d(patch_index, atlas_resolution_in_patches.x);
+
+    return patch_texel + vec2<u32>(1u, 1u) + patch_grid * patch_pitch;
+}
+`, [
+        chunk_index_to_grid2d,
+    ]);

package/src/shade/renderer/global_illumination/probe/octahedral/sample/chunk_lpv_atlas_read_patch_texel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_lpv_atlas_read_patch_texel.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe/octahedral/sample/chunk_lpv_atlas_read_patch_texel.js"],"names":[],"mappings":"AAIA,yDAuBO;0BAzBmB,0CAA0C"}
+{"version":3,"file":"chunk_lpv_atlas_read_patch_texel.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe/octahedral/sample/chunk_lpv_atlas_read_patch_texel.js"],"names":[],"mappings":"AAIA,yDA6BO;0BAhCmB,0CAA0C"}

package/src/shade/renderer/global_illumination/probe/octahedral/sample/chunk_lpv_atlas_read_patch_texel.js

@@ -1,28 +1,34 @@
 import { chunk_rgbe9995_decode } from "../../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_decode.js";
-import { chunk_index_to_grid2d } from "../../../../shader/chunk/grid/chunk_index_to_grid2d.js";
 import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { chunk_lpv_atlas_patch_texel_coord } from "./chunk_lpv_atlas_patch_texel_coord.js";
 
 export const chunk_lpv_atlas_read_patch_texel = CodeChunk.from(
     //language=WGSL
     `
+/**
+ * probe_resolution is the UNPADDED one, and patch_texel is inside the unpadded patch — the
+ * one-texel border the atlas stores around every probe is applied by
+ * lpv_atlas_patch_texel_coord, so no caller has to remember it. This used to take the PITCH, and
+ * the two callers disagreed about what to pass.
+ */
 fn lpv_atlas_read_patch_texel(
     patch_index: u32,
     patch_texel: vec2<u32>,
     atlas: texture_2d<u32>,
-    patch_resolution: u32
+    probe_resolution: u32
 ) -> vec3<f32>{
-    let atlas_resolution_in_patches = textureDimensions(atlas) / patch_resolution;
+    let atlas_texel_coord = lpv_atlas_patch_texel_coord(
+        patch_index,
+        patch_texel,
+        textureDimensions(atlas),
+        probe_resolution
+    );
     
-    // convert probe to offset
-    let patch_grid = index_to_grid2d(patch_index, atlas_resolution_in_patches.x); 
-    
-    let atlas_texel_coord = patch_texel + patch_grid * patch_resolution;
-    
-    let raw_texel = textureLoad(atlas, vec2<u32>(atlas_texel_coord), 0).r;
+    let raw_texel = textureLoad(atlas, atlas_texel_coord, 0).r;
     
     return rgbe9995_decode( raw_texel );
 }
 `, [
-        chunk_index_to_grid2d,
+        chunk_lpv_atlas_patch_texel_coord,
         chunk_rgbe9995_decode,
     ]);

package/src/shade/renderer/gpu_primitive/indirect/IndirectComputeCommandBuildPass.d.ts

@@ -8,7 +8,7 @@
  * @param {number} buffer_command_offset where to start writing at, in bytes
  * @param {boolean} [fold] spread a count past one dimension's limit over `y` and `z` instead of
  *        clamping it away. Only for a shader that reads its index through
- *        {@link chunk_grid3d_to_index} — see {@link create_pipeline}.
+ *        {@link chunk_folded_workgroup_index} — see {@link create_pipeline}.
  */
 export function build_indirect_compute_dispatch_command(elements_per_workgroup: number, encoder: ShadeGPUCommandContext, buffer_input: GPUBuffer, buffer_input_offset: number, buffer_command: GPUBuffer, buffer_command_offset: number, fold?: boolean): void;
 /**

package/src/shade/renderer/gpu_primitive/indirect/IndirectComputeCommandBuildPass.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IndirectComputeCommandBuildPass.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/indirect/IndirectComputeCommandBuildPass.js"],"names":[],"mappings":"AAoLA;;;;;;;;;;;GAWG;AACH,gFAVW,MAAM,iFAGN,MAAM,oDAEN,MAAM,SACN,OAAO,QAuFjB;AAED;;;;;;;GAOG;AACH,gFALW,MAAM,mBACN,MAAM,SACN,OAAO,GACL,MAAM,CAkClB;AA9ID,2EAIE;yCA7KuC,mDAAmD"}
+{"version":3,"file":"IndirectComputeCommandBuildPass.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/indirect/IndirectComputeCommandBuildPass.js"],"names":[],"mappings":"AA+LA;;;;;;;;;;;GAWG;AACH,gFAVW,MAAM,iFAGN,MAAM,oDAEN,MAAM,SACN,OAAO,QAuFjB;AAED;;;;;;;GAOG;AACH,gFALW,MAAM,mBACN,MAAM,SACN,OAAO,GACL,MAAM,CAkClB;AA9ID,2EAIE;yCAxLuC,mDAAmD"}

package/src/shade/renderer/gpu_primitive/indirect/IndirectComputeCommandBuildPass.js

@@ -6,6 +6,9 @@ import { BufferBindingLayout } from "../../../descriptor/binding/BufferBindingLa
 import { ComputePipelineDescriptor } from "../../../descriptor/pipeline/compute/ComputePipelineDescriptor.js";
 import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
 import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "./STRUCT_DISPATCH_COMPUTE_COMMAND.js";
+import {
+    WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION
+} from "./WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
 
 /**
  * How a workgroup count that does not fit one dimension is spread over three.
@@ -23,7 +26,9 @@ import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "./STRUCT_DISPATCH_COMPUTE_COMMA
  * moves a counter, because the collection's own `count` is written by a different pass.
  *
  * So the count is folded instead: `x` fills to the limit, then `y`, then `z`. Nothing is dropped
- * and the reachable size becomes 65,535³ groups, which is not a limit anyone will meet.
+ * and the reachable size becomes 65,535³ groups, which is not a limit anyone will meet. The limit is
+ * {@link WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION} rather than this device's figure —
+ * see below for why it has to be.
  *
  * **A folded command's shader has to read its index accordingly.** `global_invocation_id.x` only
  * carries the x dimension, so a shader that keeps using it would run its first 8,388,480 elements
@@ -32,18 +37,23 @@ import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "./STRUCT_DISPATCH_COMPUTE_COMMA
  * ```wgsl
  * fn main(
  *     @builtin(workgroup_id) workgroup_id : vec3<u32>,
- *     @builtin(num_workgroups) group_count : vec3<u32>,
  *     @builtin(local_invocation_index) local_index : u32,
  * ){
- *     let index = grid3d_to_index(workgroup_id, group_count.xy) * GROUP_SIZEu + local_index;
+ *     let index = folded_workgroup_index(workgroup_id) * GROUP_SIZEu + local_index;
  *
  *     if(index >= count){ return; }
  * ```
  *
- * {@link chunk_grid3d_to_index} is the same flattening the light and decal clusters use, and a
- * folded grid is exactly a 3D grid whose extents happen to be a dispatch's. When the count fits,
- * `y` and `z` are 1 and the expression is `global_invocation_id.x` term for term, so a pass under
- * the ceiling pays nothing for this.
+ * {@link chunk_folded_workgroup_index} flattens the grid with the fold's width as a constant stride,
+ * which is only right because every folded command is folded against that same constant — this
+ * builder and {@link shader_prefix_sum_to_command} both. The alternative is to ask the dispatch for
+ * its extents through `@builtin(num_workgroups)`, and on D3D12 that costs ~15 µs per indirect
+ * dispatch whatever the grid, empty ones included. When the count fits, `y` and `z` are 1 and the
+ * index is `global_invocation_id.x` term for term, so a pass under the ceiling pays nothing for this.
+ *
+ * A shader that flattens with {@link chunk_grid3d_to_index} over `num_workgroups` instead reads the
+ * same index from these commands; it only pays for the builtin. `NOTES.md` beside this file has the
+ * measurements and the reason, which is how Dawn issues such a dispatch on D3D12.
  *
  * Folding is opt-in because it is only safe once the shader indexes this way, and most passes
  * driven by this builder cannot reach the ceiling to begin with — a scene is capped at 3,047,424
@@ -68,17 +78,18 @@ function create_pipeline(key) {
 
     //language=WGSL
     const folded_dispatch = `
-    const LIMIT = ${max_workgroup_count}u;
+    // the width chunk_folded_workgroup_index strides by, which is why it is not this device's figure
+    const LIMIT = ${WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION}u;
 
     // x to the limit, what is left of it in rows of x, what is left of those in slices of x*y
     let rows = divide_round_up(desired_groups, LIMIT);
     let slices = divide_round_up(rows, LIMIT);
 
-    command = ${STRUCT_DISPATCH_COMPUTE_COMMAND.wgsl_ref}(
-        min( desired_groups, LIMIT ),
-        min( max( rows, 1u ), LIMIT ),
-        max( slices, 1u )
-    );`;
+    // field by field, as shader_prefix_sum_to_command writes it: the WGSL emulator drops a whole-struct
+    // store into a storage variable, and this is the text folded_dispatch_width.spec.js runs
+    command.workgroupCountX = min( desired_groups, LIMIT );
+    command.workgroupCountY = min( max( rows, 1u ), LIMIT );
+    command.workgroupCountZ = max( slices, 1u );`;
 
 //language=WGSL
     const shader_code = `
@@ -188,7 +199,7 @@ export const INDIRECT_COMPUTE_COMMAND_DESCRIPTOR = BufferResourceDescriptor.from
  * @param {number} buffer_command_offset where to start writing at, in bytes
  * @param {boolean} [fold] spread a count past one dimension's limit over `y` and `z` instead of
  *        clamping it away. Only for a shader that reads its index through
- *        {@link chunk_grid3d_to_index} — see {@link create_pipeline}.
+ *        {@link chunk_folded_workgroup_index} — see {@link create_pipeline}.
  */
 export function build_indirect_compute_dispatch_command(
     elements_per_workgroup,

package/src/shade/renderer/gpu_primitive/indirect/NOTES.md

@@ -0,0 +1,94 @@
+# `@builtin(num_workgroups)` in an indirect dispatch
+
+**Do not read `@builtin(num_workgroups)` in a shader dispatched with `dispatchWorkgroupsIndirect`**
+— which in this engine means `ComputeShader#dispatchIndirect` or `graph_compute_indirect_pass`. On
+D3D12 every such dispatch costs about 15 µs more than one that does not read it, and it costs that
+over an empty grid as much as over a full one. A *direct* dispatch pays nothing for the builtin.
+
+## What it costs
+
+One dispatch of a 128-wide shader in its own timed compute pass, the command written by a compute
+pass just before it, as the engine's builders do. RTX 4090, Chrome 154 on D3D12, median µs:
+
+| | 0 groups | 1 group | 4096 groups |
+|---|---:|---:|---:|
+| indirect, reads `num_workgroups` | 18.4 | 18.4 | 23.6 |
+| indirect, flattens with a constant stride | 3.1 | 4.1 | 7.2 |
+| indirect, reads the extents from the command buffer | 3.1 | 4.1 | 7.2 |
+| direct, either way | 0 | 1.0 | 4.1–5.1 |
+
+In the engine, the standard raster path ran seven such dispatches per view — the mesh-to-meshlet
+expansion twice, both meshlet filters, the three meshlet bucket passes — so every view, shadow views
+included, carried a fixed ~105 µs before it did any work. Removing the builtin from those seven
+(2026-09-25) took them, summed per view on `playground/mesh_row_ceiling?rows=200000`, from 157.7 /
+156.7 / 123.9 / 169.0 µs to 44.0 / 62.5 / 20.5 / 69.6 µs (three sun cascades and the main view; the
+third cascade is empty, so that column is the pure floor).
+
+## Why
+
+Read out of Dawn's source and confirmed by probe. Two separate things happen to an indirect
+dispatch, and only one of them is the builtin.
+
+1. **Every indirect dispatch is copied, whatever the shader reads.** With validation on, which is
+   how Chrome runs, `ComputePassEncoder::TransformIndirectDispatchBuffer` (Dawn's
+   `src/dawn/native/ComputePassEncoder.cpp`) inserts a one-thread compute pass that copies the three
+   counts into a scratch buffer and zeroes them if any is over `maxComputeWorkgroupsPerDimension`.
+   The real dispatch then reads the scratch buffer. This is why an over-limit indirect dispatch runs
+   nothing at all rather than failing (see `playground/mesh_row_ceiling/README.md`). It costs about
+   2 µs: `--enable-dawn-features=skip_validation` takes a plain indirect dispatch from 3.1 µs to
+   1.0 µs.
+
+2. **The builtin changes how the dispatch is issued.** HLSL has no `num_workgroups`, so Dawn's D3D12
+   backend passes it as a root constant. A direct dispatch sets that constant from the CPU, which is
+   free. For an indirect dispatch the counts only exist on the GPU, so the validation pass writes
+   them twice (`duplicateNumWorkgroups`), and the dispatch goes through `ExecuteIndirect` with a
+   command signature that sets the root constants ahead of the dispatch
+   (`ComputePipeline::GetDispatchIndirectCommandSignature` →
+   `GetDispatchIndirectCommandSignatureWithNumWorkgroups`, in `src/dawn/native/d3d12/`). The
+   pipeline gets that signature whenever its shader uses the builtin (`UsesNumWorkgroups`).
+
+**The ~15 µs is the command signature, not the copy.** With validation off the plain dispatch
+drops to 1.0 µs, but the `num_workgroups` dispatch stays at 18.4, where the copy survives only to
+duplicate the counts. Three more words written cannot cost 15 µs.
+
+Dawn duplicates the counts only on D3D12: the base `ShouldDuplicateNumWorkgroupsForDispatchIndirect`
+returns false, so Vulkan and Metal should not pay this. Not measured there.
+
+## What to do instead
+
+- **A folded command** — from `build_indirect_compute_dispatch_command` with `fold`, or from
+  `shader_prefix_sum_to_command` — flattens with
+  `renderer/shader/chunk/grid/chunk_folded_workgroup_index.js`. Both builders fill x to
+  `WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION` before y grows, and y before z, so the
+  grid flattens with that constant as its stride. `folded_dispatch_width.spec.js` holds the two
+  builders to the same command.
+- **Any other shader that needs its extents** can read them from the command buffer, bound
+  read-only in the same dispatch that uses it as INDIRECT. WebGPU allows it, since both are
+  read-only usages in one usage scope, and it measured the same as a constant stride.
+- **A direct dispatch** may read `num_workgroups` freely.
+
+## Still paying, as of 2026-09-25
+
+These still read the builtin and are dispatched indirectly. They are correct, just 15 µs a dispatch
+dearer than they need to be:
+
+- `renderer/particles/shaders/shader_particle_emit.js`, `shader_particle_init_free_list.js`
+- `renderer/rasterize/bucket/shader_count_meshlets_by_material.js`, `shader_sort_meshlets_by_material.js`
+- `renderer/rasterize/native/avboit/shader_avboit_occupancy.js`
+- `renderer/rasterize/cull/hzb/shader_hzb_meshlet_filter_1way_full.js` (no live caller)
+
+The texture encoders also read it, but they dispatch directly, so they pay nothing.
+
+## Measuring a pass like this
+
+- **Time one dispatch per compute pass.** Rotate the order of the arms every round, and write each
+  command with a compute pass just before its dispatch, not with `writeBuffer`, so the buffer
+  transitions match the engine's.
+- **Separate the copy with `--enable-dawn-features=skip_validation`.** It removes Dawn's validation
+  copy from every dispatch that does not read `num_workgroups`.
+- **Check for other headless Chromes before trusting a run.** Other sessions benchmark on the same
+  GPU; start a run only after none has been up for a while, and discard any run one appears in.
+- **Compare heavy passes within a paired round.** At `mesh_row_ceiling?rows=2000000`, the main
+  view's 2-way filter and the mesh bucket sort each pick one of two modes per run, about 200 µs
+  apart, and hold it for the whole run. A pooled median across runs can read a mode flip as a
+  regression. Quote the p10, and attribute any regression with an arm that differs by one file.

package/src/shade/renderer/gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.d.ts

@@ -1,5 +1,6 @@
 /**
- * Workgroups per dimension that **every** WebGPU device allows.
+ * Workgroups per dimension that **every** WebGPU device allows, and so the width every folded
+ * dispatch command is folded to.
  *
  * `maxComputeWorkgroupsPerDimension` has this as its default, and a device may only report more,
  * never less — so a shader that writes an indirect dispatch command can fold against this literal
@@ -7,13 +8,15 @@
  * to reach it through a binding.
  *
  * Folding sooner than a particular device would have needed costs nothing: the extents are only
- * how the workgroups are arranged, and the shaders on the other side flatten them back with
- * {@link chunk_grid3d_to_index} whatever they are. It is the other direction that is
- * unrecoverable — a command over the device's limit does not run at all, and nothing reports it.
+ * how the workgroups are arranged. It is the other direction that is unrecoverable — a command over
+ * the device's limit does not run at all, and nothing reports it.
  *
- * {@link build_indirect_compute_dispatch_command} does not use this: it builds its pipeline per
- * device and inlines the real figure. This is for {@link shader_prefix_sum_to_command}, which is a
- * shared {@link ComputeShader} compiled once and cannot.
+ * Both builders of folded commands fold against this, {@link shader_prefix_sum_to_command} and
+ * {@link build_indirect_compute_dispatch_command} with `fold` — the second could inline the device's
+ * own figure and deliberately does not. The agreement is load-bearing: the passes they drive flatten
+ * the grid with {@link chunk_folded_workgroup_index}, which strides by this constant instead of
+ * reading `@builtin(num_workgroups)`, so a command whose x fell short of it while y was past 1
+ * would leave a gap in the index.
  *
  * @see https://www.w3.org/TR/webgpu/#limits
  * @type {number}

package/src/shade/renderer/gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qEAFU,MAAM,CAE4D"}
+{"version":3,"file":"WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qEAFU,MAAM,CAE4D"}

package/src/shade/renderer/gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js

@@ -1,5 +1,6 @@
 /**
- * Workgroups per dimension that **every** WebGPU device allows.
+ * Workgroups per dimension that **every** WebGPU device allows, and so the width every folded
+ * dispatch command is folded to.
  *
  * `maxComputeWorkgroupsPerDimension` has this as its default, and a device may only report more,
  * never less — so a shader that writes an indirect dispatch command can fold against this literal
@@ -7,13 +8,15 @@
  * to reach it through a binding.
  *
  * Folding sooner than a particular device would have needed costs nothing: the extents are only
- * how the workgroups are arranged, and the shaders on the other side flatten them back with
- * {@link chunk_grid3d_to_index} whatever they are. It is the other direction that is
- * unrecoverable — a command over the device's limit does not run at all, and nothing reports it.
+ * how the workgroups are arranged. It is the other direction that is unrecoverable — a command over
+ * the device's limit does not run at all, and nothing reports it.
  *
- * {@link build_indirect_compute_dispatch_command} does not use this: it builds its pipeline per
- * device and inlines the real figure. This is for {@link shader_prefix_sum_to_command}, which is a
- * shared {@link ComputeShader} compiled once and cannot.
+ * Both builders of folded commands fold against this, {@link shader_prefix_sum_to_command} and
+ * {@link build_indirect_compute_dispatch_command} with `fold` — the second could inline the device's
+ * own figure and deliberately does not. The agreement is load-bearing: the passes they drive flatten
+ * the grid with {@link chunk_folded_workgroup_index}, which strides by this constant instead of
+ * reading `@builtin(num_workgroups)`, so a command whose x fell short of it while y was past 1
+ * would leave a gap in the index.
  *
  * @see https://www.w3.org/TR/webgpu/#limits
  * @type {number}

package/src/shade/renderer/light/GPULightCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPULightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/GPULightCollection.js"],"names":[],"mappings":"AAyCA;IAgII;;;;;;OAMG;IACH,sBALW,eAAe,aACf,eAAe,EA8BzB;IA1JD;;;OAGG;IACH,6DAEC;IAeD;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,qFAEC;IAWD;;OAEG;IACH,+CAEC;IAyCD;;;OAGG;IACH,qCAEC;IAGD,+BAIC;IAwFD;;;OAGG;IACH,YAFW,eAAe,QA8BzB;IAED;;;;;;;;;OASG;IACH,gBAFW,OAAO,+BAA+B,EAAE,YAAY,QAkC9D;IAED;;;;;;OAMG;IACH,uBAHW,sBAAsB,mCAyBhC;IAwED,gBAQC;;CACJ;8BAvaY,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,sBAAsB,EAAE,eAAe;4BApB/B,gCAAgC;yCACnB,2CAA2C;kCAClD,iCAAiC;uCAH5B,wCAAwC"}
+{"version":3,"file":"GPULightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/GPULightCollection.js"],"names":[],"mappings":"AA0CA;IAgII;;;;;;OAMG;IACH,sBALW,eAAe,aACf,eAAe,EA8BzB;IA1JD;;;OAGG;IACH,6DAEC;IAeD;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,qFAEC;IAWD;;OAEG;IACH,+CAEC;IAyCD;;;OAGG;IACH,qCAEC;IAGD,+BAIC;IA4GD;;;OAGG;IACH,YAFW,eAAe,QA8BzB;IAED;;;;;;;;;OASG;IACH,gBAFW,OAAO,+BAA+B,EAAE,YAAY,QAkC9D;IAED;;;;;;OAMG;IACH,uBAHW,sBAAsB,mCAyBhC;IAwED,gBAQC;;CACJ;8BA3bY,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,sBAAsB,EAAE,eAAe;4BApB/B,gCAAgC;yCACnB,2CAA2C;kCAClD,iCAAiC;uCAH5B,wCAAwC"}

package/src/shade/renderer/light/GPULightCollection.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { isImageBitmap } from "../../../core/dom/isImageBitmap.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
 import { GPUSceneShadowmapContext } from "../shadow/map/GPUSceneShadowmapContext.js";
@@ -218,6 +219,26 @@ export class GPULightCollection {
 
         const gpu_ctx = this.#environment;
 
+        /*
+         No environment is a supported state, not a mistake: LightCollection's setter takes
+         undefined — its assert is conditional on the value being defined — and serialize_scene
+         writes the absence of one. Clearing a map that had been set used to walk straight into
+         source_env.image and take the frame down from inside the renderer's per-frame update.
+
+         Every consumer binds this texture unconditionally — the path tracer, the probe atlas, the
+         lightmap baker, the transparent passes all call obtainView() on it without asking whether
+         there is an environment — so it has to keep existing. A freshly allocated 1x1 at one mip
+         is zeroed, which is the same black IBL they read before an environment is ever assigned.
+        */
+        if (source_env === undefined) {
+            gpu_ctx.descriptor.mipLevelCount = 1;
+            gpu_ctx.descriptor.size = [1, 1, 1];
+
+            gpu_ctx.allocate();
+
+            return;
+        }
+
         const source_image = source_env.image;
         gpu_ctx.resize(source_image.width, source_image.height);
         /*
@@ -234,7 +255,7 @@ export class GPULightCollection {
         gpu_ctx.allocate();
 
         if (
-            source_image.source instanceof ImageBitmap
+            isImageBitmap(source_image.source)
             && (gpu_ctx.descriptor.usage & GPUTextureUsage.RENDER_ATTACHMENT) === 0
         ) {
             // need RENDER_ATTACHMENT to use GPUQueue.copyExternalImageToTexture API

package/src/shade/renderer/light/LIGHT_DATABASE_SPEC.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LIGHT_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/LIGHT_DATABASE_SPEC.js"],"names":[],"mappings":"AAUA,wDAiBG;sCAzBmC,0CAA0C"}
+{"version":3,"file":"LIGHT_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/LIGHT_DATABASE_SPEC.js"],"names":[],"mappings":"AAWA,wDAiBG;sCA1BmC,0CAA0C"}

package/src/shade/renderer/light/LIGHT_DATABASE_SPEC.js

@@ -1,6 +1,7 @@
 import { vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../shader/type/WebGPUArray.js";
 import { GPUDatabaseDefinition } from "../buffer/table/GPUDatabaseDefinition.js";
+import { SCENE_DATABASE_SPEC } from "../scene/SCENE_DATABASE_SPEC.js";
 import { DIRECTIONAL_LIGHT_STRUCT } from "../shader/chunk/light/DIRECTIONAL_LIGHT_STRUCT.js";
 import { POINT_LIGHT_STRUCT } from "../shader/chunk/light/POINT_LIGHT_STRUCT.js";
 import { SPOT_LIGHT_STRUCT } from "../shader/chunk/light/SPOT_LIGHT_STRUCT.js";
@@ -26,3 +27,28 @@ export const LIGHT_DATABASE_SPEC = GPUDatabaseDefinition.from({
     // map, claimed and released by the shadow context
     shadow_csm_caster_range: CSM_CASTER_RANGE_STRUCT,
 });
+
+for (const kind of ['point', 'spot', 'directional']) {
+    // The light's shadow slot. Slots are numbered densely per kind by the shadow context and
+    // rebuilt with the records, so a light does not own its slot; a light without a shadow names
+    // none.
+    LIGHT_DATABASE_SPEC.add_link({
+        table: `light_${kind}`,
+        field: 'shadow_id',
+        target_database: LIGHT_DATABASE_SPEC,
+        target_table: `shadow_${kind}`,
+        nullable: true,
+        owning: false,
+    });
+
+    // The transforms row of the light's entity, where the GPU reads its pose each frame. The light
+    // collection holds that row through the scene's rows; it is not this database's to free.
+    LIGHT_DATABASE_SPEC.add_link({
+        table: `light_${kind}`,
+        field: 'node',
+        target_database: SCENE_DATABASE_SPEC,
+        target_table: 'transforms',
+        nullable: false,
+        owning: false,
+    });
+}

package/src/shade/renderer/light/cluster/chunk_cluster_keep_smallest.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Keep the smallest values in a full slice: replace the largest with `candidate` when `candidate`
+ * is smaller, otherwise leave it alone.
+ *
+ * **What this buys is determinism.** A cluster that resolves more lights than its local storage
+ * holds has to drop some, and it used to drop whichever arrived last — the arrival order being the
+ * order of the culled list, which `shader_cull_lights_frustum`/`_hzb` build with an `atomicAdd`,
+ * i.e. GPU scheduling order, which is not stable across frames. So the set of lights a crowded
+ * cluster lost changed every frame, and the artefact flickered instead of sitting still. Keeping
+ * the smallest indices makes the kept set a function of the scene alone: still a loss, but the same
+ * loss every frame, which is the difference between an artefact you can see and reason about and
+ * one that reads as random noise.
+ *
+ * Linear in the slice, and only paid when a cluster is over its limit — which is already a
+ * pathological cluster at {@link LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT} lights of one type.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_cluster_keep_smallest: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_cluster_keep_smallest.d.ts.map

package/src/shade/renderer/light/cluster/chunk_cluster_keep_smallest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_cluster_keep_smallest.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/cluster/chunk_cluster_keep_smallest.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAFU,SAAS,CA2BhB;0BA9CuB,oCAAoC"}

package/src/shade/renderer/light/cluster/chunk_cluster_keep_smallest.js

@@ -0,0 +1,47 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT } from "./LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT.js";
+
+/**
+ * Keep the smallest values in a full slice: replace the largest with `candidate` when `candidate`
+ * is smaller, otherwise leave it alone.
+ *
+ * **What this buys is determinism.** A cluster that resolves more lights than its local storage
+ * holds has to drop some, and it used to drop whichever arrived last — the arrival order being the
+ * order of the culled list, which `shader_cull_lights_frustum`/`_hzb` build with an `atomicAdd`,
+ * i.e. GPU scheduling order, which is not stable across frames. So the set of lights a crowded
+ * cluster lost changed every frame, and the artefact flickered instead of sitting still. Keeping
+ * the smallest indices makes the kept set a function of the scene alone: still a loss, but the same
+ * loss every frame, which is the difference between an artefact you can see and reason about and
+ * one that reads as random noise.
+ *
+ * Linear in the slice, and only paid when a cluster is over its limit — which is already a
+ * pathological cluster at {@link LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT} lights of one type.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_cluster_keep_smallest = CodeChunk.from(
+    //language=WGSL
+    `
+fn cluster_keep_smallest(
+    values: ptr<function, array<u32, ${2 * LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}>>,
+    base: u32,
+    count: u32,
+    candidate: u32
+) {
+    var worst = 0u;
+    var worst_value = (*values)[base];
+
+    for (var i = 1u; i < count; i++) {
+        let value = (*values)[base + i];
+
+        if (value > worst_value) {
+            worst_value = value;
+            worst = i;
+        }
+    }
+
+    if (candidate < worst_value) {
+        (*values)[base + worst] = candidate;
+    }
+}
+`);

package/src/shade/renderer/light/cluster/shader_cluster_assign_lights.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_cluster_assign_lights.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/cluster/shader_cluster_assign_lights.js"],"names":[],"mappings":"AA+BA,mEAMG;AAmBH,sDAAoF;AA2IpF,yDAIG;6BArM0B,mCAAmC;4BADpC,kCAAkC;8BAoBhC,+BAA+B"}
+{"version":3,"file":"shader_cluster_assign_lights.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/cluster/shader_cluster_assign_lights.js"],"names":[],"mappings":"AAgCA,mEAMG;AAmBH,sDAAoF;AA8IpF,yDAIG;6BAzM0B,mCAAmC;4BADpC,kCAAkC;8BAoBhC,+BAA+B"}

package/src/shade/renderer/light/cluster/shader_cluster_assign_lights.js

@@ -22,6 +22,7 @@ import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { chunk_cluster_depth_from_z_slice } from "./chunk_cluster_depth_from_z_slice.js";
+import { chunk_cluster_keep_smallest } from "./chunk_cluster_keep_smallest.js";
 import { chunk_light_cluster_counts } from "./chunk_light_cluster_counts.js";
 import { chunk_light_cluster_resolution_xy_from_screen } from "./chunk_light_cluster_resolution_xy_from_screen.js";
 import { CLUSTER_LIGHT_TYPE, chunk_cluster_light_tuple } from "./CLUSTER_LIGHT_TYPE.js";
@@ -133,17 +134,19 @@ fn main(
         }
 
         if (light_type == ${CLUSTER_LIGHT_TYPE.Point}u) {
-            if (local_point_count >= ${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}) {
-                continue; // local point storage full
+            if (local_point_count < ${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}) {
+                local_lights[local_point_count] = light_index;
+                local_point_count += 1u;
+            } else {
+                cluster_keep_smallest(&local_lights, 0u, ${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}u, light_index);
             }
-            local_lights[local_point_count] = light_index;
-            local_point_count += 1u;
         } else {
-            if (local_spot_count >= ${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}) {
-                continue; // local spot storage full
+            if (local_spot_count < ${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}) {
+                local_lights[${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT} + local_spot_count] = light_index;
+                local_spot_count += 1u;
+            } else {
+                cluster_keep_smallest(&local_lights, ${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}u, ${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}u, light_index);
             }
-            local_lights[${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT} + local_spot_count] = light_index;
-            local_spot_count += 1u;
         }
     }
 
@@ -177,6 +180,7 @@ fn main(
     `, [
         LIGHT_CLUSTER_METADATA.declaration_chunk,
         chunk_grid3d_to_index,
+        chunk_cluster_keep_smallest,
         chunk_cluster_slice_frustum,
         chunk_plane_from_triangle,
         chunk_frustum_to_corners,

package/src/shade/renderer/light/environment/equirectangular_zenith_first_direction_to_uv.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Direction to equirectangular UV, in the convention the environment bake uses:
+ *
+ *   u = (atan2(x, z) + pi) / 2pi
+ *   v = acos(y) / pi
+ *
+ * so **v = 0 is the zenith** (+Y) and longitude is measured from +Z, anticlockwise about +Y.
+ *
+ * ## There are two equirectangular conventions in this tree, deliberately
+ *
+ * `core/geom/3d/equirectangular` defines the projection the other way round — `u = atan2(z, x)/2pi + 0.5`,
+ * `v = asin(y)/pi + 0.5`, which puts the zenith at **v = 1** and starts longitude a quarter turn away
+ * with the opposite handedness. That one matches three.js' `equirectUv`, deliberately, so that a texture
+ * authored for `EquirectangularReflectionMapping` reads correctly through it.
+ *
+ * The two are self-consistent and **not interchangeable**. Feeding an HDRI resampled through this
+ * convention to a probe written against the `core` one gives an environment flipped vertically and
+ * rotated ninety degrees in azimuth — which reads as a bad asset rather than a code bug. The comment at
+ * `resample_equirectangular_to_octahedral`'s decode records that a previous attempt to move the bake onto
+ * the other convention produced an east-west mirrored environment, so "just call the core one" is a change
+ * that has already gone wrong once.
+ *
+ * This exists as a named function rather than as arithmetic inside the resampler because the resampler's
+ * own spec was restating it — a second copy of the mapping, in the place least able to catch a drift in it.
+ *
+ * @param {number[]|Float32Array} out receives `(u, v)`
+ * @param {number} out_offset
+ * @param {number} x unit direction
+ * @param {number} y
+ * @param {number} z
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function equirectangular_zenith_first_direction_to_uv(out: number[] | Float32Array, out_offset: number, x: number, y: number, z: number): void;
+//# sourceMappingURL=equirectangular_zenith_first_direction_to_uv.d.ts.map

package/src/shade/renderer/light/environment/equirectangular_zenith_first_direction_to_uv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equirectangular_zenith_first_direction_to_uv.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/equirectangular_zenith_first_direction_to_uv.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,kEATW,MAAM,EAAE,GAAC,YAAY,cACrB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAWhB"}