@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/gpu_primitive/slot_stack/chunk_slot_stack.js

@@ -0,0 +1,58 @@
+import { UINT32_MAX } from "../../../../core/binary/UINT32_MAX.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * What {@link chunk_slot_stack}'s pop hands back when the stack is empty: the engine's one "no index"
+ * word, which no capacity reaches.
+ *
+ * @type {number}
+ */
+export const SLOT_STACK_NONE = UINT32_MAX;
+
+/**
+ * A stack of free slot indices on the device: a count, and the array the slots sit in below it. A
+ * pool hands its slots out by popping and takes them back by pushing; the order inside is
+ * arbitrary, and what matters is that every free slot appears once (`shader_slot_stack_fill` makes a
+ * fresh one).
+ *
+ * ```wgsl
+ * fn slot_stack_pop(count: ptr<storage, atomic<u32>, read_write>, slots: ptr<storage, array<u32>, read_write>, capacity: u32) -> u32
+ * fn slot_stack_push(count: ptr<storage, atomic<u32>, read_write>, slots: ptr<storage, array<u32>, read_write>, slot: u32)
+ * ```
+ *
+ * **The pop's guard catches wrapped counts, not just zero.** When many threads race an empty stack,
+ * the first over-pop wraps the count to `0xFFFFFFFF` before its undo lands, and a concurrent thread
+ * then reads a huge old value. Testing only `== 0` would let it index `slots[old - 1]` with garbage and
+ * hand out a slot that is not free. The count never legitimately exceeds `capacity`, so `> capacity`
+ * names every wrapped state; each thread that subtracted adds back exactly once, so the count
+ * converges to 0.
+ *
+ * **Pushes and pops go in separate dispatches.** A pop can read a slot a concurrent push has counted
+ * but not yet written.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_slot_stack = CodeChunk.from(
+    //language=WGSL
+    `
+const SLOT_STACK_NONE = ${SLOT_STACK_NONE}u;
+
+fn slot_stack_pop(count: ptr<storage, atomic<u32>, read_write>, slots: ptr<storage, array<u32>, read_write>, capacity: u32) -> u32 {
+    let old = atomicSub(count, 1u);
+
+    if (old == 0u || old > capacity) {
+        // empty, or wrapped by a race on an empty stack: undo the over-pop
+        atomicAdd(count, 1u);
+
+        return SLOT_STACK_NONE;
+    }
+
+    return (*slots)[old - 1u];
+}
+
+fn slot_stack_push(count: ptr<storage, atomic<u32>, read_write>, slots: ptr<storage, array<u32>, read_write>, slot: u32) {
+    let top = atomicAdd(count, 1u);
+
+    (*slots)[top] = slot;
+}
+`);

package/src/shade/renderer/gpu_primitive/slot_stack/shader_slot_stack_fill.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A slot stack ({@link chunk_slot_stack}) as a fresh pool leaves it: every slot free,
+ * `slots[i] = i`, bottom to top. The stack's count is the caller's to set to `capacity` beside it.
+ *
+ * The order within the stack is arbitrary and identity is simply the cheapest arrangement to write.
+ * What matters is that every slot appears exactly once: a repeat hands two owners one slot, and a gap
+ * strands a slot for the lifetime of the pool.
+ *
+ * ## Why this is a pass and not a host write
+ *
+ * Zero is not a valid stack — `slots[i] = 0` for every `i` is the same slot half a million times
+ * over — so the buffer WebGPU hands back has to be written before the first pop. Writing it from
+ * the host means a typed array the size of the stack (2 MiB for the particles' default capacity), a
+ * loop over every element of it, and a staged upload, all on the frame the pool is made. Here it is
+ * one store per slot with no host memory involved at all, and it leaves the stack `STORAGE` only:
+ * nothing else ever writes it from the host, so it needs no `COPY_DST` and stays off the driver's
+ * upload-friendly — and slower — path.
+ *
+ * ## Bounded launch, strided loop
+ *
+ * The capacity belongs to whoever makes the pool, and `capacity / workgroup_size` can pass
+ * `maxComputeWorkgroupsPerDimension` — a validation error for a direct dispatch, and worse than that
+ * for the indirect ones elsewhere in the engine, which simply do not run. So the caller clamps the
+ * launch and every lane strides through the stack by the whole grid: the fill covers any capacity,
+ * and a grid that happens to cover it in one pass costs one comparison to find out.
+ */
+/** Lanes per workgroup. One store each, so this is sized for occupancy and nothing else. */
+export const SLOT_STACK_FILL_WORKGROUP_SIZE: 256;
+export const shader_slot_stack_fill: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_slot_stack_fill.d.ts.map

