@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -2,59 +2,69 @@ import { assert } from "../../../../core/assert.js";
 import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
 import { graph_import_typed_buffer } from "../../shader/graph/graph_import_typed_buffer.js";
 import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { update_frustum_far_plane } from "../../shadow/map/update_frustum_far_plane.js";
-import { slice_flat_array } from "../../util/slice_flat_array.js";
+import { RasterizationCollectionType } from "../../rasterize/expand/RasterizationCollectionType.js";
+import { graph_record_stat } from "../../util/graph_record_stat.js";
 import { build_light_cluster_parameters } from "./build_light_cluster_parameters.js";
-import { LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT } from "./LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT.js";
+import { CLUSTER_LIGHT_PROXY } from "./CLUSTER_LIGHT_PROXY.js";
+import { LIGHT_LIMIT } from "./cull/graph_cull_lights.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";
+import { shader_cluster_assign_lights } from "./shader_cluster_assign_lights.js";
 import {
-    LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS,
-    shader_cluster_assign_lights
-} from "./shader_cluster_assign_lights.js";
+    LIGHT_CLUSTER_COARSE_CLEAR_ROW,
+    shader_cluster_coarse_clear,
+    shader_cluster_coarse_scatter
+} from "./shader_cluster_coarse_mark.js";
+import { shader_cluster_light_compact } from "./shader_cluster_light_compact.js";
+import { shader_cluster_light_mark } from "./shader_cluster_light_mark.js";
+import { shader_cluster_light_prepare } from "./shader_cluster_light_prepare.js";
 
 /**
  * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 
-
 /**
- * cluster datastructures can get quite large quickly, we control this by exploiting a basic assumption that local lights tend to affect only small part of the scene
+ * The entries `cluster_data` is primed with for a grid, before any bound has been read back: 64.5 per
+ * cell, the size the 128-per-type cap used to imply.
  * @param {number} total_cluster_count
  * @return {number}
  */
