@woosh/meep-engine 3.11.2 → 3.12.0

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

@@ -1,198 +1,191 @@
-import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
-import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import {
-    shader_cull_point_lights_frustum,
-    shader_cull_spot_lights_frustum,
-    SHADER_CULL_LIGHTS_FRUSTUM_WORKGROUP_SIZE
-} from "./shader_cull_lights_frustum.js";
-import { shader_cull_lights_hzb, SHADER_CULL_LIGHTS_HZB_WORKGROUP_SIZE } from "./shader_cull_lights_hzb.js";
-
-/**
- * Maximum number of lights we can filter through
- * @type {number}
- */
-const LIGHT_LIMIT = 16383; // note 2^14-1, the -1 is to accommodate the counter while maintaining alignment
-
-
-const OUTPUT_DESCRIPTOR = BufferResourceDescriptor.from(
-    u32.size * (1 + LIGHT_LIMIT), // 64k
-    GPUBufferUsage.STORAGE,
-    0, 16, // clear light count
-);
-
-/**
- * How many lights are eligible for clustered shading on this frame? Directional
- * lights are excluded — they are global and not bound to any cluster.
- *
- * @param {GPULightCollection} lights
- * @returns {number}
- */
-function clusterable_light_count(lights) {
-    const source = lights.source.elements;
-    let count = 0;
-
-    for (let i = 0; i < source.length; i++) {
-        const light = source[i];
-
-        if (light.isPointLight === true || light.isSpotLight === true) {
-            count++;
-        }
-    }
-
-    return count;
-}
-
-/**
- *
- * @param {GPULightCollection} lights
- * @param {GPUCameraContext} camera
- * @param {FrameGraph} graph
- * @return {number}
- */
-function graph_cull_lights_frustum({ lights, camera, graph }) {
-    /**
-     *
-     * @param data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     */
-    function execute(data, resources, context) {
-
-        const output = resources.get(data.output);
-
-        // Per-thread dispatch — one thread per (page, in_page_slot)
-        // pair, sized to the table's currently allocated capacity.
-        // Threads landing on unallocated pages or unoccupied slots
-        // early-return; visible lights are atomically appended to
-        // the output buffer.
-        const point_table = lights.database.get('light_point');
-        const spot_table = lights.database.get('light_spot');
-        const point_thread_count = point_table.dispatch_page_count * point_table.descriptor.elements_per_page;
-        const spot_thread_count = spot_table.dispatch_page_count * spot_table.descriptor.elements_per_page;
-
-        if (point_thread_count > 0) {
-            shader_cull_point_lights_frustum.dispatch({
-                encoder: context.encoder,
-                bindings: {
-                    camera: camera.buffer,
-                    light_data: lights.buffer_data,
-                    output,
-                },
-                group_count_x: Math.ceil(point_thread_count / SHADER_CULL_LIGHTS_FRUSTUM_WORKGROUP_SIZE),
-            });
-        }
-
-        if (spot_thread_count > 0) {
-            shader_cull_spot_lights_frustum.dispatch({
-                encoder: context.encoder,
-                bindings: {
-                    camera: camera.buffer,
-                    light_data: lights.buffer_data,
-                    output,
-                },
-                group_count_x: Math.ceil(spot_thread_count / SHADER_CULL_LIGHTS_FRUSTUM_WORKGROUP_SIZE),
-            });
-        }
-
-    }
-
-    const data = {};
-
-    const pass = graph.add("cull lights / frustum", data, execute);
-
-    data.output = pass.create("list", OUTPUT_DESCRIPTOR);
-
-    return data.output;
-}
-
-
-/**
- *
- * @param {number} list
- * @param {GPULightCollection} lights
- * @param {GPUCameraContext} camera
- * @param {FrameGraph} graph
- * @param {number} hzb
- * @return {number}
- */
-function graph_cull_lights_hzb({
-                                   list,
-                                   lights,
-                                   camera,
-                                   graph,
-                                   hzb
-                               }) {
-    /**
-     *
-     * @param data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     */
-    function execute(data, resources, context) {
-
-        const input = resources.get(data.input);
-        const output = resources.get(data.output);
-        const hzb = resources.get(data.hzb);
-
-        const candidate_count = clusterable_light_count(lights);
-
-        if (candidate_count <= 0) {
-            // TODO should use indirect dispatch
-            // no culling work
-            return;
-        }
-
-        // TODO use indirect dispatch
-        const group_count = Math.ceil(candidate_count / SHADER_CULL_LIGHTS_HZB_WORKGROUP_SIZE);
-
-        shader_cull_lights_hzb.dispatch({
-            encoder: context.encoder,
-            bindings: {
-                texture_hzb: hzb,
-                camera: camera.buffer,
-                input,
-                light_data: lights.buffer_data,
-                output,
-            },
-            group_count_x: group_count,
-        });
-
-    }
-
-    const data = {};
-
-    const pass = graph.add("cull lights / HZB", data, execute);
-
-    data.input = pass.read(list);
-    data.hzb = pass.read(hzb);
-    data.output = pass.create("output", OUTPUT_DESCRIPTOR);
-
-    return data.output;
-}
-
-/**
- *
- * @param {FrameGraph} graph
- * @param {GPULightCollection} lights
- * @param {GPUCameraContext} camera
- * @param {number} hzb
- */
-export function graph_cull_lights({
-                                      graph,
-                                      lights,
-                                      camera,
-                                      hzb,
-                                  }) {
-
-    // TODO cull useless lights where radius is <= 0 or total luma is <= 0
-
-    let culled = graph_cull_lights_frustum({ lights, camera, graph });
-
-    return graph_cull_lights_hzb({
-        list: culled,
-        lights,
-        camera,
-        graph,
-        hzb,
-    });
-}
+import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import {
+    shader_cull_point_lights_frustum,
+    shader_cull_spot_lights_frustum
+} from "./shader_cull_lights_frustum.js";
+import { shader_cull_lights_hzb } from "./shader_cull_lights_hzb.js";
+
+/**
+ * Maximum number of lights we can filter through
+ * @type {number}
+ */
+const LIGHT_LIMIT = 16383; // note 2^14-1, the -1 is to accommodate the counter while maintaining alignment
+
+
+const OUTPUT_DESCRIPTOR = BufferResourceDescriptor.from(
+    u32.size * (1 + LIGHT_LIMIT), // 64k
+    GPUBufferUsage.STORAGE,
+    0, 16, // clear light count
+);
+
+/**
+ * How many lights are eligible for clustered shading on this frame? Directional
+ * lights are excluded — they are global and not bound to any cluster.
+ *
+ * @param {GPULightCollection} lights
+ * @returns {number}
+ */
+function clusterable_light_count(lights) {
+    const source = lights.source.elements;
+    let count = 0;
+
+    for (let i = 0; i < source.length; i++) {
+        const light = source[i];
+
+        if (light.isPointLight === true || light.isSpotLight === true) {
+            count++;
+        }
+    }
+
+    return count;
+}
+
+/**
+ *
+ * @param {GPULightCollection} lights
+ * @param {GPUCameraContext} camera
+ * @param {FrameGraph} graph
+ * @return {number}
+ */
+function graph_cull_lights_frustum({ lights, camera, graph }) {
+    /**
+     *
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(data, resources, context) {
+
+        const output = resources.get(data.output);
+
+        // Per-thread dispatch — one thread per (page, in_page_slot)
+        // pair, sized to the table's currently allocated capacity.
+        // Threads landing on unallocated pages or unoccupied slots
+        // early-return; visible lights are atomically appended to
+        // the output buffer.
+        const point_table = lights.database.get('light_point');
+        const spot_table = lights.database.get('light_spot');
+        const point_thread_count = point_table.dispatch_page_count * point_table.descriptor.elements_per_page;
+        const spot_thread_count = spot_table.dispatch_page_count * spot_table.descriptor.elements_per_page;
+
+        shader_cull_point_lights_frustum.dispatchThreads({
+            encoder: context.encoder,
+            bindings: {
+                camera: camera.buffer,
+                light_data: lights.buffer_data,
+                output,
+            },
+            thread_count_x: point_thread_count,
+        });
+
+        shader_cull_spot_lights_frustum.dispatchThreads({
+            encoder: context.encoder,
+            bindings: {
+                camera: camera.buffer,
+                light_data: lights.buffer_data,
+                output,
+            },
+            thread_count_x: spot_thread_count,
+        });
+
+    }
+
+    const data = {};
+
+    const pass = graph.add("cull lights / frustum", data, execute);
+
+    data.output = pass.create("list", OUTPUT_DESCRIPTOR);
+
+    return data.output;
+}
+
+
+/**
+ *
+ * @param {number} list
+ * @param {GPULightCollection} lights
+ * @param {GPUCameraContext} camera
+ * @param {FrameGraph} graph
+ * @param {number} hzb
+ * @return {number}
+ */
+function graph_cull_lights_hzb({
+                                   list,
+                                   lights,
+                                   camera,
+                                   graph,
+                                   hzb
+                               }) {
+    /**
+     *
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(data, resources, context) {
+
+        const input = resources.get(data.input);
+        const output = resources.get(data.output);
+        const hzb = resources.get(data.hzb);
+
+        const candidate_count = clusterable_light_count(lights);
+
+        if (candidate_count <= 0) {
+            // TODO should use indirect dispatch
+            // no culling work
+            return;
+        }
+
+        // TODO use indirect dispatch
+        shader_cull_lights_hzb.dispatchThreads({
+            encoder: context.encoder,
+            bindings: {
+                texture_hzb: hzb,
+                camera: camera.buffer,
+                input,
+                light_data: lights.buffer_data,
+                output,
+            },
+            thread_count_x: candidate_count,
+        });
+
+    }
+
+    const data = {};
+
+    const pass = graph.add("cull lights / HZB", data, execute);
+
+    data.input = pass.read(list);
+    data.hzb = pass.read(hzb);
+    data.output = pass.create("output", OUTPUT_DESCRIPTOR);
+
+    return data.output;
+}
+
+/**
+ *
+ * @param {FrameGraph} graph
+ * @param {GPULightCollection} lights
+ * @param {GPUCameraContext} camera
+ * @param {number} hzb
+ */
+export function graph_cull_lights({
+                                      graph,
+                                      lights,
+                                      camera,
+                                      hzb,
+                                  }) {
+
+    // TODO cull useless lights where radius is <= 0 or total luma is <= 0
+
+    let culled = graph_cull_lights_frustum({ lights, camera, graph });
+
+    return graph_cull_lights_hzb({
+        list: culled,
+        lights,
+        camera,
+        graph,
+        hzb,
+    });
+}

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

@@ -1,9 +1,3 @@
-/**
- * Workgroup size used by both point/spot cull dispatches; the host
- * sizes the dispatch as ceil(dispatch_page_count * elements_per_page / WORKGROUP_SIZE).
- * @type {number}
- */
-export const SHADER_CULL_LIGHTS_FRUSTUM_WORKGROUP_SIZE: number;
 export const shader_cull_point_lights_frustum: ComputeShader;
 export const shader_cull_spot_lights_frustum: ComputeShader;
 export const shader_cull_lights_frustum: ComputeShader;

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":"AAkBA;;;;GAIG;AACH,wDAFU,MAAM,CAE2E;AA2E3F,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;AAGH,uDAA2E;8BAzG7C,kCAAkC"}

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

@@ -1,120 +1,120 @@
-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 dispatches; the host
- * sizes the dispatch as ceil(dispatch_page_count * elements_per_page / WORKGROUP_SIZE).
- * @type {number}
- */
-export 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,
+});
+
+// Compatibility re-export — graph_cull_lights still imports this name.
+export const shader_cull_lights_frustum = shader_cull_point_lights_frustum;

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

@@ -1,7 +1,3 @@
-/**
- * @type {number}
- */
-export const SHADER_CULL_LIGHTS_HZB_WORKGROUP_SIZE: number;
 export const shader_cull_lights_hzb: ComputeShader;
 import { ComputeShader } from "../../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_cull_lights_hzb.d.ts.map