@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -1,53 +1,38 @@
-import { atomic_u32, f32, vec2u, vec3f, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import {
-    chunk_compute_near_far_from_projection
-} from "../../shader/chunk/camera/chunk_compute_near_far_from_projection.js";
-import { chunk_inverse_lerp } from "../../shader/chunk/math/chunk_inverse_lerp.js";
-import { chunk_cluster_slice_frustum } from "../../shader/chunk/geometry/frustum/chunk_cluster_slice_frustum.js";
-import { chunk_frustum_from_corners } from "../../shader/chunk/geometry/frustum/chunk_frustum_from_corners.js";
-import { chunk_frustum_slice } from "../../shader/chunk/geometry/frustum/chunk_frustum_slice.js";
-import { chunk_frustum_to_corners } from "../../shader/chunk/geometry/frustum/chunk_frustum_to_corners.js";
-import { chunk_plane_from_triangle } from "../../shader/chunk/geometry/plane/chunk_plane_from_triangle.js";
 import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.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 { 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 { atomic_u32, vec4u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { chunk_cluster_cell } from "./chunk_cluster_cell.js";
+import { chunk_cluster_light_proxy } from "./chunk_cluster_light_proxy.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";
-import { LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT } from "./LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT.js";
+import { CLUSTER_LIGHT_LIST } from "./CLUSTER_LIGHT_LIST.js";
+import { CLUSTER_LIGHT_PROXY } from "./CLUSTER_LIGHT_PROXY.js";
+import { chunk_cluster_light_tuple } from "./CLUSTER_LIGHT_TYPE.js";
+import { LIGHT_CLUSTER_ASSIGNMENT_SETTINGS } from "./LIGHT_CLUSTER_ASSIGNMENT_SETTINGS.js";
+import { LIGHT_CLUSTER_COARSE_BLOCK } from "./LIGHT_CLUSTER_COARSE_BLOCK.js";
 import { LIGHT_CLUSTER_METADATA } from "./LIGHT_CLUSTER_METADATA.js";
-import { LIGHT_CLUSTER_RESOLUTION_Z, LIGHT_CLUSTER_TILE_RESOLUTION } from "./LIGHT_CLUSTER_RESOLUTION.js";
-
-export const LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS = WebGPUStruct.from({
-    cluster_params: vec3f,
-    screen_resolution: vec2u,
-    distance_min: f32,
-    distance_max: f32,
-    frustum: WebGPUArray.from(vec4f, 6)
-});
+import { LIGHT_CLUSTER_RESOLUTION_Z } from "./LIGHT_CLUSTER_RESOLUTION.js";
+
+const B = LIGHT_CLUSTER_COARSE_BLOCK;
 
 const resources = new ShaderResourceSetDescriptor();
 
 resources.createGroup()
     .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addStorageBuffer("input", WebGPUArray.u32)
-    .addUniform("settings", LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS)
+    .addUniform("settings", LIGHT_CLUSTER_ASSIGNMENT_SETTINGS)
+    .addStorageBuffer("lights", CLUSTER_LIGHT_LIST)
 ;
 
 resources.createGroup()
-    .addStorageBuffer("light_data", WebGPUArray.u32) // raw light database buffer
+    .addStorageBuffer("proxies", WebGPUArray.from(CLUSTER_LIGHT_PROXY))
+    .addStorageBuffer("boxes", WebGPUArray.from(vec4u))
+    .addStorageBuffer("coarse", WebGPUArray.u32)
 ;
 
 const CLUSTER_DATA_STRUCT = WebGPUStruct.from({
@@ -55,148 +40,254 @@ const CLUSTER_DATA_STRUCT = WebGPUStruct.from({
     data: WebGPUArray.u32
 });
 
+/**
+ * Each cell's metadata, see {@link LIGHT_CLUSTER_METADATA}
+ * @type {WebGPUArray}
+ */
 export const LIGHT_CLUSTER_LOOKUP_STRUCT = WebGPUArray.from(LIGHT_CLUSTER_METADATA);
+
 resources.createGroup({ label: "output" })
     .addStorageBuffer("cluster_lookup", LIGHT_CLUSTER_LOOKUP_STRUCT, true)
     .addStorageBuffer("cluster_data", CLUSTER_DATA_STRUCT, true)
-
-/**
- * Note the low count, this is because we use a lot of registers,
- * and most of the workgroups are likely to not get enough registers during allocation and end up idle (unallocated)
- * @type {number[]}
- */
-const LIGHT_CLUSTER_WORKGROUP_SIZE = [4, 4, 4];
+;
 
 const body = CodeChunk.from(
-//language=WGSL
+    //language=WGSL
     `
-@compute @workgroup_size(${LIGHT_CLUSTER_WORKGROUP_SIZE.join(', ')})
-fn main(
-    @builtin(global_invocation_id) voxel_position : vec3<u32>
-) {
-    // figure out limit values
-    let limit_xy = light_cluster_resolution_xy_from_screen(settings.screen_resolution);
-
-    if (any(voxel_position >= vec3(limit_xy, ${LIGHT_CLUSTER_RESOLUTION_Z}))) {
-        // out of bounds
-        return;
+// one chunk's survivors of the coarse mask, in list order up to the lane order inside a subgroup
+var<workgroup> survivors: array<u32, 64>;
+// per subgroup, its survivors in this chunk
+var<workgroup> subgroup_survivors: array<u32, 64>;
+var<workgroup> workgroup_light_count: u32;
+var<workgroup> workgroup_mask: vec2<u32>;
+
+fn cluster_light_hits_cell(i: u32, is_spot: bool, C: ClusterCell) -> bool {
+    if (!is_spot) {
+        return cluster_cell_intersects_sphere(proxies[i].bound, C);
     }
+    let proxy = proxies[i];
+    if (proxy.unbounded == 1u) {
+        return true;
+    }
+    return cluster_cell_intersects_spot(
+        proxy.apex_height.xyz,
+        proxy.direction_cos.xyz,
+        proxy.apex_height.w,
+        proxy.direction_cos.w,
+        proxy.source_radius,
+        proxy.bound,
+        C,
+    );
+}
 
-    let cluster_index = grid3d_to_index(voxel_position, limit_xy);
-
-    let z_planes = vec2(settings.distance_min, settings.distance_max);
-
-   let xy0 = vec2f((voxel_position.xy + 0u) * ${LIGHT_CLUSTER_TILE_RESOLUTION}) / vec2f(settings.screen_resolution);
-   let xy1 = vec2f((voxel_position.xy + 1u) * ${LIGHT_CLUSTER_TILE_RESOLUTION}) / vec2f(settings.screen_resolution);
-
-    var f0: vec3f = vec3f(xy0, 0.0);
-    var f1: vec3f = vec3f(xy1, 0.0);
+fn cluster_box_has(box: vec4<u32>, cell: vec3<u32>) -> bool {
+    return all(cell >= cluster_box_lo(box)) && all(cell <= cluster_box_hi(box));
+}
 
-    // remap z to non-linear space
-    let d0 = cluster_depth_from_z_slice(f32(voxel_position.z), settings.cluster_params, ${LIGHT_CLUSTER_RESOLUTION_Z});
-    let d1 = cluster_depth_from_z_slice(f32(voxel_position.z + 1), settings.cluster_params, ${LIGHT_CLUSTER_RESOLUTION_Z});
+/*
+ Compacts the chunk of 64 sorted lights starting at \`base\` that survive the block's coarse mask \`mask\`
+ into \`survivors\`, and returns how many there are. Subgroups are taken to be runs of
+ \`subgroup_size\` consecutive local invocation indices, which is what both GPUs this was measured on
+ do; the lanes inside a subgroup need not follow the index, which is what permutes the order inside a
+ subgroup's window.
+*/
+fn cluster_compact_chunk(
+    base: u32,
+    light_count: u32,
+    mask: vec2<u32>,
+    local_index: u32,
+    subgroup_lane: u32,
+    subgroup_size: u32,
+) -> u32 {
+    var keep = false;
+    if (base + local_index < light_count) {
+        keep = ((select(mask.x, mask.y, local_index >= 32u) >> (local_index & 31u)) & 1u) != 0u;
+    }
+    let k = select(0u, 1u, keep);
+    let before_in_subgroup = subgroupExclusiveAdd(k);
+    let in_subgroup = subgroupAdd(k);
+    let subgroup = local_index / subgroup_size;
+    if (subgroup_lane == 0u) {
+        subgroup_survivors[subgroup] = in_subgroup;
+    }
+    workgroupBarrier();
+
+    // Budget: 64 / subgroup_size subgroups. Nothing is past it.
+    var before = 0u;
+    var count = 0u;
+    for (var s = 0u; s < 64u / subgroup_size; s++) {
+        let n = subgroup_survivors[s];
+        before += select(0u, n, s < subgroup);
+        count += n;
+    }
+    if (keep) {
+        survivors[before + before_in_subgroup] = base + local_index;
+    }
+    workgroupBarrier();
 
-    f0.z = inverse_lerp(z_planes.x, z_planes.y, d0);
-    f1.z = inverse_lerp(z_planes.x, z_planes.y, d1);
+    return count;
+}
 
-    var input_planes = settings.frustum;
+@compute @workgroup_size(${B}, ${B}, ${B})
+fn main(
+    @builtin(global_invocation_id) cell: vec3<u32>,
+    @builtin(workgroup_id) block: vec3<u32>,
+    @builtin(local_invocation_index) local_index: u32,
+    @builtin(subgroup_invocation_id) subgroup_lane: u32,
+    @builtin(subgroup_size) subgroup_size: u32,
+) {
+    let grid = vec3<u32>(light_cluster_resolution_xy_from_screen(settings.screen_resolution), ${LIGHT_CLUSTER_RESOLUTION_Z}u);
+    let in_grid = all(cell < grid);
 
-    // build cluster frustum
-    var cluster_frustum = frustum_slice(input_planes, f0, f1);
+    if (local_index == 0u) {
+        workgroup_light_count = lights.count;
+    }
+    let light_count = workgroupUniformLoad(&workgroup_light_count);
+    let point_count = lights.point_count;
 
-    // iterate culled lights and test against cluster frustum, separating by type.
-    // The producer's atomic append counter is not clamped on overflow, so the stored count
-    // can exceed capacity — iterating the raw value would re-read the clamped last element.
-    let input_light_count = min(input[0], arrayLength(&input) - 1u);
+    let blocks = (grid + vec3<u32>(${B - 1}u)) / ${B}u;
+    let mask_words = (light_count + 31u) / 32u;
+    let mask_base = grid3d_to_index(block, blocks.xy) * mask_words;
 
-    var local_point_count = 0u;
-    var local_spot_count = 0u;
+    // (P00, P11, P02, P12): the projection the frame renders with, offset included
+    let P = camera.projection_matrix;
+    let projection = vec4<f32>(P[0][0], P[1][1], P[2][0], P[2][1]);
 
-    // Per-type local storage: point lights at [0..LIMIT), spot lights at [LIMIT..2*LIMIT).
-    // Keeping types segregated locally avoids a second pass to sort before write-out.
-    // TODO we can pack filtered indices into u16 to double available local storage
-    var local_lights = array<u32, ${2 * LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT}>();
+    var C: ClusterCell;
+    if (in_grid && light_count > 0u) {
+        // the bounding sphere is for spot lights only
+        C = cluster_cell(cell, ${LIGHT_CLUSTER_RESOLUTION_Z}u, settings.screen_resolution, projection, settings.cluster_parameters, point_count < light_count);
+    }
 
-    for (var i = 0u; i < input_light_count; i++) {
-        let tuple = input[1 + i];
-        let light_index = cluster_light_tuple_id(tuple);
-        let light_type = cluster_light_tuple_type(tuple);
+    // sweep 1: count the hits of each type, uncapped
+    var point_hits = 0u;
+    var spot_hits = 0u;
 
-        var intersects = false;
-        if (light_type == ${CLUSTER_LIGHT_TYPE.Point}u) {
-            intersects = point_light_intersects_frustum(&light_data, light_index, cluster_frustum);
-        } else if (light_type == ${CLUSTER_LIGHT_TYPE.Spot}u) {
-            intersects = spot_light_intersects_frustum(&light_data, light_index, cluster_frustum);
+    // Budget: one chunk per 64 sorted lights, at most 256 at the cull limit; a chunk with no light in
+    // this block costs two loads. Nothing is past it.
+    for (var base = 0u; base < light_count; base += 64u) {
+        if (local_index == 0u) {
+            let w = base / 32u;
+            workgroup_mask = vec2<u32>(coarse[mask_base + w], select(0u, coarse[mask_base + w + 1u], w + 1u < mask_words));
         }
-
-        if (!intersects) {
+        let mask = workgroupUniformLoad(&workgroup_mask);
+        if ((mask.x | mask.y) == 0u) {
             continue;
         }
 
-        if (light_type == ${CLUSTER_LIGHT_TYPE.Point}u) {
-            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);
-            }
-        } else {
-            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);
+        let n = cluster_compact_chunk(base, light_count, mask, local_index, subgroup_lane, subgroup_size);
+
+        if (in_grid) {
+            // Budget: the chunk's survivors, at most 64. Nothing is past it.
+            for (var j = 0u; j < n; j++) {
+                let i = survivors[j];
+                if (!cluster_box_has(boxes[i], cell)) {
+                    continue;
+                }
+                let is_spot = i >= point_count;
+                if (cluster_light_hits_cell(i, is_spot, C)) {
+                    if (is_spot) {
+                        spot_hits++;
+                    } else {
+                        point_hits++;
+                    }
+                }
             }
         }
+        workgroupBarrier();
     }
 
-    let local_total = local_point_count + local_spot_count;
-
-    let write_offset = atomicAdd(&cluster_data.offset, local_total);
-
-    // guard against overflow of cluster_data
-    let available = arrayLength(&cluster_data.data) - min(write_offset, arrayLength(&cluster_data.data));
-    let write_total = min(local_total, available);
-
-    // Splitting the available budget between types in proportion isn't worth the complexity:
-    // when overflow happens we just truncate spot lights first.
-    var write_point_count = min(local_point_count, write_total);
-    var write_spot_count = min(local_spot_count, write_total - write_point_count);
-
-    for (var i = 0u; i < write_point_count; i++) {
-        cluster_data.data[write_offset + i] = local_lights[i];
+    // one allocation per subgroup, for exactly its hits
+    let hits = point_hits + spot_hits;
+    let before = subgroupExclusiveAdd(hits);
+    let subgroup_hits = subgroupAdd(hits);
+    let elected = subgroupElect();
+    var subgroup_base = 0u;
+    if (elected && subgroup_hits > 0u) {
+        subgroup_base = atomicAdd(&cluster_data.offset, subgroup_hits);
     }
-    for (var i = 0u; i < write_spot_count; i++) {
-        cluster_data.data[write_offset + write_point_count + i] = local_lights[${LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT} + i];
-    }
-
-    var metadata: ${LIGHT_CLUSTER_METADATA.wgsl_ref};
+    let write_base = subgroupBroadcastFirst(subgroup_base) + before;
+
+    // Past the end of cluster_data the cell keeps what fits, points first. The frame is truncated;
+    // the next one is sized up from the bound.
+    let capacity = arrayLength(&cluster_data.data);
+    let available = capacity - min(write_base, capacity);
+    let point_capacity = min(point_hits, available);
+    let spot_capacity = min(spot_hits, available - point_capacity);
+
+    // sweep 2: write the same hits, points then spots
+    var points_written = 0u;
+    var spots_written = 0u;
+
+    // Budget: as sweep 1. Nothing is past it.
+    for (var base = 0u; base < light_count; base += 64u) {
+        if (local_index == 0u) {
+            let w = base / 32u;
+            workgroup_mask = vec2<u32>(coarse[mask_base + w], select(0u, coarse[mask_base + w + 1u], w + 1u < mask_words));
+        }
+        let mask = workgroupUniformLoad(&workgroup_mask);
+        if ((mask.x | mask.y) == 0u) {
+            continue;
+        }
 
-    metadata.counts = light_cluster_pack_counts(write_point_count, write_spot_count);
-    metadata.offset = write_offset + 1; // the +1 skips past the offset counter
+        let n = cluster_compact_chunk(base, light_count, mask, local_index, subgroup_lane, subgroup_size);
+
+        if (in_grid && (points_written < point_capacity || spots_written < spot_capacity)) {
+            // Budget: the chunk's survivors, at most 64. Nothing is past it.
+            for (var j = 0u; j < n; j++) {
+                let i = survivors[j];
+                if (!cluster_box_has(boxes[i], cell)) {
+                    continue;
+                }
+                let is_spot = i >= point_count;
+                if (is_spot) {
+                    if (spots_written < spot_capacity && cluster_light_hits_cell(i, true, C)) {
+                        cluster_data.data[write_base + point_capacity + spots_written] = cluster_light_tuple_id(lights.tuples[i]);
+                        spots_written++;
+                    }
+                } else {
+                    if (points_written < point_capacity && cluster_light_hits_cell(i, false, C)) {
+                        cluster_data.data[write_base + points_written] = cluster_light_tuple_id(lights.tuples[i]);
+                        points_written++;
+                    }
+                }
+            }
+        }
+        workgroupBarrier();
+    }
 
-    cluster_lookup[cluster_index] = metadata;
+    if (in_grid) {
+        var metadata: ${LIGHT_CLUSTER_METADATA.wgsl_ref};
+        metadata.counts = light_cluster_pack_counts(point_capacity, spot_capacity);
+        // +1 skips the allocation counter at the head of cluster_data
+        metadata.offset = write_base + 1u;
+        cluster_lookup[grid3d_to_index(cell, grid.xy)] = metadata;
+    }
 }
     `, [
         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,
-        chunk_frustum_from_corners,
-        chunk_point_light_intersects_frustum,
-        chunk_spot_light_intersects_frustum,
-        chunk_frustum_slice,
-        chunk_compute_near_far_from_projection,
-        chunk_cluster_depth_from_z_slice,
-        chunk_light_cluster_resolution_xy_from_screen,
-        chunk_inverse_lerp,
+        CLUSTER_LIGHT_PROXY.declaration_chunk,
+        chunk_cluster_cell,
+        chunk_cluster_light_proxy,
         chunk_cluster_light_tuple,
+        chunk_grid3d_to_index,
         chunk_light_cluster_counts,
+        chunk_light_cluster_resolution_xy_from_screen,
     ]
 );
 
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Pass 6 of the cluster light assignment, the fine pass: one workgroup per 4×4×4 block of cells, one
+ * thread per cell. In chunks of 64 sorted lights, it skips a chunk with no light in the block's coarse
+ * mask, gathers the chunk's survivors into workgroup memory, and runs each cell's box and precise tests
+ * against them ({@link chunk_cluster_cell}). It counts every hit, takes one allocation per subgroup for
+ * exactly that many, then writes them: no cell drops a light unless `cluster_data` is full.
+ *
+ * A cell's list is points then spots, each in sorted-list order chunk by chunk, with the lanes' order
+ * inside a subgroup's window: deterministic on a device, not ascending.
+ */
 export const shader_cluster_assign_lights = ComputeShader.from({
     label: "cluster assign lights",
     resources,

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

@@ -0,0 +1,19 @@
+/**
+ * Workgroups in one row of the coarse clear's dispatch. The clear is one thread per mask word, which
+ * can be more workgroups than one dimension takes, so the dispatch is folded into rows of this many.
+ * @type {number}
+ */
+export const LIGHT_CLUSTER_COARSE_CLEAR_ROW: number;
+/**
+ * Pass 4 of the cluster light assignment: zero every block's light bitmask, the words the frame's light
+ * count needs. One thread per word for the most lights the frame can have, in rows of
+ * {@link LIGHT_CLUSTER_COARSE_CLEAR_ROW} workgroups.
+ */
+export const shader_cluster_coarse_clear: ComputeShader;
+/**
+ * Pass 5 of the cluster light assignment: one workgroup per entry of the sorted light list sets the
+ * light's bit in every block its cell box touches.
+ */
+export const shader_cluster_coarse_scatter: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_cluster_coarse_mark.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_cluster_coarse_mark.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/cluster/shader_cluster_coarse_mark.js"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,6CAFU,MAAM,CAEmC;AAUnD;;;;GAIG;AACH,wDAqBG;AAWH;;;GAGG;AACH,0DA2CG;8BAjI2B,+BAA+B"}

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

@@ -0,0 +1,134 @@
+import { atomic_u32, vec4u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_cluster_light_proxy } from "./chunk_cluster_light_proxy.js";
+import { chunk_light_cluster_resolution_xy_from_screen } from "./chunk_light_cluster_resolution_xy_from_screen.js";
+import { CLUSTER_LIGHT_LIST } from "./CLUSTER_LIGHT_LIST.js";
+import { LIGHT_CLUSTER_ASSIGNMENT_SETTINGS } from "./LIGHT_CLUSTER_ASSIGNMENT_SETTINGS.js";
+import { LIGHT_CLUSTER_COARSE_BLOCK } from "./LIGHT_CLUSTER_COARSE_BLOCK.js";
+import { LIGHT_CLUSTER_RESOLUTION_Z } from "./LIGHT_CLUSTER_RESOLUTION.js";
+
+/**
+ * The coarse blocks of the grid, along each axis.
+ * @type {CodeChunk}
+ */
+const chunk_cluster_coarse_blocks = CodeChunk.from(
+    //language=WGSL
+    `
+fn cluster_coarse_blocks(screen_resolution: vec2<u32>) -> vec3<u32> {
+    let grid = vec3<u32>(light_cluster_resolution_xy_from_screen(screen_resolution), ${LIGHT_CLUSTER_RESOLUTION_Z}u);
+    return (grid + vec3<u32>(${LIGHT_CLUSTER_COARSE_BLOCK - 1}u)) / ${LIGHT_CLUSTER_COARSE_BLOCK}u;
+}
+
+// words of a block's light bitmask: one bit per entry of the sorted light list
+fn cluster_coarse_words(light_count: u32) -> u32 {
+    return (light_count + 31u) / 32u;
+}
+    `, [
+        chunk_light_cluster_resolution_xy_from_screen,
+    ]
+);
+
+/**
+ * Workgroups in one row of the coarse clear's dispatch. The clear is one thread per mask word, which
+ * can be more workgroups than one dimension takes, so the dispatch is folded into rows of this many.
+ * @type {number}
+ */
+export const LIGHT_CLUSTER_COARSE_CLEAR_ROW = 1024;
+
+const clear_resources = new ShaderResourceSetDescriptor();
+
+clear_resources.createGroup()
+    .addUniform("settings", LIGHT_CLUSTER_ASSIGNMENT_SETTINGS)
+    .addStorageBuffer("lights", CLUSTER_LIGHT_LIST)
+    .addStorageBuffer("coarse", WebGPUArray.u32, true)
+;
+
+/**
+ * Pass 4 of the cluster light assignment: zero every block's light bitmask, the words the frame's light
+ * count needs. One thread per word for the most lights the frame can have, in rows of
+ * {@link LIGHT_CLUSTER_COARSE_CLEAR_ROW} workgroups.
+ */
+export const shader_cluster_coarse_clear = ComputeShader.from({
+    label: "cluster coarse clear",
+    resources: clear_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(256)
+fn main(
+    @builtin(global_invocation_id) global_id: vec3<u32>
+) {
+    let blocks = cluster_coarse_blocks(settings.screen_resolution);
+    let word = global_id.x + global_id.y * ${LIGHT_CLUSTER_COARSE_CLEAR_ROW * 256}u;
+    if (word >= blocks.x * blocks.y * blocks.z * cluster_coarse_words(lights.count)) {
+        return;
+    }
+    coarse[word] = 0u;
+}
+        `, [
+            chunk_cluster_coarse_blocks,
+        ]
+    ),
+});
+
+const scatter_resources = new ShaderResourceSetDescriptor();
+
+scatter_resources.createGroup()
+    .addUniform("settings", LIGHT_CLUSTER_ASSIGNMENT_SETTINGS)
+    .addStorageBuffer("lights", CLUSTER_LIGHT_LIST)
+    .addStorageBuffer("boxes", WebGPUArray.from(vec4u))
+    .addStorageBuffer("coarse", WebGPUArray.from(atomic_u32), true)
+;
+
+/**
+ * Pass 5 of the cluster light assignment: one workgroup per entry of the sorted light list sets the
+ * light's bit in every block its cell box touches.
+ */
+export const shader_cluster_coarse_scatter = ComputeShader.from({
+    label: "cluster coarse scatter",
+    resources: scatter_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(64)
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) local_index: u32,
+) {
+    let i = workgroup_id.x;
+    if (i >= lights.count) {
+        return;
+    }
+    let box = boxes[i];
+    if (box.w == 0u) {
+        return;
+    }
+
+    let blocks = cluster_coarse_blocks(settings.screen_resolution);
+    let words = cluster_coarse_words(lights.count);
+
+    let lo = cluster_box_lo(box) / ${LIGHT_CLUSTER_COARSE_BLOCK}u;
+    let extent = cluster_box_hi(box) / ${LIGHT_CLUSTER_COARSE_BLOCK}u - lo + vec3<u32>(1u);
+    let n = extent.x * extent.y * extent.z;
+
+    let word = i >> 5u;
+    let bit = 1u << (i & 31u);
+
+    // Budget: the box's blocks over the workgroup's 64 threads; at most every block of the grid,
+    // 48 a thread at 3840x2160. Nothing is past it.
+    for (var k = local_index; k < n; k += 64u) {
+        let block = lo + vec3<u32>(k % extent.x, (k / extent.x) % extent.y, k / (extent.x * extent.y));
+        atomicOr(&coarse[grid3d_to_index(block, blocks.xy) * words + word], bit);
+    }
+}
+        `, [
+            chunk_cluster_coarse_blocks,
+            chunk_cluster_light_proxy,
+            chunk_grid3d_to_index,
+        ]
+    ),
+});

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

@@ -0,0 +1,11 @@
+/**
+ * Pass 2 of the cluster light assignment: one workgroup reads the visibility bitmask in order and writes
+ * the set bits out as {@link CLUSTER_LIGHT_LIST}, sorted by (type, id). It reads the bitmask through a
+ * plain read-only view: an atomic load would be an interlocked OR on D3D12.
+ *
+ * The cull list holds at most 16,383 lights, so one workgroup is enough; the rounds are over the
+ * tables' slots, which may be more.
+ */
+export const shader_cluster_light_compact: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_cluster_light_compact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_cluster_light_compact.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/cluster/shader_cluster_light_compact.js"],"names":[],"mappings":"AAqGA;;;;;;;GAOG;AACH,yDAIG;8BA/G2B,+BAA+B"}