@woosh/meep-engine 3.3.0 → 3.4.0

package/src/shade/renderer/gpu_primitive/bvh/verify_gpu_bvh_build.js

@@ -0,0 +1,422 @@
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import { ebvh_build_hierarchy_radix } from "../../../../core/bvh2/bvh3/ebvh_build_hierarchy_radix.js";
+import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { ShadeGPUCommandContext } from "../../../device/ShadeGPUCommandContext.js";
+import { f32, 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 { bvh_buffer_size } from "./BVH_BUFFER_LAYOUT.js";
+import {
+    check_bvh_structure,
+    format_depth_histogram,
+    read_bvh_node,
+    surface_area,
+    TRAVERSAL_STACK_SIZE
+} from "./check_bvh_structure.js";
+import { graph_bvh_build_lbvh } from "./graph_bvh_build_lbvh.js";
+
+/**
+ * @param {number} seed
+ * @returns {function(): number} LCG, so a failing case is reproducible
+ */
+function make_random(seed) {
+    let state = seed >>> 0;
+
+    return () => (state = (state * 1664525 + 1013904223) >>> 0);
+}
+
+/**
+ * The leaf sets one run covers. Each is a name and a generator, because the shapes that break an
+ * LBVH are not the ones a uniform random cloud produces.
+ *
+ * @returns {{name: string, count: number, make: function(number, number): {low: number[], high: number[]}}[]}
+ */
+function cases() {
+    /**
+     * A box around a random point.
+     * @param {function(): number} random
+     * @param {number} spread
+     * @returns {function(): {low: number[], high: number[]}}
+     */
+    function scattered(spread) {
+        return random => {
+            const unit = () => (random() / 0x100000000) * 2 - 1;
+
+            const centre = [unit() * spread, unit() * spread, unit() * spread];
+            const half = [0.5 + Math.abs(unit()), 0.5 + Math.abs(unit()), 0.5 + Math.abs(unit())];
+
+            return {
+                low: centre.map((c, a) => c - half[a]),
+                high: centre.map((c, a) => c + half[a]),
+            };
+        };
+    }
+
+    /**
+     * A box with no volume at all — a point. Legal input, and the case where a centroid and a
+     * corner are the same number.
+     * @param {function(): number} random
+     * @returns {{low: number[], high: number[]}}
+     */
+    function degenerate(random) {
+        const unit = () => (random() / 0x100000000) * 2 - 1;
+
+        const point = [unit() * 50, unit() * 50, unit() * 50];
+
+        return { low: point.slice(), high: point.slice() };
+    }
+
+    const shapes = [
+        ['scattered', scattered(100)],
+        // every instance at the same place: every Morton code identical, and the duplicate-key
+        // tiebreak in `delta` is then the only thing holding the tree together
+        ['coincident', () => ({ low: [1, 2, 3], high: [4, 5, 6] })],
+        // clustered tightly enough that quantisation collapses long runs to one code
+        ['clustered', scattered(0.0004)],
+        ['degenerate', degenerate],
+        // half of everything piled at the origin, the rest spread out — mixed duplicate runs
+        ['mixed', (random, i) => (i % 2 === 0 ? { low: [0, 0, 0], high: [0, 0, 0] } : scattered(100)(random))],
+    ];
+
+    // Counts either side of every boundary the pipeline has: the emission kernel's tail thread, the
+    // builder's 64-wide workgroups, and the sort's 1024-key tile.
+    const counts = [1, 2, 3, 4, 7, 8, 9, 63, 64, 65, 1023, 1024, 1025, 100003];
+
+    const result = [];
+
+    for (const count of counts) {
+        for (const [shape_name, make] of shapes) {
+            // Every shape at the small counts, where a case costs nothing and the edges live.
+            // Above that, the two that say the most: an ordinary cloud, and the pathological
+            // all-one-code set.
+            if (count > 200 && shape_name !== 'scattered' && shape_name !== 'coincident') {
+                continue;
+            }
+
+            result.push({ name: `n=${count} ${shape_name}`, count, make });
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Materialise a case into the flat arrays the builder consumes.
+ *
+ * @param {{name: string, count: number, make: function}} test_case
+ * @returns {{bounds: Float32Array, payload: Uint32Array, scene: Float32Array}}
+ */
+function build_input(test_case) {
+    const { count, make } = test_case;
+
+    const random = make_random(0x1234567 ^ (count * 2654435761));
+
+    const bounds = new Float32Array(count * 6);
+    const payload = new Uint32Array(count);
+
+    for (let i = 0; i < count; i++) {
+        const box = make(random, i);
+
+        bounds.set([...box.low, ...box.high], i * 6);
+
+        // sparse, unordered rows — never the leaf index, so a mixed-up permutation shows
+        payload[i] = 11 + i * 7;
+    }
+
+    const scene = new Float32Array(6);
+
+    scene.set([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+
+    for (let i = 0; i < count; i++) {
+        for (let axis = 0; axis < 3; axis++) {
+            scene[axis] = Math.min(scene[axis], bounds[i * 6 + axis]);
+            scene[3 + axis] = Math.max(scene[3 + axis], bounds[i * 6 + 3 + axis]);
+        }
+    }
+
+    return { bounds, payload, scene };
+}
+
+/**
+ * Everything {@link check_bvh_structure} holds, plus the one thing only this harness can: the
+ * topology, node for node, against `ebvh_build_hierarchy_radix` — fed the GPU's OWN sorted order,
+ * so a mismatch means the emission kernel disagrees with the oracle rather than that the two
+ * quantisers rounded a centroid differently. (WGSL `round` breaks halfway cases to even, JS breaks
+ * them upward; on grid-aligned content that is a real difference.)
+ *
+ * @param {{name: string, count: number}} test_case
+ * @param {{bounds: Float32Array, payload: Uint32Array}} input
+ * @param {Uint32Array} tree the whole node buffer, as words
+ * @param {Uint32Array} sorted_keys
+ * @param {Uint32Array} sorted_values
+ * @returns {{problems: string[], warnings: string[], depth_histogram: number[], max_depth: number, sah: number, cpu_sah: number}}
+ */
+function check(test_case, input, tree, sorted_keys, sorted_values) {
+    const count = test_case.count;
+
+    const result = check_bvh_structure(tree, count, input.payload);
+
+    // normalised by the checker — a readback of a `WebGPUArray` is a plain JS Array, not a
+    // typed one, so `tree` is not something a Float32Array view can be built from
+    const { problems, words, floats } = result;
+
+    // ---- the sorted order the tree was built from ----
+
+    const seen = new Uint8Array(count);
+
+    for (let i = 0; i < count; i++) {
+        const value = sorted_values[i];
+
+        if (value >= count || seen[value] === 1) {
+            problems.push(`the Morton order is not a permutation at [${i}]: ${value}`);
+            break;
+        }
+
+        seen[value] = 1;
+
+        if (i > 0 && sorted_keys[i] < sorted_keys[i - 1]) {
+            problems.push(`Morton keys are not ascending at [${i}]`);
+            break;
+        }
+    }
+
+    // ---- topology against the CPU oracle, fed the SAME sorted order ----
+
+    let cpu_sah = 0;
+
+    if (problems.length === 0) {
+        const bvh = new BVH();
+
+        const leaf_nodes = new Uint32Array(count);
+        const internal_nodes = new Uint32Array(Math.max(1, count - 1));
+
+        for (let i = 0; i < count; i++) {
+            const source = sorted_values[i];
+
+            const node = bvh.allocate_node();
+
+            bvh.node_set_aabb(node, input.bounds.subarray(source * 6, source * 6 + 6));
+            bvh.node_set_user_data(node, input.payload[source]);
+
+            leaf_nodes[i] = node;
+        }
+
+        for (let k = 0; k < count - 1; k++) {
+            internal_nodes[k] = bvh.allocate_node();
+        }
+
+        const cpu_root = ebvh_build_hierarchy_radix(bvh, leaf_nodes, sorted_keys, count, internal_nodes);
+
+        // cpu leaf i <-> gpu node (n-1)+i, cpu internal k <-> gpu node k
+        const to_gpu = new Map();
+        for (let i = 0; i < count; i++) {
+            to_gpu.set(leaf_nodes[i], (count - 1) + i);
+        }
+        for (let k = 0; k < count - 1; k++) {
+            to_gpu.set(internal_nodes[k], k);
+        }
+
+        if (to_gpu.get(cpu_root) !== words[0]) {
+            problems.push(`the CPU oracle's root maps to node ${to_gpu.get(cpu_root)}, the GPU wrote ${words[0]}`);
+        }
+
+        const cpu_bounds = new Float32Array(6);
+
+        for (let k = 0; k < count - 1; k++) {
+            const cpu_node = internal_nodes[k];
+
+            const gpu = read_bvh_node(words, floats, k);
+
+            const expected_1 = to_gpu.get(bvh.node_get_child1(cpu_node));
+            const expected_2 = to_gpu.get(bvh.node_get_child2(cpu_node));
+
+            if (gpu.child_1 !== expected_1 || gpu.child_2 !== expected_2) {
+                problems.push(
+                    `topology differs at internal node ${k}: GPU (${gpu.child_1}, ${gpu.child_2}), `
+                    + `CPU (${expected_1}, ${expected_2})`
+                );
+                break;
+            }
+
+            bvh.node_get_aabb(cpu_node, cpu_bounds);
+
+            cpu_sah += surface_area(
+                [cpu_bounds[0], cpu_bounds[1], cpu_bounds[2]],
+                [cpu_bounds[3], cpu_bounds[4], cpu_bounds[5]]
+            );
+
+            for (let axis = 0; axis < 3; axis++) {
+                if (Math.abs(cpu_bounds[axis] - gpu.low[axis]) > 1e-4
+                    || Math.abs(cpu_bounds[3 + axis] - gpu.high[axis]) > 1e-4) {
+                    problems.push(
+                        `refit differs at internal node ${k}, axis ${axis}: `
+                        + `GPU [${gpu.low[axis]}, ${gpu.high[axis]}], CPU [${cpu_bounds[axis]}, ${cpu_bounds[3 + axis]}]`
+                    );
+                    break;
+                }
+            }
+        }
+    }
+
+    return { ...result, cpu_sah };
+}
+
+/**
+ * On-device verification of the GPU BVH build.
+ *
+ * Builds a tree for each of a set of leaf sets chosen for the shapes that break LBVH builders —
+ * coincident instances, tight clusters that quantise to one Morton code, degenerate zero-volume
+ * boxes, and counts either side of every tile and workgroup boundary — reads the result back, and
+ * checks on the CPU that:
+ *
+ *   - the root word is what the format says it is,
+ *   - every node is reachable exactly once (a shared node is the classic duplicate-key failure),
+ *   - every leaf carries its own payload and every payload appears once,
+ *   - every internal node's box contains both of its children's,
+ *   - the Morton order is an ascending permutation,
+ *   - the topology matches `ebvh_build_hierarchy_radix` node for node, fed the GPU's OWN sorted
+ *     order so the comparison tests emission rather than float rounding in the quantiser,
+ *   - the refit's internal bounds match the CPU's.
+ *
+ * And it reports what the risk register asks to be measured rather than assumed: the depth
+ * histogram against the shared traversal stack, and the SAH cost of the tree.
+ *
+ * Per-pass GPU timings go to the console for the largest case, through the debug-timers path —
+ * the `timer` argument `graph_compute_pass` forwards is silently dropped by
+ * `ComputeShader.dispatch`, so this is the path that actually reports anything.
+ *
+ * One graph and one submission per case: the transients then come and go with each build instead
+ * of all being alive at once, and each case gets a fresh set of timer query slots.
+ *
+ * @param {GraphicsContext} graphics
+ */
+export function verify_gpu_bvh_build(graphics) {
+
+    for (const test_case of cases()) {
+        run_case(graphics, test_case);
+    }
+}
+
+/**
+ * Build, read back and check one leaf set.
+ *
+ * @param {GraphicsContext} graphics
+ * @param {{name: string, count: number, make: function}} test_case
+ */
+function run_case(graphics, test_case) {
+
+    const graph = new FrameGraph(`verify gpu bvh build/${test_case.name}`);
+
+    const cmd = ShadeGPUCommandContext.create(graphics, `verify/gpu bvh build/${test_case.name}`);
+
+    // Only the large case: the number worth having is the build time at scale, and a table per
+    // case would bury it.
+    if (test_case.count >= 100000) {
+        cmd.enable_debug_timers(table => {
+            console.log(`[BVH] GPU timings — ${test_case.name}`);
+            console.table(table);
+        });
+    }
+
+    const storage_usage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC;
+
+    {
+        const { count } = test_case;
+
+        const input = build_input(test_case);
+
+        const bounds_type = WebGPUArray.from(f32, count * 6);
+        const payload_type = WebGPUArray.from(u32, count);
+        const scene_type = WebGPUArray.from(f32, 6);
+
+        const leaf_bounds = graph_import_typed_buffer({
+            graph, type: bounds_type, value: input.bounds,
+            label: `verify bvh bounds ${test_case.name}`, usage: storage_usage
+        });
+
+        const leaf_payload = graph_import_typed_buffer({
+            graph, type: payload_type, value: input.payload,
+            label: `verify bvh payload ${test_case.name}`, usage: storage_usage
+        });
+
+        const scene_bounds = graph_import_typed_buffer({
+            graph, type: scene_type, value: input.scene,
+            label: `verify bvh scene bounds ${test_case.name}`, usage: storage_usage
+        });
+
+        const word_count = bvh_buffer_size(count) / Uint32Array.BYTES_PER_ELEMENT;
+
+        const nodes = graph_import_typed_buffer({
+            graph,
+            type: WebGPUArray.from(u32, word_count),
+            value: new Uint32Array(word_count),
+            label: `verify bvh nodes ${test_case.name}`,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+        });
+
+        const built = graph_bvh_build_lbvh({
+            graph, leaf_bounds, leaf_payload, scene_bounds, element_count: count, nodes,
+        });
+
+        /** @type {Uint32Array|undefined} */
+        let tree;
+        /** @type {Uint32Array|undefined} */
+        let keys;
+        /** @type {Uint32Array|undefined} */
+        let values;
+
+        function validate() {
+            if (tree === undefined || keys === undefined || values === undefined) {
+                // wait for all three readbacks
+                return;
+            }
+
+            const result = check(test_case, input, tree, keys, values);
+
+            const depth_summary = format_depth_histogram(result.depth_histogram);
+
+            const headline = `${test_case.name} — max depth ${result.max_depth}/${TRAVERSAL_STACK_SIZE}, `
+                + `SAH ${result.sah.toFixed(1)} (CPU oracle ${result.cpu_sah.toFixed(1)})`;
+
+            if (result.problems.length === 0) {
+                console.log(`%c[BVH] PASS ${headline}`, 'color: #0c0');
+            } else {
+                console.error(`[BVH] FAIL ${headline}\n  ${result.problems.join('\n  ')}`);
+            }
+
+            console.log(`       depth histogram (depth:leaves) ${depth_summary}`);
+
+            for (const warning of result.warnings) {
+                console.warn(`[BVH] ${test_case.name}: ${warning}`);
+            }
+        }
+
+        graph_inspect_gpu_buffer({
+            graph, type: WebGPUArray.from(u32, word_count), buffer: built.nodes,
+            callback([data]) {
+                tree = data;
+                validate();
+            }
+        });
+
+        graph_inspect_gpu_buffer({
+            graph, type: payload_type, buffer: built.keys, count: 1,
+            callback([data]) {
+                keys = data;
+                validate();
+            }
+        });
+
+        graph_inspect_gpu_buffer({
+            graph, type: payload_type, buffer: built.values, count: 1,
+            callback([data]) {
+                values = data;
+                validate();
+            }
+        });
+    }
+
+    cmd.encodeGraph(graph);
+    cmd.finish();
+}

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test_prefix_sum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.js"],"names":[],"mappings":"AA2BA;;;GAGG;AACH,0EA+DC"}
+{"version":3,"file":"test_prefix_sum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.js"],"names":[],"mappings":"AA2BA;;;GAGG;AACH,0EA8DC"}

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.js

@@ -58,8 +58,7 @@ export async function test_prefix_sum(graphics) {
     const prefix_sum = graph_prefix_scan_csdldf({
         graph,
         data,
-        timer,
-        element_count: input.length,
+        element_max_count: input.length,
     });
 
     graph_inspect_gpu_buffer({

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

@@ -0,0 +1,9 @@
+/**
+ * Per-digit-pass constants, shared by the histogram and the scatter so the two agree on which keys
+ * exist and where their counts live in the spine.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_PASS_SETTINGS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=SORT_PASS_SETTINGS_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SORT_PASS_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/SORT_PASS_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,YAAY,CAeC;6BArBM,mCAAmC"}

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

@@ -0,0 +1,23 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Per-digit-pass constants, shared by the histogram and the scatter so the two agree on which keys
+ * exist and where their counts live in the spine.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_PASS_SETTINGS_STRUCT = WebGPUStruct.from({
+    /**
+     * Bit position of the digit this pass sorts on — 0, 8, 16, 24.
+     */
+    shift: u32,
+    /**
+     * Keys in the input. The tail tile is partial and every read is bounds-checked against this.
+     */
+    element_count: u32,
+    /**
+     * Number of tiles, which is the stride between adjacent bins in the bin-major spine.
+     */
+    tile_count: u32,
+}, "SortPassSettings");

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

@@ -0,0 +1,18 @@
+/**
+ * The two pure index computations the sort's three stages have to agree on, kept out of the
+ * shaders so the emulator tier can execute them directly against a CPU statement of the same
+ * arithmetic.
+ *
+ * `sort_extract_digit` is the digit selector: `shift` is 0, 8, 16, 24 across the four passes.
+ *
+ * `sort_spine_index` is the flattening. The spine holds one 256-bin histogram per tile, laid out
+ * **bin-major** — every tile's count for bin 0, then every tile's count for bin 1, and so on — so
+ * that a single running scan across it yields, at `(bin, tile)`, the number of keys that precede
+ * this tile's bin-`bin` run in the final ordering. A tile-major layout would need a second scan
+ * over the per-bin totals. {@link SPINE_HEADER_WORDS} steps over the scan's `count` header.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_digit: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sort_digit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sort_digit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/chunk_sort_digit.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,+BAFU,SAAS,CAehB;0BA/BuB,oCAAoC"}

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

@@ -0,0 +1,32 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { RADIX, SPINE_HEADER_WORDS } from "./defs.js";
+
+/**
+ * The two pure index computations the sort's three stages have to agree on, kept out of the
+ * shaders so the emulator tier can execute them directly against a CPU statement of the same
+ * arithmetic.
+ *
+ * `sort_extract_digit` is the digit selector: `shift` is 0, 8, 16, 24 across the four passes.
+ *
+ * `sort_spine_index` is the flattening. The spine holds one 256-bin histogram per tile, laid out
+ * **bin-major** — every tile's count for bin 0, then every tile's count for bin 1, and so on — so
+ * that a single running scan across it yields, at `(bin, tile)`, the number of keys that precede
+ * this tile's bin-`bin` run in the final ordering. A tile-major layout would need a second scan
+ * over the per-bin totals. {@link SPINE_HEADER_WORDS} steps over the scan's `count` header.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_digit = CodeChunk.from(
+    //language=WGSL
+    `
+const SORT_RADIX_MASK = ${RADIX - 1}u;
+const SORT_SPINE_HEADER_WORDS = ${SPINE_HEADER_WORDS}u;
+
+fn sort_extract_digit(key: u32, shift: u32) -> u32 {
+    return (key >> shift) & SORT_RADIX_MASK;
+}
+
+fn sort_spine_index(bin: u32, tile: u32, tile_count: u32) -> u32 {
+    return SORT_SPINE_HEADER_WORDS + bin * tile_count + tile;
+}
+`);

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

@@ -0,0 +1,27 @@
+/**
+ * The scatter's two pieces of rank arithmetic, isolated as pure functions so the emulator tier can
+ * execute them against a CPU statement of the same rule rather than only reading them.
+ *
+ * `sort_split_destination` is one round of the stable binary split the scatter runs
+ * `RADIX_LOG` times to order a tile by the current digit. Zeroes keep the front of the tile in
+ * their original relative order, ones follow them in theirs — which is what makes the whole sort
+ * stable, and what an LSD radix sort's correctness rests on.
+ *
+ * `sort_scatter_base` turns the spine's **inclusive** running total for `(bin, tile)` into the
+ * device address that this tile's bin-`bin` run starts at, biased so that a key's sorted position
+ * within the tile can simply be added to it:
+ *
+ *   - `spine_inclusive - local_count` is the number of keys that precede this tile's run — the
+ *     scan is inclusive-only, so the exclusive value is recovered by subtracting the tile's own
+ *     count rather than by keeping a pre-scan copy of it;
+ *   - `- bin_start` cancels the offset the run already carries inside the sorted tile.
+ *
+ * Never underflows: `spine_inclusive` counts every key in every earlier bin (of which this tile's
+ * share is exactly `bin_start`) plus every key of this bin up to and including this tile (of which
+ * this tile's share is exactly `local_count`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_rank: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sort_rank.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sort_rank.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/chunk_sort_rank.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAFU,SAAS,CAgBhB;0BAxCuB,oCAAoC"}

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

@@ -0,0 +1,41 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * The scatter's two pieces of rank arithmetic, isolated as pure functions so the emulator tier can
+ * execute them against a CPU statement of the same rule rather than only reading them.
+ *
+ * `sort_split_destination` is one round of the stable binary split the scatter runs
+ * `RADIX_LOG` times to order a tile by the current digit. Zeroes keep the front of the tile in
+ * their original relative order, ones follow them in theirs — which is what makes the whole sort
+ * stable, and what an LSD radix sort's correctness rests on.
+ *
+ * `sort_scatter_base` turns the spine's **inclusive** running total for `(bin, tile)` into the
+ * device address that this tile's bin-`bin` run starts at, biased so that a key's sorted position
+ * within the tile can simply be added to it:
+ *
+ *   - `spine_inclusive - local_count` is the number of keys that precede this tile's run — the
+ *     scan is inclusive-only, so the exclusive value is recovered by subtracting the tile's own
+ *     count rather than by keeping a pre-scan copy of it;
+ *   - `- bin_start` cancels the offset the run already carries inside the sorted tile.
+ *
+ * Never underflows: `spine_inclusive` counts every key in every earlier bin (of which this tile's
+ * share is exactly `bin_start`) plus every key of this bin up to and including this tile (of which
+ * this tile's share is exactly `local_count`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_rank = CodeChunk.from(
+    //language=WGSL
+    `
+fn sort_split_destination(is_one: bool, zeros_before: u32, ones_before: u32, total_zeros: u32) -> u32 {
+    if (is_one) {
+        return total_zeros + ones_before;
+    }
+
+    return zeros_before;
+}
+
+fn sort_scatter_base(spine_inclusive: u32, local_count: u32, bin_start: u32) -> u32 {
+    return spine_inclusive - local_count - bin_start;
+}
+`);

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

@@ -0,0 +1,25 @@
+/**
+ * Workgroup-wide exclusive scan of one `u32` per thread, returning
+ * `vec2(exclusive_prefix, workgroup_total)`.
+ *
+ * Two levels: `subgroupInclusiveAdd` inside each subgroup, then a Hillis–Steele scan over the
+ * per-subgroup totals in workgroup memory. Subgroup ops carry the wide part of the work; workgroup
+ * memory is the correctness layer across subgroup boundaries, because subgroup size is a runtime
+ * value in [4, 128] and nothing here may assume one.
+ *
+ * The Hillis–Steele loop's trip count is the **constant** `MAX_SUBGROUPS_PER_WORKGROUP` rather than
+ * the real subgroup count. It contains `workgroupBarrier`, and a barrier under a bound derived from
+ * `subgroup_size` is precisely the shape a uniformity analysis is entitled to reject; iterations
+ * past the real subgroup count find `active` false and write nothing. The per-iteration
+ * read-barrier-write split is what keeps a thread from overwriting a value another thread has yet
+ * to read.
+ *
+ * Callers must invoke this from workgroup-uniform control flow — subgroup builtins require it, and
+ * so do the barriers. The barrier at the top is what lets a caller invoke it repeatedly: it fences
+ * the previous call's reads of `wg_sort_partials` against this call's writes.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_workgroup_scan: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sort_workgroup_scan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sort_workgroup_scan.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/chunk_sort_workgroup_scan.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wCAFU,SAAS,CAkDhB;0BAzEuB,oCAAoC"}