@woosh/meep-engine 3.3.0 → 3.4.0

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

@@ -0,0 +1,74 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { MAX_SUBGROUPS_PER_WORKGROUP, SORT_WORKGROUP_SIZE } from "./defs.js";
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+var<workgroup> wg_sort_partials: array<u32, ${MAX_SUBGROUPS_PER_WORKGROUP}>;
+
+fn sort_workgroup_exclusive_scan(
+    value: u32,
+    thread_id: u32,
+    lane_id: u32,
+    lane_count: u32
+) -> vec2<u32> {
+    let subgroup_id = thread_id / lane_count;
+    let subgroup_count = ${SORT_WORKGROUP_SIZE}u / lane_count;
+
+    let inclusive = subgroupInclusiveAdd(value);
+
+    workgroupBarrier();
+
+    if (lane_id == lane_count - 1u) {
+        wg_sort_partials[subgroup_id] = inclusive;
+    }
+
+    workgroupBarrier();
+
+    for (var offset = 1u; offset < ${MAX_SUBGROUPS_PER_WORKGROUP}u; offset <<= 1u) {
+        let contributes = thread_id < subgroup_count && thread_id >= offset;
+
+        var carry = 0u;
+        if (contributes) {
+            carry = wg_sort_partials[thread_id - offset];
+        }
+
+        workgroupBarrier();
+
+        if (contributes) {
+            wg_sort_partials[thread_id] += carry;
+        }
+
+        workgroupBarrier();
+    }
+
+    var subgroup_prefix = 0u;
+    if (subgroup_id != 0u) {
+        subgroup_prefix = wg_sort_partials[subgroup_id - 1u];
+    }
+
+    return vec2<u32>(inclusive - value + subgroup_prefix, wg_sort_partials[subgroup_count - 1u]);
+}
+`);

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

@@ -0,0 +1,71 @@
+/**
+ * Shared configuration for the key-value radix sort.
+ *
+ * The sort is LSD reduce-then-scan: four 8-bit digit passes, each of them a per-tile histogram,
+ * a spine scan through {@link graph_prefix_scan_csdldf}, and a rank-and-scatter. The numbers below
+ * are what the three stages have to agree on, so they live in one place rather than in each
+ * shader's template literal.
+ */
+/**
+ * Number of digit bins. 8-bit digits — one `u32` key is covered by {@link RADIX_PASSES} of them.
+ * @type {number}
+ */
+export const RADIX: number;
+/**
+ * `log2(RADIX)` — also the number of binary split rounds the scatter's in-tile sort runs.
+ * @type {number}
+ */
+export const RADIX_LOG: number;
+/**
+ * (key width) / RADIX_LOG. Four passes over a 32-bit key.
+ *
+ * Even, which is what puts the result back in the caller's buffers rather than in the ping-pong
+ * scratch — see {@link graph_radix_sort}.
+ * @type {number}
+ */
+export const RADIX_PASSES: number;
+/**
+ * Threads per workgroup, in both the histogram and the scatter.
+ *
+ * 256 is `maxComputeInvocationsPerWorkgroup`'s default value, and it is also exactly {@link RADIX},
+ * which is what lets the scatter run "one thread per bin" over its local histogram with no strided
+ * loop.
+ * @type {number}
+ */
+export const SORT_WORKGROUP_SIZE: number;
+/**
+ * Keys each thread carries through a tile.
+ * @type {number}
+ */
+export const SORT_KEYS_PER_THREAD: number;
+/**
+ * Keys one workgroup processes. Also the granularity of the spine: the spine holds one 256-bin
+ * histogram per tile.
+ * @type {number}
+ */
+export const SORT_TILE_SIZE: number;
+/**
+ * The smallest subgroup size WebGPU permits, and therefore the largest number of subgroups a
+ * workgroup can be split into: `SORT_WORKGROUP_SIZE / MIN_SUBGROUP_SIZE`.
+ *
+ * Subgroup size is a runtime value in [4, 128]; nothing here may bake a width in. What the bound
+ * buys is a *compile-time* trip count for the loop that scans the per-subgroup partials — a loop
+ * that contains barriers, and whose bound therefore has to be provably uniform. Iterations past
+ * the real subgroup count do nothing.
+ * @type {number}
+ */
+export const MIN_SUBGROUP_SIZE: number;
+/**
+ * @type {number}
+ */
+export const MAX_SUBGROUPS_PER_WORKGROUP: number;
+/**
+ * Words of `{count: u32, elements: array<vec4u>}` header that sit in front of the spine's elements.
+ *
+ * {@link graph_prefix_scan_csdldf} reads its element count from word 0 and its `elements` member is
+ * `@align(16)`, so the first count word lives at word 4. The histogram and scatter shaders bind the
+ * same buffer flat and have to step over the header by hand.
+ * @type {number}
+ */
+export const SPINE_HEADER_WORDS: number;
+//# sourceMappingURL=defs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defs.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/defs.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,oBAFU,MAAM,CAES;AAEzB;;;GAGG;AACH,wBAFU,MAAM,CAEW;AAE3B;;;;;;GAMG;AACH,2BAFU,MAAM,CAEc;AAE9B;;;;;;;GAOG;AACH,kCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;GAIG;AACH,6BAFU,MAAM,CAEyD;AAEzE;;;;;;;;;GASG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;GAEG;AACH,0CAFU,MAAM,CAEmE;AAEnF;;;;;;;GAOG;AACH,iCAFU,MAAM,CAEoB"}

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

@@ -0,0 +1,79 @@
+/**
+ * Shared configuration for the key-value radix sort.
+ *
+ * The sort is LSD reduce-then-scan: four 8-bit digit passes, each of them a per-tile histogram,
+ * a spine scan through {@link graph_prefix_scan_csdldf}, and a rank-and-scatter. The numbers below
+ * are what the three stages have to agree on, so they live in one place rather than in each
+ * shader's template literal.
+ */
+
+/**
+ * Number of digit bins. 8-bit digits — one `u32` key is covered by {@link RADIX_PASSES} of them.
+ * @type {number}
+ */
+export const RADIX = 256;
+
+/**
+ * `log2(RADIX)` — also the number of binary split rounds the scatter's in-tile sort runs.
+ * @type {number}
+ */
+export const RADIX_LOG = 8;
+
+/**
+ * (key width) / RADIX_LOG. Four passes over a 32-bit key.
+ *
+ * Even, which is what puts the result back in the caller's buffers rather than in the ping-pong
+ * scratch — see {@link graph_radix_sort}.
+ * @type {number}
+ */
+export const RADIX_PASSES = 4;
+
+/**
+ * Threads per workgroup, in both the histogram and the scatter.
+ *
+ * 256 is `maxComputeInvocationsPerWorkgroup`'s default value, and it is also exactly {@link RADIX},
+ * which is what lets the scatter run "one thread per bin" over its local histogram with no strided
+ * loop.
+ * @type {number}
+ */
+export const SORT_WORKGROUP_SIZE = 256;
+
+/**
+ * Keys each thread carries through a tile.
+ * @type {number}
+ */
+export const SORT_KEYS_PER_THREAD = 4;
+
+/**
+ * Keys one workgroup processes. Also the granularity of the spine: the spine holds one 256-bin
+ * histogram per tile.
+ * @type {number}
+ */
+export const SORT_TILE_SIZE = SORT_WORKGROUP_SIZE * SORT_KEYS_PER_THREAD;
+
+/**
+ * The smallest subgroup size WebGPU permits, and therefore the largest number of subgroups a
+ * workgroup can be split into: `SORT_WORKGROUP_SIZE / MIN_SUBGROUP_SIZE`.
+ *
+ * Subgroup size is a runtime value in [4, 128]; nothing here may bake a width in. What the bound
+ * buys is a *compile-time* trip count for the loop that scans the per-subgroup partials — a loop
+ * that contains barriers, and whose bound therefore has to be provably uniform. Iterations past
+ * the real subgroup count do nothing.
+ * @type {number}
+ */
+export const MIN_SUBGROUP_SIZE = 4;
+
+/**
+ * @type {number}
+ */
+export const MAX_SUBGROUPS_PER_WORKGROUP = SORT_WORKGROUP_SIZE / MIN_SUBGROUP_SIZE;
+
+/**
+ * Words of `{count: u32, elements: array<vec4u>}` header that sit in front of the spine's elements.
+ *
+ * {@link graph_prefix_scan_csdldf} reads its element count from word 0 and its `elements` member is
+ * `@align(16)`, so the first count word lives at word 4. The histogram and scatter shaders bind the
+ * same buffer flat and have to step over the header by hand.
+ * @type {number}
+ */
+export const SPINE_HEADER_WORDS = 4;

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

@@ -0,0 +1,37 @@
+/**
+ * Key-value LSD radix sort, reduce-then-scan, built on the CSDLDF spine.
+ *
+ * Keys are 32-bit unsigned integers, values are 32-bit unsigned integers, sorting is always
+ * ASCENDING and STABLE — equal keys come out in their input order, which is what an LSD radix sort
+ * needs of each of its own digit passes and what a caller sorting Morton codes needs of the whole
+ * thing. The result lands back in the caller's own buffers: four digit passes ping-pong between
+ * them and a pair of transients, and four is even.
+ *
+ * One digit pass is three dispatches:
+ *
+ *   1. {@link shader_radix_sort_histogram} — a 256-bin histogram per tile, written into the spine
+ *      bin-major;
+ *   2. {@link graph_prefix_scan_csdldf}, reused as-is — one running scan over the whole spine
+ *      therefore yields the global start of every digit and the per-tile offset within it together.
+ *      That scan is inclusive-only and in-place, so the scatter recovers the exclusive value by
+ *      subtracting the tile's own count (which it has, having re-derived the tile histogram to rank
+ *      its keys anyway);
+ *   3. {@link shader_radix_sort_scatter} — rank within the tile, then scatter.
+ *
+ * Twelve dispatches per sort, against the seven of the single-pass one-sweep formulation that
+ * commit `b6049214c` removed. What that buys is the absence of any unbounded cross-workgroup wait:
+ * the only spin anywhere is CSDLDF's own bounded-spin-then-fallback, so the sort makes progress on
+ * a scheduler that offers no fairness guarantee at all. The single-pass upgrade is recorded in
+ * `GPU_BVH_BUILD_PLAN.md` §4.2.1 as v2, gated on a measurement from a real consumer.
+ *
+ * @param {FrameGraph} graph
+ * @param {number} keys buffer resource ID, `array<u32>`, at least `element_count` entries
+ * @param {number} values buffer resource ID, `array<u32>`, at least `element_count` entries
+ * @param {number} element_count number of input elements
+ * @returns {{keys:number, values:number}} sorted output, in the caller's buffers
+ */
+export function graph_radix_sort({ graph, keys, values, element_count, }: FrameGraph): {
+    keys: number;
+    values: number;
+};
+//# sourceMappingURL=graph_radix_sort.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_radix_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/graph_radix_sort.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,uFAFa;IAAC,IAAI,EAAC,MAAM,CAAC;IAAC,MAAM,EAAC,MAAM,CAAA;CAAC,CA4JxC"}

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

@@ -0,0 +1,197 @@
+import { assert } from "../../../../core/assert.js";
+import { round_up } from "../../../../core/math/round_up.js";
+import { warn_limited } from "../../../util/warn_limited.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { graph_prefix_scan_csdldf } from "../prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { RADIX, RADIX_LOG, RADIX_PASSES, SORT_TILE_SIZE, SPINE_HEADER_WORDS } from "./defs.js";
+import { SORT_PASS_SETTINGS_STRUCT } from "./SORT_PASS_SETTINGS_STRUCT.js";
+import { shader_radix_sort_histogram } from "./shader_radix_sort_histogram.js";
+import { shader_radix_sort_scatter } from "./shader_radix_sort_scatter.js";
+
+/**
+ * Key-value LSD radix sort, reduce-then-scan, built on the CSDLDF spine.
+ *
+ * Keys are 32-bit unsigned integers, values are 32-bit unsigned integers, sorting is always
+ * ASCENDING and STABLE — equal keys come out in their input order, which is what an LSD radix sort
+ * needs of each of its own digit passes and what a caller sorting Morton codes needs of the whole
+ * thing. The result lands back in the caller's own buffers: four digit passes ping-pong between
+ * them and a pair of transients, and four is even.
+ *
+ * One digit pass is three dispatches:
+ *
+ *   1. {@link shader_radix_sort_histogram} — a 256-bin histogram per tile, written into the spine
+ *      bin-major;
+ *   2. {@link graph_prefix_scan_csdldf}, reused as-is — one running scan over the whole spine
+ *      therefore yields the global start of every digit and the per-tile offset within it together.
+ *      That scan is inclusive-only and in-place, so the scatter recovers the exclusive value by
+ *      subtracting the tile's own count (which it has, having re-derived the tile histogram to rank
+ *      its keys anyway);
+ *   3. {@link shader_radix_sort_scatter} — rank within the tile, then scatter.
+ *
+ * Twelve dispatches per sort, against the seven of the single-pass one-sweep formulation that
+ * commit `b6049214c` removed. What that buys is the absence of any unbounded cross-workgroup wait:
+ * the only spin anywhere is CSDLDF's own bounded-spin-then-fallback, so the sort makes progress on
+ * a scheduler that offers no fairness guarantee at all. The single-pass upgrade is recorded in
+ * `GPU_BVH_BUILD_PLAN.md` §4.2.1 as v2, gated on a measurement from a real consumer.
+ *
+ * @param {FrameGraph} graph
+ * @param {number} keys buffer resource ID, `array<u32>`, at least `element_count` entries
+ * @param {number} values buffer resource ID, `array<u32>`, at least `element_count` entries
+ * @param {number} element_count number of input elements
+ * @returns {{keys:number, values:number}} sorted output, in the caller's buffers
+ */
+export function graph_radix_sort({
+                                     graph,
+                                     keys,
+                                     values,
+                                     element_count,
+                                 }) {
+
+    assert.defined(graph, 'graph');
+    assert.isNonNegativeInteger(keys, 'keys');
+    assert.isNonNegativeInteger(values, 'values');
+    assert.isNonNegativeInteger(element_count, 'element_count');
+
+    if (element_count <= 1) {
+        // nothing a sort could change
+        return { keys, values };
+    }
+
+    const tile_count = Math.ceil(element_count / SORT_TILE_SIZE);
+
+    const spine_element_count = tile_count * RADIX;
+    const spine_size = (SPINE_HEADER_WORDS + spine_element_count) * Uint32Array.BYTES_PER_ELEMENT;
+
+    // The histogram writes every element cell, but the `{count, elements}` header's padding words
+    // and any tail the round-up leaves are never written and would otherwise carry whatever the
+    // pool last put there into the scan.
+    const SPINE_DESCRIPTOR = BufferResourceDescriptor.from(
+        spine_size,
+        GPUBufferUsage.STORAGE,
+        0, spine_size
+    );
+
+    // aligned on a 1k boundary to lower memory fragmentation, as the deleted port did
+    const PING_PONG_DESCRIPTOR = BufferResourceDescriptor.from(
+        round_up(element_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
+        GPUBufferUsage.STORAGE
+    );
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_histogram(pass_data, resources, context) {
+        const encoder = context.encoder;
+
+        const MAX_DISPATCH_SIZE = encoder.device.limits.maxComputeWorkgroupsPerDimension;
+
+        if (tile_count > MAX_DISPATCH_SIZE) {
+            warn_limited(`radix sort: tile_count(=${tile_count}) > MAX_DISPATCH_SIZE(=${MAX_DISPATCH_SIZE}). Sort will be incomplete`);
+        }
+
+        shader_radix_sort_histogram.dispatch({
+            encoder,
+            group_count_x: tile_count,
+            bindings: {
+                settings: encoder.allocateTransientValueBuffer(SORT_PASS_SETTINGS_STRUCT, {
+                    shift: pass_data.shift,
+                    element_count,
+                    tile_count,
+                }),
+                keys: resources.get(pass_data.keys),
+                spine: resources.get(pass_data.spine),
+            }
+        });
+    }
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_scatter(pass_data, resources, context) {
+        const encoder = context.encoder;
+
+        const in_keys = resources.get(pass_data.in_keys);
+        const in_values = resources.get(pass_data.in_values);
+        const out_keys = resources.get(pass_data.out_keys);
+        const out_values = resources.get(pass_data.out_values);
+
+        const required = element_count * Uint32Array.BYTES_PER_ELEMENT;
+
+        assert.greaterThanOrEqual(in_keys.size, required, 'key buffer underflow');
+        assert.greaterThanOrEqual(in_values.size, required, 'value buffer underflow');
+        assert.greaterThanOrEqual(out_keys.size, required, 'key output buffer underflow');
+        assert.greaterThanOrEqual(out_values.size, required, 'value output buffer underflow');
+
+        shader_radix_sort_scatter.dispatch({
+            encoder,
+            group_count_x: tile_count,
+            bindings: {
+                settings: encoder.allocateTransientValueBuffer(SORT_PASS_SETTINGS_STRUCT, {
+                    shift: pass_data.shift,
+                    element_count,
+                    tile_count,
+                }),
+                in_keys,
+                in_values,
+                out_keys,
+                out_values,
+                spine: resources.get(pass_data.spine),
+            }
+        });
+    }
+
+    let read_keys = keys;
+    let read_values = values;
+
+    // the ping-pong halves, created by the first scatter and then alternated into
+    let write_keys;
+    let write_values;
+
+    for (let pass_index = 0; pass_index < RADIX_PASSES; pass_index++) {
+
+        const shift = pass_index * RADIX_LOG;
+
+        const histogram_data = { shift };
+        const histogram_pass = graph.add(`radix sort/histogram ${pass_index}`, histogram_data, execute_histogram);
+
+        histogram_data.keys = histogram_pass.read(read_keys);
+        histogram_data.spine = histogram_pass.create(`radix sort/spine ${pass_index}`, SPINE_DESCRIPTOR);
+
+        const scanned_spine = graph_prefix_scan_csdldf({
+            graph,
+            data: histogram_data.spine,
+            element_max_count: spine_element_count,
+        });
+
+        const scatter_data = { shift };
+        const scatter_pass = graph.add(`radix sort/scatter ${pass_index}`, scatter_data, execute_scatter);
+
+        scatter_data.in_keys = scatter_pass.read(read_keys);
+        scatter_data.in_values = scatter_pass.read(read_values);
+        scatter_data.spine = scatter_pass.read(scanned_spine);
+
+        if (write_keys === undefined) {
+            write_keys = scatter_pass.create("radix sort/ping-pong keys", PING_PONG_DESCRIPTOR);
+            write_values = scatter_pass.create("radix sort/ping-pong values", PING_PONG_DESCRIPTOR);
+        } else {
+            write_keys = scatter_pass.write(write_keys);
+            write_values = scatter_pass.write(write_values);
+        }
+
+        scatter_data.out_keys = write_keys;
+        scatter_data.out_values = write_values;
+
+        // what this pass wrote is what the next one sorts
+        [read_keys, write_keys] = [write_keys, read_keys];
+        [read_values, write_values] = [write_values, read_values];
+    }
+
+    return {
+        keys: read_keys,
+        values: read_values,
+    };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Per-tile 256-bin digit histogram — stage (a) of one digit pass of {@link graph_radix_sort}.
+ *
+ * One workgroup per tile; the counts land in the spine bin-major, so that the single scan that
+ * follows produces global digit offsets and per-tile offsets in one traversal.
+ *
+ * Subgroup ballot peer-aggregation ahead of the workgroup atomics (the deleted one-sweep port's
+ * `WarpLevelMultiSplit`) is the recorded upgrade here; it is left out of v1 because this pass reads
+ * each key once and is bandwidth-shaped, while the machinery it needs is the widest part of the
+ * subgroup-size surface.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_radix_sort_histogram: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_radix_sort_histogram.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_radix_sort_histogram.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/shader_radix_sort_histogram.js"],"names":[],"mappings":"AAkEA;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAOpB;8BAjF2B,+BAA+B"}

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

@@ -0,0 +1,85 @@
+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 { RADIX, 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("keys", WebGPUArray.from(u32), false)
+    // `{count: u32, elements: array<vec4u>}` as the scan sees it, flat as this pass writes it.
+    // Every cell is produced by exactly one thread of one workgroup, so no atomics: the only
+    // consumer is a later dispatch, and WebGPU orders dispatches against each other.
+    .addStorageBuffer("spine", WebGPUArray.from(u32), true);
+
+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;
+
+// One bin per thread — RADIX and the workgroup size are equal, so the clear and the write-out are
+// both a single unstrided step.
+var<workgroup> wg_histogram: array<atomic<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>,
+) {
+    let tile = workgroup_id.x;
+
+    atomicStore(&wg_histogram[thread_id], 0u);
+
+    workgroupBarrier();
+
+    // Striped so that neighbouring threads read neighbouring addresses. The tail tile is partial;
+    // the keys past the end are not counted, which is what lets the scatter recognise them later
+    // by position alone.
+    let tile_base = tile * TILE_SIZE;
+    for (var k = 0u; k < KEYS_PER_THREAD; k += 1u) {
+        let source = tile_base + k * WORKGROUP_SIZE + thread_id;
+
+        if (source < settings.element_count) {
+            atomicAdd(&wg_histogram[sort_extract_digit(keys[source], settings.shift)], 1u);
+        }
+    }
+
+    workgroupBarrier();
+
+    spine[sort_spine_index(thread_id, tile, settings.tile_count)] = atomicLoad(&wg_histogram[thread_id]);
+
+    // The scan is indirect-dispatched off an element count it reads from word 0 of this buffer.
+    if (tile == 0u && thread_id == 0u) {
+        spine[0] = settings.tile_count * RADIX;
+    }
+}
+`, [
+    chunk_sort_digit,
+]);
+
+/**
+ * Per-tile 256-bin digit histogram — stage (a) of one digit pass of {@link graph_radix_sort}.
+ *
+ * One workgroup per tile; the counts land in the spine bin-major, so that the single scan that
+ * follows produces global digit offsets and per-tile offsets in one traversal.
+ *
+ * Subgroup ballot peer-aggregation ahead of the workgroup atomics (the deleted one-sweep port's
+ * `WarpLevelMultiSplit`) is the recorded upgrade here; it is left out of v1 because this pass reads
+ * each key once and is bandwidth-shaped, while the machinery it needs is the widest part of the
+ * subgroup-size surface.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_radix_sort_histogram = ComputeShader.from({
+    label: "RadixSort/Histogram",
+    resources,
+    body,
+    group_size: [SORT_WORKGROUP_SIZE, 1, 1],
+});

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

@@ -0,0 +1,15 @@
+/**
+ * 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;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_radix_sort_scatter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_radix_sort_scatter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/shader_radix_sort_scatter.js"],"names":[],"mappings":"AA8KA;;;;;;;;;;;GAWG;AACH,wCAFU,aAAa,CAOpB;8BA3L2B,+BAA+B"}