-function estimate_cluster_data_limit(total_cluster_count) {
-    assert.isNumber(total_cluster_count, 'total_cluster_count');
-    assert.notNaN(total_cluster_count, 'total_cluster_count');
-
-    // average percentage of occupancy per cluster relative to limit
-    const ASSUMED_OCCUPANCY_RATIO = 0.5;
-
-    // minimum number of elements per cluster
-    const ASSUMED_MIN_LIGHTS = 1;
-
-    // % of how many clusters are assumed to be full at any given time
-    const RESERVED_FULL_CLUSTERS_PERCENTAGE = 0.5;
-
-    const ASSUMED_FULL_CLUSTER_COUNT = Math.ceil(total_cluster_count * RESERVED_FULL_CLUSTERS_PERCENTAGE);
-
-    return Math.ceil(Math.max(
-        Math.max(0, total_cluster_count - ASSUMED_FULL_CLUSTER_COUNT) * ASSUMED_MIN_LIGHTS + ASSUMED_FULL_CLUSTER_COUNT * LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT,
-        total_cluster_count * LIGHT_CLUSTER_LOCAL_LIGHT_LIMIT * ASSUMED_OCCUPANCY_RATIO
-    ));
+export function estimate_cluster_data_limit(total_cluster_count) {
+    assert.isNonNegativeInteger(total_cluster_count, 'total_cluster_count');
 
+    return Math.ceil(total_cluster_count * 64.5);
 }
 
 /**
- * Offer the pipeline {@link graph_assign_clsuters} dispatches — see {@link PipelineEnquiry}.
+ * Offer the pipelines {@link graph_assign_clsuters} dispatches — see {@link PipelineEnquiry}.
  *
  * @param {PipelineEnquiry} enquiry
  */
 export function enquire_assign_clusters_pipelines(enquiry) {
+    enquiry.compute.push(shader_cluster_light_mark.pipeline);
+    enquiry.compute.push(shader_cluster_light_compact.pipeline);
+    enquiry.compute.push(shader_cluster_light_prepare.pipeline);
+    enquiry.compute.push(shader_cluster_coarse_clear.pipeline);
+    enquiry.compute.push(shader_cluster_coarse_scatter.pipeline);
     enquiry.compute.push(shader_cluster_assign_lights.pipeline);
 }
 
 /**
+ * Assign the culled lights to the cells of the cluster grid. Six dispatches in one compute pass, all
+ * with workgroup counts known here:
+ * 1. mark: the culled lights into a bitmask over the light tables' slots;
+ * 2. compact: the bitmask into a list sorted by (type, id);
+ * 3. prepare: per light, its view-space proxy, its box of cells, and the sizing bound;
+ * 4. coarse clear, 5. coarse scatter: per 4×4×4 block of cells, a bitmask of the lights whose boxes touch it;
+ * 6. fine: per cell, the precise tests, every hit counted and written.
+ * With no light that can reach the list, only compact (which writes the empty list) and fine run.
+ *
+ * `cluster_data` is sized by `limits`' {@link RasterizationCollectionType.LightClusterEntries}, which
+ * the frame's bound is recorded into: a frame that needs more than it holds keeps what fits, and the
+ * frames after it are sized up. A grid larger than any before primes the column with
+ * {@link estimate_cluster_data_limit} first.
  *
  * @param {Object} options
  * @param {FrameGraph} options.graph
@@ -62,6 +72,7 @@ export function enquire_assign_clusters_pipelines(enquiry) {
  * @param {GPULightCollection} options.lights
  * @param {number} options.list
  * @param {number[]} options.resolution
+ * @param {GPUCollectionLimits} options.limits
  * @return {{cluster_lookup:number, cluster_data:number, cluster_parameters:number}}
  */
 export function graph_assign_clsuters({
@@ -70,51 +81,54 @@ export function graph_assign_clsuters({
                                           lights,
                                           list,
                                           resolution,
+                                          limits,
                                       }) {
 
     assert.defined(resolution, 'resolution');
     assert.isArrayLike(resolution, 'resolution');
+    assert.defined(limits, 'limits');
 
     graph.push_scope("assign clusters");
 
-    const cluster_params = build_light_cluster_parameters(
-        [], 0,
-        LIGHT_CLUSTER_RESOLUTION_Z,
-        camera.camera.near,
-        camera.camera.far,
-        0.2,
-        4.06
-    );
+    const point_table = lights.database.get('light_point');
+    const spot_table = lights.database.get('light_spot');
 
-    const clipped_frustum = new Float32Array(24);
+    // one bit per table slot: ids are slots
+    const point_words = Math.ceil(point_table.element_capacity / 32);
+    const visibility_words = point_words + Math.ceil(spot_table.element_capacity / 32);
 
-    clipped_frustum.set(camera.camera.frustum);
-    update_frustum_far_plane(
-        clipped_frustum,
-        camera.camera.view_matrix,
-        camera.camera.far,
-    );
+    // the most entries the sorted list can hold: the lights the tables hold, not the slots their pages have
+    const light_limit = Math.min(LIGHT_LIMIT, point_table.count + spot_table.count);
 
     const gr_settings = graph_import_typed_buffer({
         graph,
-        type: LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS,
+        type: LIGHT_CLUSTER_ASSIGNMENT_SETTINGS,
         value: {
-            cluster_params,
-            screen_resolution: resolution,
-            distance_min: camera.camera.near,
-            distance_max: camera.camera.far,
-            frustum: slice_flat_array(
-                clipped_frustum,
-                0,
-                4,
-                6
+            cluster_parameters: build_light_cluster_parameters(
+                [], 0,
+                LIGHT_CLUSTER_RESOLUTION_Z,
+                camera.camera.near,
+                camera.camera.far,
+                0.2,
+                4.06
             ),
+            near: camera.camera.near,
+            screen_resolution: resolution,
+            point_words,
+            visibility_words,
         },
         label: "cluster settings",
     });
 
-    const cluster_count_x = Math.ceil(resolution[0] / LIGHT_CLUSTER_TILE_RESOLUTION);
-    const cluster_count_y = Math.ceil(resolution[1] / LIGHT_CLUSTER_TILE_RESOLUTION);
+    const grid = [
+        Math.ceil(resolution[0] / LIGHT_CLUSTER_TILE_RESOLUTION),
+        Math.ceil(resolution[1] / LIGHT_CLUSTER_TILE_RESOLUTION),
+        LIGHT_CLUSTER_RESOLUTION_Z,
+    ];
+    const blocks = grid.map(n => Math.ceil(n / LIGHT_CLUSTER_COARSE_BLOCK));
+    const coarse_words = Math.ceil(light_limit / 32);
+    // one thread per mask word, folded into rows
+    const clear_groups = Math.ceil(blocks[0] * blocks[1] * blocks[2] * coarse_words / shader_cluster_coarse_clear.group_size_x);
 
     const data = {};
 
@@ -125,60 +139,144 @@ export function graph_assign_clsuters({
      * @param {GraphicsExecutionContext} context
      */
     function execute(data, resources, context) {
+        const encoder = context.encoder;
+
+        const settings = resources.get(data.settings);
         const input = resources.get(data.input);
+        const visibility = resources.get(data.visibility);
+        const sorted = resources.get(data.lights);
+        const proxies = resources.get(data.proxies);
+        const boxes = resources.get(data.boxes);
+        const bound = resources.get(data.bound);
+        const coarse = resources.get(data.coarse);
         const cluster_lookup = resources.get(data.cluster_lookup);
         const cluster_data = resources.get(data.cluster_data);
-        const cluster_parameters = resources.get(data.cluster_parameters);
 
-        shader_cluster_assign_lights.dispatchThreads({
-            encoder: context.encoder,
+        const pass = encoder.beginComputePass({ label: "assign clusters" });
 
-            thread_count_x: cluster_count_x,
-            thread_count_y: cluster_count_y,
-            thread_count_z: LIGHT_CLUSTER_RESOLUTION_Z,
+        if (light_limit > 0) {
+            shader_cluster_light_mark.dispatchInPass({
+                encoder, pass,
+                bindings: { settings, input, visibility },
+                group_count_x: Math.ceil(light_limit / shader_cluster_light_mark.group_size_x),
+            });
+        }
 
+        shader_cluster_light_compact.dispatchInPass({
+            encoder, pass,
+            bindings: { settings, visibility, lights: sorted },
+        });
+
+        if (light_limit > 0) {
+            shader_cluster_light_prepare.dispatchInPass({
+                encoder, pass,
+                bindings: {
+                    camera: camera.buffer,
+                    settings,
+                    lights: sorted,
+                    light_data: lights.buffer_data,
+                    proxies,
+                    boxes,
+                    bound,
+                },
+                group_count_x: Math.ceil(light_limit / shader_cluster_light_prepare.group_size_x),
+            });
+
+            shader_cluster_coarse_clear.dispatchInPass({
+                encoder, pass,
+                bindings: { settings, lights: sorted, coarse },
+                group_count_x: Math.min(clear_groups, LIGHT_CLUSTER_COARSE_CLEAR_ROW),
+                group_count_y: Math.ceil(clear_groups / LIGHT_CLUSTER_COARSE_CLEAR_ROW),
+            });
+
+            shader_cluster_coarse_scatter.dispatchInPass({
+                encoder, pass,
+                bindings: { settings, lights: sorted, boxes, coarse },
+                group_count_x: light_limit,
+            });
+        }
+
+        shader_cluster_assign_lights.dispatchInPass({
+            encoder, pass,
             bindings: {
                 camera: camera.buffer,
-                light_data: lights.buffer_data,
-                input,
+                settings,
+                lights: sorted,
+                proxies,
+                boxes,
+                coarse,
                 cluster_lookup,
                 cluster_data,
-                settings: {
-                    buffer: cluster_parameters,
-                    size: LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS.size,
-                },
             },
-
+            group_count_x: blocks[0],
+            group_count_y: blocks[1],
+            group_count_z: blocks[2],
         });
+
+        pass.end();
     }
 
     const builder = graph.add("assign clusters", data, execute);
 
     data.input = builder.read(list);
-    data.cluster_parameters = builder.read(gr_settings);
+    data.settings = builder.read(gr_settings);
 
-    const LIGHT_CLUSTER_COUNT = LIGHT_CLUSTER_RESOLUTION_Z * cluster_count_x * cluster_count_y;
+    const lights_capacity = Math.max(1, light_limit);
+
+    data.visibility = builder.create("light visibility", BufferResourceDescriptor.from(
+        u32.size * Math.max(4, visibility_words),
+        GPUBufferUsage.STORAGE,
+        0, u32.size * Math.max(4, visibility_words), // mark ORs into a zeroed bitmask
+    ));
+    data.lights = builder.create("sorted lights", BufferResourceDescriptor.from(
+        u32.size * (2 + lights_capacity),
+        GPUBufferUsage.STORAGE,
+    ));
+    data.proxies = builder.create("light proxies", BufferResourceDescriptor.from(
+        CLUSTER_LIGHT_PROXY.aligned_size * lights_capacity,
+        GPUBufferUsage.STORAGE,
+    ));
+    data.boxes = builder.create("light cell boxes", BufferResourceDescriptor.from(
+        16 * lights_capacity,
+        GPUBufferUsage.STORAGE,
+    ));
+    data.bound = builder.create("cluster data bound", BufferResourceDescriptor.from(
+        16,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC, // copied into the limits' stats
+        0, 16, // the sum starts at 0
+    ));
+    data.coarse = builder.create("coarse light masks", BufferResourceDescriptor.from(
+        u32.size * Math.max(4, blocks[0] * blocks[1] * blocks[2] * coarse_words),
+        GPUBufferUsage.STORAGE,
+    ));
+
+    const cluster_count = grid[0] * grid[1] * grid[2];
 
     data.cluster_lookup = builder.create("cluster_lookup", BufferResourceDescriptor.from(
-        LIGHT_CLUSTER_METADATA.size * LIGHT_CLUSTER_COUNT,
+        LIGHT_CLUSTER_METADATA.size * cluster_count,
         GPUBufferUsage.STORAGE,
     ));
 
-    const CLUSTER_DATA_SIZE_LIMIT = estimate_cluster_data_limit(LIGHT_CLUSTER_COUNT);
+    const primed = estimate_cluster_data_limit(cluster_count);
 
-    const data_size = u32.size * (1 + CLUSTER_DATA_SIZE_LIMIT);
+    if (limits.get_limit(RasterizationCollectionType.LightClusterEntries) < primed) {
+        limits.prime(RasterizationCollectionType.LightClusterEntries, primed);
+    }
 
     data.cluster_data = builder.create("cluster_data", BufferResourceDescriptor.from(
-        data_size,
+        // the allocation counter, then the entries
+        u32.size + limits.compute_buffer_size(RasterizationCollectionType.LightClusterEntries),
         GPUBufferUsage.STORAGE,
         0, 16, // clear offset
     ));
 
+    graph_record_stat(graph, limits.stats, RasterizationCollectionType.LightClusterEntries, data.bound);
+
     graph.pop_scope();
 
     return {
         cluster_lookup: data.cluster_lookup,
         cluster_data: data.cluster_data,
-        cluster_parameters: data.cluster_parameters,
+        cluster_parameters: data.settings,
     }
-}
+}

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

@@ -12,13 +12,15 @@ export function enquire_build_light_clusters_pipelines(enquiry: PipelineEnquiry)
  * @param {number} options.hzb
  * @param {GPUCameraContext} options.camera
  * @param {number[]} options.resolution
+ * @param {GPUCollectionLimits} options.limits sizes the clusters' light lists
  */
-export function graph_build_light_clusters({ graph, lights, hzb, camera, resolution, }: {
+export function graph_build_light_clusters({ graph, lights, hzb, camera, resolution, limits, }: {
     graph: FrameGraph;
     lights: GPULightCollection;
     hzb: number;
     camera: GPUCameraContext;
     resolution: number[];
+    limits: GPUCollectionLimits;
 }): {
     /**
      * @type {number}

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

@@ -1 +1 @@
-{"version":3,"file":"graph_build_light_clusters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/cluster/graph_build_light_clusters.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,gEAFW,eAAe,QAKzB;AAED;;;;;;;;GAQG;AACH;IAN+B,KAAK;IACG,MAAM;IAClB,GAAG,EAAnB,MAAM;IACoB,MAAM;IACd,UAAU,EAA5B,MAAM,EAAE;;IAsEX;;OAEG;UADO,MAAM;IAGhB;;OAEG;YADO,MAAM;;EAKvB;8BAtGY,OAAO,6CAA6C,EAAE,eAAe"}
+{"version":3,"file":"graph_build_light_clusters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/cluster/graph_build_light_clusters.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,gEAFW,eAAe,QAKzB;AAED;;;;;;;;;GASG;AACH;IAP+B,KAAK;IACG,MAAM;IAClB,GAAG,EAAnB,MAAM;IACoB,MAAM;IACd,UAAU,EAA5B,MAAM,EAAE;IACqB,MAAM;;IAwEtC;;OAEG;UADO,MAAM;IAGhB;;OAEG;YADO,MAAM;;EAKvB;8BAzGY,OAAO,6CAA6C,EAAE,eAAe"}

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

@@ -25,6 +25,7 @@ export function enquire_build_light_clusters_pipelines(enquiry) {
  * @param {number} options.hzb
  * @param {GPUCameraContext} options.camera
  * @param {number[]} options.resolution
+ * @param {GPUCollectionLimits} options.limits sizes the clusters' light lists
  */
 export function graph_build_light_clusters({
                                                graph,
@@ -32,6 +33,7 @@ export function graph_build_light_clusters({
                                                hzb,
                                                camera,
                                                resolution,
+                                               limits,
                                            }) {
 
 
@@ -60,6 +62,7 @@ export function graph_build_light_clusters({
         lights,
         list: culled_light_list,
         resolution,
+        limits,
     });
 
 

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

@@ -1,7 +1,19 @@
-export const LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS: WebGPUStruct;
+/**
+ * Each cell's metadata, see {@link LIGHT_CLUSTER_METADATA}
+ * @type {WebGPUArray}
+ */
 export const LIGHT_CLUSTER_LOOKUP_STRUCT: WebGPUArray;
+/**
+ * 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;
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_cluster_assign_lights.d.ts.map

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":"AAgCA,mEAMG;AAmBH,sDAAoF;AA8IpF,yDAIG;6BAzM0B,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":"AA0CA;;;GAGG;AACH,0CAFU,WAAW,CAE+D;AA0OpF;;;;;;;;;GASG;AACH,yDAIG;4BA/RyB,kCAAkC;8BAHhC,+BAA+B"}