package/src/shade/renderer/gpu_primitive/slot_stack/shader_slot_stack_fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_slot_stack_fill.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/slot_stack/shader_slot_stack_fill.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,4FAA4F;AAC5F,iDAAkD;AAQlD,mDAmBG;8BA3D2B,+BAA+B"}

package/src/shade/renderer/gpu_primitive/slot_stack/shader_slot_stack_fill.js

@@ -0,0 +1,62 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+
+/**
+ * A slot stack ({@link chunk_slot_stack}) as a fresh pool leaves it: every slot free,
+ * `slots[i] = i`, bottom to top. The stack's count is the caller's to set to `capacity` beside it.
+ *
+ * The order within the stack is arbitrary and identity is simply the cheapest arrangement to write.
+ * What matters is that every slot appears exactly once: a repeat hands two owners one slot, and a gap
+ * strands a slot for the lifetime of the pool.
+ *
+ * ## Why this is a pass and not a host write
+ *
+ * Zero is not a valid stack — `slots[i] = 0` for every `i` is the same slot half a million times
+ * over — so the buffer WebGPU hands back has to be written before the first pop. Writing it from
+ * the host means a typed array the size of the stack (2 MiB for the particles' default capacity), a
+ * loop over every element of it, and a staged upload, all on the frame the pool is made. Here it is
+ * one store per slot with no host memory involved at all, and it leaves the stack `STORAGE` only:
+ * nothing else ever writes it from the host, so it needs no `COPY_DST` and stays off the driver's
+ * upload-friendly — and slower — path.
+ *
+ * ## Bounded launch, strided loop
+ *
+ * The capacity belongs to whoever makes the pool, and `capacity / workgroup_size` can pass
+ * `maxComputeWorkgroupsPerDimension` — a validation error for a direct dispatch, and worse than that
+ * for the indirect ones elsewhere in the engine, which simply do not run. So the caller clamps the
+ * launch and every lane strides through the stack by the whole grid: the fill covers any capacity,
+ * and a grid that happens to cover it in one pass costs one comparison to find out.
+ */
+
+/** Lanes per workgroup. One store each, so this is sized for occupancy and nothing else. */
+export const SLOT_STACK_FILL_WORKGROUP_SIZE = 256;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+resources.setImmediate("capacity", u32);
+resources.createGroup().addStorageBuffer("slots", WebGPUArray.u32, true);
+
+export const shader_slot_stack_fill = ComputeShader.from({
+    label: "Slot Stack Fill",
+    resources,
+    body: CodeChunk.from(
+        /* language=wgsl */
+        `
+@compute @workgroup_size(${SLOT_STACK_FILL_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(global_invocation_id) global_id : vec3<u32>,
+    @builtin(num_workgroups) group_count : vec3<u32>,
+) {
+    // The grid may be smaller than the stack; every lane keeps taking the next slot a whole grid on.
+    let stride = group_count.x * ${SLOT_STACK_FILL_WORKGROUP_SIZE}u;
+
+    for (var slot = global_id.x; slot < capacity; slot += stride) {
+        slots[slot] = slot;
+    }
+}
+`),
+});

package/src/shade/renderer/gpu_primitive/slot_stack/shader_slot_stack_push_range.d.ts

