@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/renderer/gpu_primitive/sort/shader_radix_sort_scatter.js

@@ -0,0 +1,192 @@
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_sort_digit } from "./chunk_sort_digit.js";
+import { chunk_sort_rank } from "./chunk_sort_rank.js";
+import { chunk_sort_workgroup_scan } from "./chunk_sort_workgroup_scan.js";
+import { RADIX, RADIX_LOG, SORT_KEYS_PER_THREAD, SORT_TILE_SIZE, SORT_WORKGROUP_SIZE } from "./defs.js";
+import { SORT_PASS_SETTINGS_STRUCT } from "./SORT_PASS_SETTINGS_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("settings", SORT_PASS_SETTINGS_STRUCT)
+    .addStorageBuffer("in_keys", WebGPUArray.from(u32), false)
+    .addStorageBuffer("in_values", WebGPUArray.from(u32), false)
+    .addStorageBuffer("out_keys", WebGPUArray.from(u32), true)
+    .addStorageBuffer("out_values", WebGPUArray.from(u32), true)
+    // scanned spine, read flat past its `{count, elements}` header
+    .addStorageBuffer("spine", WebGPUArray.from(u32), false);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE = ${SORT_WORKGROUP_SIZE}u;
+const KEYS_PER_THREAD = ${SORT_KEYS_PER_THREAD}u;
+const TILE_SIZE = ${SORT_TILE_SIZE}u;
+const RADIX = ${RADIX}u;
+const RADIX_LOG = ${RADIX_LOG}u;
+
+/**
+ * The key a slot past the end of the input is filled with. It is the largest u32, so its digit is
+ * the largest in every pass and the stable in-tile sort parks every one of them behind every real
+ * key — which is what makes "sorted position < the tile's real key count" a sufficient test for
+ * whether a slot holds a real key.
+ */
+const PADDING_KEY = 0xffffffffu;
+
+var<workgroup> wg_keys: array<u32, TILE_SIZE>;
+var<workgroup> wg_values: array<u32, TILE_SIZE>;
+// one bin per thread; RADIX == WORKGROUP_SIZE
+var<workgroup> wg_histogram: array<atomic<u32>, RADIX>;
+var<workgroup> wg_base: array<u32, RADIX>;
+
+@compute @workgroup_size(WORKGROUP_SIZE, 1, 1)
+fn main(
+    @builtin(local_invocation_index) thread_id: u32,
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(subgroup_invocation_id) lane_id: u32,
+    @builtin(subgroup_size) lane_count: u32,
+) {
+    let tile = workgroup_id.x;
+    let tile_base = tile * TILE_SIZE;
+    let shift = settings.shift;
+
+    atomicStore(&wg_histogram[thread_id], 0u);
+
+    // Striped load, so neighbouring threads read neighbouring addresses.
+    for (var k = 0u; k < KEYS_PER_THREAD; k += 1u) {
+        let slot = k * WORKGROUP_SIZE + thread_id;
+        let source = tile_base + slot;
+
+        var key = PADDING_KEY;
+        var value = 0u;
+
+        if (source < settings.element_count) {
+            key = in_keys[source];
+            value = in_values[source];
+        }
+
+        wg_keys[slot] = key;
+        wg_values[slot] = value;
+    }
+
+    workgroupBarrier();
+
+    // Local histogram over the real keys only — it has to agree with what the histogram pass
+    // counted, because the spine value this tile reads back was built from that count.
+    for (var k = 0u; k < KEYS_PER_THREAD; k += 1u) {
+        let slot = k * WORKGROUP_SIZE + thread_id;
+
+        if (tile_base + slot < settings.element_count) {
+            atomicAdd(&wg_histogram[sort_extract_digit(wg_keys[slot], shift)], 1u);
+        }
+    }
+
+    workgroupBarrier();
+
+    // this thread's bin, captured before the in-tile sort touches anything
+    let local_count = atomicLoad(&wg_histogram[thread_id]);
+
+    // Order the tile by this pass's digit, one bit at a time, least significant first. Eight stable
+    // binary splits are a sort by the whole 8-bit digit; ranking a key against its same-digit peers
+    // then costs nothing, because the rank IS the sorted position, and the device writes that
+    // follow come out contiguous per bin.
+    for (var bit_index = 0u; bit_index < RADIX_LOG; bit_index += 1u) {
+        let bit = shift + bit_index;
+
+        // Blocked ownership for the permutation: thread t owns the tile's slots
+        // [t*KEYS_PER_THREAD, (t+1)*KEYS_PER_THREAD), so the offsets a thread hands its own keys
+        // are consecutive and the scan below only has to run over one value per thread.
+        var keys: array<u32, KEYS_PER_THREAD>;
+        var values: array<u32, KEYS_PER_THREAD>;
+        var ones = 0u;
+
+        for (var j = 0u; j < KEYS_PER_THREAD; j += 1u) {
+            let slot = thread_id * KEYS_PER_THREAD + j;
+
+            keys[j] = wg_keys[slot];
+            values[j] = wg_values[slot];
+            ones += (keys[j] >> bit) & 1u;
+        }
+
+        // The scan's first barrier is what fences every thread's reads above against the writes
+        // below — by the time it returns, no read of wg_keys/wg_values is outstanding.
+        let scan = sort_workgroup_exclusive_scan(ones, thread_id, lane_id, lane_count);
+
+        let total_zeros = TILE_SIZE - scan.y;
+
+        var ones_before = scan.x;
+        var zeros_before = thread_id * KEYS_PER_THREAD - scan.x;
+
+        for (var j = 0u; j < KEYS_PER_THREAD; j += 1u) {
+            let is_one = ((keys[j] >> bit) & 1u) != 0u;
+            let destination = sort_split_destination(is_one, zeros_before, ones_before, total_zeros);
+
+            if (is_one) {
+                ones_before += 1u;
+            } else {
+                zeros_before += 1u;
+            }
+
+            wg_keys[destination] = keys[j];
+            wg_values[destination] = values[j];
+        }
+
+        workgroupBarrier();
+    }
+
+    // Exclusive prefix of the local histogram — for a tile now sorted by digit this is exactly the
+    // slot each bin's run begins at, and the total is the tile's real key count, because the
+    // padding was never counted.
+    let histogram_scan = sort_workgroup_exclusive_scan(local_count, thread_id, lane_id, lane_count);
+
+    let bin_start = histogram_scan.x;
+    let valid_count = histogram_scan.y;
+
+    let spine_inclusive = spine[sort_spine_index(thread_id, tile, settings.tile_count)];
+
+    wg_base[thread_id] = sort_scatter_base(spine_inclusive, local_count, bin_start);
+
+    workgroupBarrier();
+
+    for (var k = 0u; k < KEYS_PER_THREAD; k += 1u) {
+        let slot = k * WORKGROUP_SIZE + thread_id;
+
+        if (slot < valid_count) {
+            let key = wg_keys[slot];
+            let destination = wg_base[sort_extract_digit(key, shift)] + slot;
+
+            out_keys[destination] = key;
+            out_values[destination] = wg_values[slot];
+        }
+    }
+}
+`, [
+    chunk_sort_digit,
+    chunk_sort_rank,
+    chunk_sort_workgroup_scan,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Rank-and-scatter — stage (c) of one digit pass of {@link graph_radix_sort}.
+ *
+ * One workgroup per tile. The tile is sorted by the current digit in workgroup memory (stability is
+ * what an LSD radix sort's correctness rests on, and it is also what lets the tail tile's padding
+ * be identified by position), the tile's own histogram is re-derived rather than carried over from
+ * the histogram pass — the scan is inclusive-only, and re-counting is cheaper than preserving
+ * pre-scan counts — and each key is written to
+ * `spine_inclusive[bin] - local_count[bin] - bin_start[bin] + sorted_position`.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_radix_sort_scatter = ComputeShader.from({
+    label: "RadixSort/Scatter",
+    resources,
+    body,
+    group_size: [SORT_WORKGROUP_SIZE, 1, 1],
+});

package/src/shade/renderer/gpu_primitive/sort/verify_radix_sort.d.ts

@@ -0,0 +1,12 @@
+/**
+ * On-device verification of {@link graph_radix_sort}: sorts deterministic key/payload sets across
+ * tile-boundary element counts and three key distributions, reads the results back, and checks on
+ * the CPU that the keys are ascending, that the payload is a permutation of the input indices, that
+ * every payload still sits next to ITS key, and that equal keys kept their input order.
+ *
+ * Logs one `[SORT]` PASS/FAIL line per case.
+ *
+ * @param {GraphicsContext} graphics
+ */
+export function verify_radix_sort(graphics: GraphicsContext): void;
+//# sourceMappingURL=verify_radix_sort.d.ts.map

package/src/shade/renderer/gpu_primitive/sort/verify_radix_sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_radix_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/verify_radix_sort.js"],"names":[],"mappings":"AA+GA;;;;;;;;;GASG;AACH,mEAkEC"}

package/src/shade/renderer/gpu_primitive/sort/verify_radix_sort.js

@@ -0,0 +1,188 @@
+import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { ShadeGPUCommandContext } from "../../../device/ShadeGPUCommandContext.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { graph_inspect_gpu_buffer } from "../../buffer/graph_inspect_gpu_buffer.js";
+import { graph_import_typed_buffer } from "../../shader/graph/graph_import_typed_buffer.js";
+import { SORT_TILE_SIZE } from "./defs.js";
+import { graph_radix_sort } from "./graph_radix_sort.js";
+
+/**
+ * The element counts one run covers. The interesting ones are all at tile boundaries — the scatter's
+ * tail tile is padded, and a count one either side of an exact multiple is what exercises the
+ * padding guard from both directions.
+ *
+ * @type {number[]}
+ */
+const ELEMENT_COUNTS = [
+    2, 3, 255, 256, 257,
+    SORT_TILE_SIZE - 1, SORT_TILE_SIZE, SORT_TILE_SIZE + 1,
+    SORT_TILE_SIZE * 4 + 13,
+    100003,
+];
+
+/**
+ * @param {number} seed
+ * @returns {function(): number} LCG, so a failing run is reproducible
+ */
+function make_random(seed) {
+    let state = seed >>> 0;
+
+    return () => (state = (state * 1664525 + 1013904223) >>> 0);
+}
+
+/**
+ * The key distribution for one case. Three shapes, because a radix sort fails differently under
+ * each: dense duplicates stress stability and the in-tile split's equal-digit runs, a single
+ * repeated key makes every tile one bin, and full-range keys are the only ones that reach the top
+ * digit pass at all.
+ *
+ * @param {number} element_count
+ * @param {number} variant
+ * @returns {Uint32Array}
+ */
+function make_keys(element_count, variant) {
+    const random = make_random(0x9e3779b9 ^ (element_count * 31 + variant));
+
+    const keys = new Uint32Array(element_count);
+
+    for (let i = 0; i < element_count; i++) {
+        if (variant === 0) {
+            keys[i] = random() % 1000;
+        } else if (variant === 1) {
+            keys[i] = 0x2a2a2a2a;
+        } else {
+            keys[i] = random();
+        }
+    }
+
+    return keys;
+}
+
+/**
+ * @param {Uint32Array} input_keys
+ * @param {Uint32Array|number[]} sorted_keys
+ * @param {Uint32Array|number[]} sorted_values
+ * @returns {string[]} one entry per distinct problem found, empty when the sort is correct
+ */
+function problems_with(input_keys, sorted_keys, sorted_values) {
+    const element_count = input_keys.length;
+
+    const problems = [];
+
+    for (let i = 1; i < element_count; i++) {
+        if (sorted_keys[i] < sorted_keys[i - 1]) {
+            problems.push(`keys not ascending at [${i}]: ${sorted_keys[i - 1]} -> ${sorted_keys[i]}`);
+            break;
+        }
+    }
+
+    const seen = new Uint8Array(element_count);
+    for (let i = 0; i < element_count; i++) {
+        const value = sorted_values[i];
+
+        if (value >= element_count || seen[value] === 1) {
+            problems.push(`payload is not a permutation at [${i}]: ${value}`);
+            break;
+        }
+
+        seen[value] = 1;
+    }
+
+    for (let i = 0; i < element_count; i++) {
+        if (input_keys[sorted_values[i]] !== sorted_keys[i]) {
+            problems.push(`key/payload pairing broken at [${i}]: payload ${sorted_values[i]} `
+                + `had key ${input_keys[sorted_values[i]]}, sorted key is ${sorted_keys[i]}`);
+            break;
+        }
+    }
+
+    // payload is the input index, so a stable sort leaves equal keys with ascending payloads
+    for (let i = 1; i < element_count; i++) {
+        if (sorted_keys[i] === sorted_keys[i - 1] && sorted_values[i] < sorted_values[i - 1]) {
+            problems.push(`not stable at [${i}]: key ${sorted_keys[i]} came from index `
+                + `${sorted_values[i - 1]} then ${sorted_values[i]}`);
+            break;
+        }
+    }
+
+    return problems;
+}
+
+/**
+ * On-device verification of {@link graph_radix_sort}: sorts deterministic key/payload sets across
+ * tile-boundary element counts and three key distributions, reads the results back, and checks on
+ * the CPU that the keys are ascending, that the payload is a permutation of the input indices, that
+ * every payload still sits next to ITS key, and that equal keys kept their input order.
+ *
+ * Logs one `[SORT]` PASS/FAIL line per case.
+ *
+ * @param {GraphicsContext} graphics
+ */
+export function verify_radix_sort(graphics) {
+
+    const graph = new FrameGraph();
+    const cmd = ShadeGPUCommandContext.create(graphics, 'verify/radix sort');
+
+    const usage = GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE;
+
+    for (const element_count of ELEMENT_COUNTS) {
+        for (let variant = 0; variant < 3; variant++) {
+
+            const input_keys = make_keys(element_count, variant);
+            const input_values = new Uint32Array(element_count);
+            for (let i = 0; i < element_count; i++) {
+                input_values[i] = i;
+            }
+
+            const type = WebGPUArray.from(u32, element_count);
+            const label = `n=${element_count} variant=${variant}`;
+
+            const keys = graph_import_typed_buffer({
+                graph, type, value: input_keys, label: `verify sort keys ${label}`, usage
+            });
+            const values = graph_import_typed_buffer({
+                graph, type, value: input_values, label: `verify sort values ${label}`, usage
+            });
+
+            const sorted = graph_radix_sort({ graph, keys, values, element_count });
+
+            let sorted_keys;
+            let sorted_values;
+
+            function validate() {
+                if (sorted_keys === undefined || sorted_values === undefined) {
+                    // wait for both readbacks
+                    return;
+                }
+
+                const problems = problems_with(input_keys, sorted_keys, sorted_values);
+
+                if (problems.length === 0) {
+                    console.log(`%c[SORT] PASS ${label}`, 'color: #0c0');
+                } else {
+                    console.error(`[SORT] FAIL ${label}:\n  ${problems.join('\n  ')}`);
+                }
+            }
+
+            graph_inspect_gpu_buffer({
+                graph, type, buffer: sorted.keys,
+                callback([data]) {
+                    sorted_keys = data;
+                    validate();
+                }
+            });
+
+            graph_inspect_gpu_buffer({
+                graph, type, buffer: sorted.values,
+                callback([data]) {
+                    sorted_values = data;
+                    validate();
+                }
+            });
+        }
+    }
+
+    cmd.encodeGraph(graph);
+    cmd.finish();
+}

package/src/shade/renderer/scene/GPUInstancesAccelerationStructure.d.ts

@@ -4,9 +4,15 @@
 export class GPUInstancesAccelerationStructure {
     /**
      *
-     * @param {GPUDevice} device
+     * @param {GraphicsContext} graphics
+     */
+    constructor(graphics: GraphicsContext);
+    /**
+     * The CPU-side tree. Still maintained incrementally by the `instance_*` methods and still walked
+     * by CPU queries — {@link DirectionalLightShadowmap} runs `compute_tight_near_far_clipping_planes`
+     * against it per cascade per frame. What the GPU build retires is the per-frame treelet pass and
+     * the full flatten-and-upload, not the tree.
      */
-    constructor(device: GPUDevice);
     get bvh(): BVH;
     clear(): void;
     /**
@@ -34,8 +40,14 @@ export class GPUInstancesAccelerationStructure {
      * @param {Mesh} instance
      */
     instance_update(index: number, instance: Mesh): void;
-    push_to_gpu(): void;
-    update(): void;
+    /**
+     * @param {GPUBuffer} scene_database_buffer the table the world AABBs are read from
+     */
+    push_to_gpu(scene_database_buffer: GPUBuffer): void;
+    /**
+     * @param {GPUBuffer} scene_database_buffer
+     */
+    update(scene_database_buffer: GPUBuffer): void;
     #private;
 }
 import { BVH } from "../../../core/bvh2/bvh3/BVH.js";

package/src/shade/renderer/scene/GPUInstancesAccelerationStructure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUInstancesAccelerationStructure.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUInstancesAccelerationStructure.js"],"names":[],"mappings":"AAOA;;GAEG;AACH;IAmCI;;;OAGG;IACH,+BASC;IAvCD,eAEC;IAED,cAIC;IAOD;;;OAGG;IACH,wBAEC;IA0BD;;;;OAIG;IACH,oBAHW,MAAM,wBAkBhB;IAED;;;;;;OAMG;IACH,uBAFW,MAAM,QAiBhB;IAED;;;;OAIG;IACH,uBAHW,MAAM,wBAYhB;IAED,oBAkCC;IAED,eAMC;;CACJ;oBA1KmB,gCAAgC"}
+{"version":3,"file":"GPUInstancesAccelerationStructure.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUInstancesAccelerationStructure.js"],"names":[],"mappings":"AAgCA;;GAEG;AACH;IA2EI;;;OAGG;IACH,uCAcC;IA/ED;;;;;OAKG;IACH,eAEC;IAED,cAKC;IAOD;;;OAGG;IACH,wBAEC;IA2DD;;;;OAIG;IACH,oBAHW,MAAM,wBAmBhB;IAED;;;;;;OAMG;IACH,uBAFW,MAAM,QAkBhB;IAED;;;;OAIG;IACH,uBAHW,MAAM,wBAYhB;IAuID;;OAEG;IACH,oDAIC;IAED;;OAEG;IACH,+CAMC;;CACJ;oBA/VmB,gCAAgC"}