@@ -0,0 +1,21 @@
+/** Lanes per workgroup. One push each, so this is sized for occupancy and nothing else. */
+export const SLOT_STACK_PUSH_RANGE_WORKGROUP_SIZE: 256;
+/**
+ * @type {WebGPUStruct}
+ */
+export const SLOT_STACK_PUSH_RANGE_SETTINGS: WebGPUStruct;
+/**
+ * Pushes the slots `first` to `first + count - 1` onto a live slot stack ({@link chunk_slot_stack}):
+ * the slots a pool gains when it grows. Unlike {@link shader_slot_stack_fill}, the stack may hold
+ * slots already, a count the host does not know, so each slot goes on with an atomic push; the order
+ * they land in is arbitrary.
+ *
+ * The launch is the caller's to clamp, as for the fill: every lane strides through the range by the
+ * whole grid.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_slot_stack_push_range: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_slot_stack_push_range.d.ts.map

package/src/shade/renderer/gpu_primitive/slot_stack/shader_slot_stack_push_range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_slot_stack_push_range.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/slot_stack/shader_slot_stack_push_range.js"],"names":[],"mappings":"AAQA,2FAA2F;AAC3F,uDAAwD;AAExD;;GAEG;AACH,6CAFU,YAAY,CASW;AAUjC;;;;;;;;;;GAUG;AACH,2CAFU,aAAa,CAoBpB;6BAvD0B,mCAAmC;8BAJlC,+BAA+B"}

package/src/shade/renderer/gpu_primitive/slot_stack/shader_slot_stack_push_range.js

@@ -0,0 +1,61 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { chunk_slot_stack } from "./chunk_slot_stack.js";
+
+/** Lanes per workgroup. One push each, so this is sized for occupancy and nothing else. */
+export const SLOT_STACK_PUSH_RANGE_WORKGROUP_SIZE = 256;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const SLOT_STACK_PUSH_RANGE_SETTINGS = WebGPUStruct.from({
+    /** the first slot pushed */
+    first: u32,
+    /** slots pushed, `first` on */
+    count: u32,
+    /** which word of `counts` is the stack's count */
+    counter: u32,
+}, "SlotStackPushRangeSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", SLOT_STACK_PUSH_RANGE_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("counts", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("slots", WebGPUArray.u32, true);
+
+/**
+ * Pushes the slots `first` to `first + count - 1` onto a live slot stack ({@link chunk_slot_stack}):
+ * the slots a pool gains when it grows. Unlike {@link shader_slot_stack_fill}, the stack may hold
+ * slots already, a count the host does not know, so each slot goes on with an atomic push; the order
+ * they land in is arbitrary.
+ *
+ * The launch is the caller's to clamp, as for the fill: every lane strides through the range by the
+ * whole grid.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_slot_stack_push_range = ComputeShader.from({
+    label: "Slot Stack Push Range",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${SLOT_STACK_PUSH_RANGE_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(global_invocation_id) global_id: vec3<u32>,
+    @builtin(num_workgroups) group_count: vec3<u32>,
+) {
+    let stride = group_count.x * ${SLOT_STACK_PUSH_RANGE_WORKGROUP_SIZE}u;
+
+    for (var i = global_id.x; i < settings.count; i += stride) {
+        slot_stack_push(&counts[settings.counter], &slots, settings.first + i);
+    }
+}
+`, [chunk_slot_stack]),
+});

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":"AAsDA;IAEI;;;;;OAKG;IACH,iCAFW,eAAe,QAOzB;IA6KD;;;;;;OAMG;IACH,sBALW,eAAe,aACf,eAAe,EA2CzB;IAnND;;;OAGG;IACH,6DAEC;IAeD;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,qFAEC;IAWD;;OAEG;IACH,+CAEC;IA6DD;;;OAGG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,yCAEC;IAGD,4BAMC;IAmMD;;;OAGG;IACH,YAFW,eAAe,QAoCzB;IAED;;;;;;;;;OASG;IACH,gBAFW,OAAO,+BAA+B,EAAE,YAAY,QAkC9D;IAED;;;;;;OAMG;IACH,uBAHW,sBAAsB,mCA6BhC;IAwED,gBAUC;;CACJ;8BAzlBY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,sBAAsB,EAAE,eAAe;4BA/B/B,gCAAgC;yCACnB,2CAA2C;kCAClD,iCAAiC;uCAH5B,wCAAwC"}
+{"version":3,"file":"GPULightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/GPULightCollection.js"],"names":[],"mappings":"AAsDA;IAEI;;;;;OAKG;IACH,iCAFW,eAAe,QAOzB;IA6KD;;;;;;OAMG;IACH,sBALW,eAAe,aACf,eAAe,EA2CzB;IAnND;;;OAGG;IACH,6DAEC;IAeD;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,qFAEC;IAWD;;OAEG;IACH,+CAEC;IA6DD;;;OAGG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,yCAEC;IAGD,4BAMC;IAoMD;;;OAGG;IACH,YAFW,eAAe,QAoCzB;IAED;;;;;;;;;OASG;IACH,gBAFW,OAAO,+BAA+B,EAAE,YAAY,QAkC9D;IAED;;;;;;OAMG;IACH,uBAHW,sBAAsB,mCA6BhC;IAwED,gBAUC;;CACJ;8BA1lBY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,sBAAsB,EAAE,eAAe;4BA/B/B,gCAAgC;yCACnB,2CAA2C;kCAClD,iCAAiC;uCAH5B,wCAAwC"}

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

@@ -368,11 +368,17 @@ export class GPULightCollection {
             );
         }
 
-        gpu_ctx.resize(source_image.width, source_image.height);
+        /*
+         Assign descriptor.size directly rather than calling gpu_ctx.resize(): resize() immediately
+         re-allocates when the context is already in TEXTURE_STATE_ALLOCATED, which would call
+         createTexture with the new size and the previous map's mipLevelCount (failing WebGPU
+         validation whenever the new map is smaller) before allocate() below replaces it again.
+        */
+        gpu_ctx.descriptor.size = [source_image.width, source_image.height, 1];
         /*
          The environment map is equirectangular and this context is built 2D a few lines up — the
-         descriptor keeps the default dimension and `resize` above only takes two axes. Asked of the
-         descriptor rather than assumed, so the count follows if that ever stops being true.
+         descriptor keeps the default dimension and `size` above only sets two spatial axes. Asked of
+         the descriptor rather than assumed, so the count follows if that ever stops being true.
         */
         const gpu_size = gpu_ctx.descriptor.size;
 
@@ -380,18 +386,13 @@ export class GPULightCollection {
             gpu_size.width, gpu_size.height, gpu_size.depthOrArrayLayers, gpu_ctx.descriptor.dimension
         );
 
-        gpu_ctx.allocate();
-
-        if (
-            isImageBitmap(source_image.source)
-            && (gpu_ctx.descriptor.usage & GPUTextureUsage.RENDER_ATTACHMENT) === 0
-        ) {
+        if (isImageBitmap(source_image.source)) {
             // need RENDER_ATTACHMENT to use GPUQueue.copyExternalImageToTexture API
-            // update descriptor and re-allocate texture
             gpu_ctx.descriptor.usage |= GPUTextureUsage.RENDER_ATTACHMENT;
-            gpu_ctx.allocate(false);
         }
 
+        gpu_ctx.allocate();
+
         texture_write_to_gpu(source_image, gpu_ctx.gpu_texture, this.#device.queue, source_image.level_count);
 
         // convolve

package/src/shade/renderer/light/cluster/cull/shader_cull_lights_frustum.d.ts

@@ -1,5 +1,4 @@
 export const shader_cull_point_lights_frustum: ComputeShader;
 export const shader_cull_spot_lights_frustum: ComputeShader;
-export const shader_cull_lights_frustum: ComputeShader;
 import { ComputeShader } from "../../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_cull_lights_frustum.d.ts.map

package/src/shade/renderer/light/cluster/cull/shader_cull_lights_frustum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_cull_lights_frustum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/cluster/cull/shader_cull_lights_frustum.js"],"names":[],"mappings":"AAkGA,6DAQG;AAEH,4DAQG;AAGH,uDAA2E;8BAzG7C,kCAAkC"}
+{"version":3,"file":"shader_cull_lights_frustum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/cluster/cull/shader_cull_lights_frustum.js"],"names":[],"mappings":"AAkGA,6DAQG;AAEH,4DAQG;8BAtG2B,kCAAkC"}

package/src/shade/renderer/light/cluster/cull/shader_cull_lights_frustum.js

@@ -1,120 +1,117 @@
-import { atomic_u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
-import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
-import {
-    chunk_point_light_intersects_frustum
-} from "../../../shader/chunk/light/cull/chunk_point_light_intersects_frustum.js";
-import {
-    chunk_spot_light_intersects_frustum
-} from "../../../shader/chunk/light/cull/chunk_spot_light_intersects_frustum.js";
-import { chunk_point_lights_iterate } from "../../../shader/chunk/light/io/chunk_point_lights_iterate.js";
-import { chunk_spot_lights_iterate } from "../../../shader/chunk/light/io/chunk_spot_lights_iterate.js";
-import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
-import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
-import { ComputeShader } from "../../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
-import { CLUSTER_LIGHT_TYPE, chunk_cluster_light_tuple } from "../CLUSTER_LIGHT_TYPE.js";
-
-/**
- * Workgroup size used by both point/spot cull entry points. Interpolated into the WGSL below, which
- * is where the size is stated; the host reads it back off the shader and dispatches in threads.
- * @type {number}
- */
-const SHADER_CULL_LIGHTS_FRUSTUM_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
-
-const OUTPUT_STRUCT = WebGPUStruct.from({
-    offset: atomic_u32,
-    data: WebGPUArray.u32
-});
-
-// One thread per (page_index, in_page_slot) pair. Threads whose page
-// is unallocated or whose occupancy bit is clear early-return — no
-// workgroup memory, scales with the table's allocated capacity rather
-// than a hardcoded cap.
-function build_cull_shader({ label, prefix_upper, prefix_lower, intersects_chunk, intersects_fn, cluster_type, iterate_chunk }) {
-    const resources = new ShaderResourceSetDescriptor();
-    resources.createGroup()
-        .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-
-    resources.createGroup()
-        .addStorageBuffer("light_data", WebGPUArray.u32)
-
-    resources.createGroup()
-        .addStorageBuffer("output", OUTPUT_STRUCT, true)
-
-    const body = CodeChunk.from(
-        //language=WGSL
-        `
-@compute @workgroup_size(${SHADER_CULL_LIGHTS_FRUSTUM_WORKGROUP_SIZE}, 1, 1)
-fn main(
-    @builtin(global_invocation_id) global_id : vec3<u32>
-) {
-    let id = global_id.x;
-    let page_index = id / ${prefix_upper}_ELEMENTS_PER_PAGE;
-    let in_page_slot = id % ${prefix_upper}_ELEMENTS_PER_PAGE;
-
-    if (page_index >= ${prefix_upper}_PAGE_LIMIT) {
-        return;
-    }
-
-    let page_address = ${prefix_lower}_page_address(&light_data, page_index);
-    if (page_address == ~0u) {
-        return;
-    }
-
-    let word_index = in_page_slot >> 5u;
-    let bit = in_page_slot & 31u;
-    let bitmap_word = ${prefix_lower}_page_bitmap_word(&light_data, page_address, word_index);
-    if ((bitmap_word & (1u << bit)) == 0u) {
-        return;
-    }
-
-    let light_index = ${prefix_lower}_slot_to_index(page_index, in_page_slot);
-    if (!${intersects_fn}(&light_data, light_index, camera.frustum)) {
-        return;
-    }
-
-    let packed_id = cluster_light_tuple_pack(light_index, ${cluster_type}u);
-    let destination = atomicAdd(&output.offset, 1u);
-
-    if (destination < arrayLength(&output.data)) {
-        output.data[destination] = packed_id;
-    }
-}
-        `, [
-            chunk_cluster_light_tuple,
-            iterate_chunk,
-            intersects_chunk,
-        ]
-    );
-
-    return ComputeShader.from({
-        label,
-        body,
-        resources,
-    });
-}
-
-export const shader_cull_point_lights_frustum = build_cull_shader({
-    label: "cull point lights frustum",
-    prefix_upper: "POINT_LIGHTS",
-    prefix_lower: "point_lights",
-    intersects_chunk: chunk_point_light_intersects_frustum,
-    intersects_fn: "point_light_intersects_frustum",
-    cluster_type: CLUSTER_LIGHT_TYPE.Point,
-    iterate_chunk: chunk_point_lights_iterate,
-});
-
-export const shader_cull_spot_lights_frustum = build_cull_shader({
-    label: "cull spot lights frustum",
-    prefix_upper: "SPOT_LIGHTS",
-    prefix_lower: "spot_lights",
-    intersects_chunk: chunk_spot_light_intersects_frustum,
-    intersects_fn: "spot_light_intersects_frustum",
-    cluster_type: CLUSTER_LIGHT_TYPE.Spot,
-    iterate_chunk: chunk_spot_lights_iterate,
-});
-
-// Compatibility re-export — graph_cull_lights still imports this name.
-export const shader_cull_lights_frustum = shader_cull_point_lights_frustum;
+import { atomic_u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import {
+    chunk_point_light_intersects_frustum
+} from "../../../shader/chunk/light/cull/chunk_point_light_intersects_frustum.js";
+import {
+    chunk_spot_light_intersects_frustum
+} from "../../../shader/chunk/light/cull/chunk_spot_light_intersects_frustum.js";
+import { chunk_point_lights_iterate } from "../../../shader/chunk/light/io/chunk_point_lights_iterate.js";
+import { chunk_spot_lights_iterate } from "../../../shader/chunk/light/io/chunk_spot_lights_iterate.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { CLUSTER_LIGHT_TYPE, chunk_cluster_light_tuple } from "../CLUSTER_LIGHT_TYPE.js";
+
+/**
+ * Workgroup size used by both point/spot cull entry points. Interpolated into the WGSL below, which
+ * is where the size is stated; the host reads it back off the shader and dispatches in threads.
+ * @type {number}
+ */
+const SHADER_CULL_LIGHTS_FRUSTUM_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+
+const OUTPUT_STRUCT = WebGPUStruct.from({
+    offset: atomic_u32,
+    data: WebGPUArray.u32
+});
+
+// One thread per (page_index, in_page_slot) pair. Threads whose page
+// is unallocated or whose occupancy bit is clear early-return — no
+// workgroup memory, scales with the table's allocated capacity rather
+// than a hardcoded cap.
+function build_cull_shader({ label, prefix_upper, prefix_lower, intersects_chunk, intersects_fn, cluster_type, iterate_chunk }) {
+    const resources = new ShaderResourceSetDescriptor();
+    resources.createGroup()
+        .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+
+    resources.createGroup()
+        .addStorageBuffer("light_data", WebGPUArray.u32)
+
+    resources.createGroup()
+        .addStorageBuffer("output", OUTPUT_STRUCT, true)
+
+    const body = CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${SHADER_CULL_LIGHTS_FRUSTUM_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(global_invocation_id) global_id : vec3<u32>
+) {
+    let id = global_id.x;
+    let page_index = id / ${prefix_upper}_ELEMENTS_PER_PAGE;
+    let in_page_slot = id % ${prefix_upper}_ELEMENTS_PER_PAGE;
+
+    if (page_index >= ${prefix_upper}_PAGE_LIMIT) {
+        return;
+    }
+
+    let page_address = ${prefix_lower}_page_address(&light_data, page_index);
+    if (page_address == ~0u) {
+        return;
+    }
+
+    let word_index = in_page_slot >> 5u;
+    let bit = in_page_slot & 31u;
+    let bitmap_word = ${prefix_lower}_page_bitmap_word(&light_data, page_address, word_index);
+    if ((bitmap_word & (1u << bit)) == 0u) {
+        return;
+    }
+
+    let light_index = ${prefix_lower}_slot_to_index(page_index, in_page_slot);
+    if (!${intersects_fn}(&light_data, light_index, camera.frustum)) {
+        return;
+    }
+
+    let packed_id = cluster_light_tuple_pack(light_index, ${cluster_type}u);
+    let destination = atomicAdd(&output.offset, 1u);
+
+    if (destination < arrayLength(&output.data)) {
+        output.data[destination] = packed_id;
+    }
+}
+        `, [
+            chunk_cluster_light_tuple,
+            iterate_chunk,
+            intersects_chunk,
+        ]
+    );
+
+    return ComputeShader.from({
+        label,
+        body,
+        resources,
+    });
+}
+
+export const shader_cull_point_lights_frustum = build_cull_shader({
+    label: "cull point lights frustum",
+    prefix_upper: "POINT_LIGHTS",
+    prefix_lower: "point_lights",
+    intersects_chunk: chunk_point_light_intersects_frustum,
+    intersects_fn: "point_light_intersects_frustum",
+    cluster_type: CLUSTER_LIGHT_TYPE.Point,
+    iterate_chunk: chunk_point_lights_iterate,
+});
+
+export const shader_cull_spot_lights_frustum = build_cull_shader({
+    label: "cull spot lights frustum",
+    prefix_upper: "SPOT_LIGHTS",
+    prefix_lower: "spot_lights",
+    intersects_chunk: chunk_spot_light_intersects_frustum,
+    intersects_fn: "spot_light_intersects_frustum",
+    cluster_type: CLUSTER_LIGHT_TYPE.Spot,
+    iterate_chunk: chunk_spot_lights_iterate,
+});

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

@@ -19,8 +19,7 @@
  * different pole *and* a different signature: `(target, u, v)` against
  * `(out, out_offset, in_uv, in_offset)`. An importer who autocompleted the name got one of two functions
  * that disagree about which axis is up, and the `core` one silently reads `u` out of
- * `arguments[2][arguments[3]]` if handed this call shape. The old name is kept as a deprecated alias
- * because it is published surface.
+ * `arguments[2][arguments[3]]` if handed this call shape.
  *
  * @see chunk_uv_octahedral_unit_decode
  * @param {number[]|Float32Array} target receives the normalized direction (x, y, z)

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

@@ -1 +1 @@
-{"version":3,"file":"octahedral_z_pole_uv_to_direction.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/octahedral_z_pole_uv_to_direction.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,0DAJW,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,KACN,MAAM,QAiBhB"}
+{"version":3,"file":"octahedral_z_pole_uv_to_direction.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/octahedral_z_pole_uv_to_direction.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,0DAJW,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,KACN,MAAM,QAiBhB"}