@woosh/meep-engine 3.59.0 → 3.60.1

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

@@ -1,8 +1,10 @@
 import { assert } from "../../../../core/assert.js";
+import { noop } from "../../../../core/function/noop.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_create_buffer } from "../../shader/graph/graph_create_buffer.js";
+import { INDIRECT_COMPUTE_COMMAND_DESCRIPTOR } from "../indirect/IndirectComputeCommandBuildPass.js";
 import {
     enquire_prefix_scan_csdldf_pipelines,
     graph_prefix_scan_csdldf,
@@ -10,14 +12,19 @@ import {
 } 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 { shader_radix_sort_histogram } from "./shader_radix_sort_histogram.js";
+import { shader_radix_sort_histogram_indirect } from "./shader_radix_sort_histogram_indirect.js";
+import { shader_radix_sort_prepare } from "./shader_radix_sort_prepare.js";
 import { shader_radix_sort_scatter } from "./shader_radix_sort_scatter.js";
+import { shader_radix_sort_scatter_indirect } from "./shader_radix_sort_scatter_indirect.js";
+import { SORT_SIZE_STRUCT } from "./SORT_SIZE_STRUCT.js";
 
 /**
  * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 
 /**
- * Offer the pipelines {@link graph_radix_sort} dispatches — see {@link PipelineEnquiry}.
+ * Offer the pipelines {@link graph_radix_sort} dispatches over a host `element_count` — see
+ * {@link PipelineEnquiry}.
  *
  * @param {PipelineEnquiry} enquiry
  */
@@ -27,16 +34,49 @@ export function enquire_radix_sort_pipelines(enquiry) {
     enquiry.compute.push(shader_radix_sort_scatter.pipeline);
 }
 
+/**
+ * Offer the pipelines {@link graph_radix_sort} dispatches over a device count, a `count_buffer` —
+ * see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_radix_sort_indirect_pipelines(enquiry) {
+    enquiry.compute.push(shader_radix_sort_prepare.pipeline);
+    enquiry.compute.push(shader_radix_sort_histogram_indirect.pipeline);
+    enquire_prefix_scan_csdldf_pipelines(enquiry);
+    enquiry.compute.push(shader_radix_sort_scatter_indirect.pipeline);
+}
+
 /**
  * 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.
+ * thing.
  *
- * One digit pass is three dispatches:
+ * **Key width.** The order is by the key's low `key_bits`, in `ceil(key_bits / 8)` digit passes from
+ * the least significant byte: a 24-bit key is three passes, a 32-bit one four. The bits above
+ * `key_bits` are ignored, not required to be zero — every pass selects its digit from the key with
+ * them cleared — and each key comes out as it went in, those bits and all.
+ *
+ * **The result is in the returned handles — use them.** The digit passes ping-pong between the
+ * caller's buffers and a pair of transients the sort creates, so an even number of passes ends in the
+ * caller's buffers and an odd number in the transients. The caller's buffers are the sort's scratch
+ * either way: from the second pass on, the entries below the sorted count hold whatever the last pass
+ * to write them left there. No buffer is written at or past the sorted count.
+ *
+ * **The count** is one of:
+ * - `element_count`, known on the host: the histogram and scatter are dispatched directly, a
+ *   workgroup a tile of keys;
+ * - a count on the device, the `u32` at byte `count_offset` of `count_buffer`, with
+ *   `element_max_count` sizing the memory — the spine, the transients, and what the caller's buffers
+ *   must hold. One thread, {@link shader_radix_sort_prepare}, reads the count and writes the command
+ *   every histogram and scatter is dispatched through, the live size they read and the spine's count
+ *   every scan is dispatched over. No work follows `element_max_count`: a count of 0 dispatches no
+ *   tile and leaves an empty result. A count above it sorts the first `element_max_count` keys.
+ *
+ * One digit pass is three stages:
  *
  *   1. {@link shader_radix_sort_histogram} — a 256-bin histogram per tile, written into the spine
  *      bin-major;
@@ -47,36 +87,211 @@ export function enquire_radix_sort_pipelines(enquiry) {
  *      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.
+ * Twelve stages for a whole 32-bit key, against the seven dispatches 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 {Object} options
  * @param {FrameGraph} options.graph
- * @param {number} options.keys buffer resource ID, `array<u32>`, at least `element_count` entries
- * @param {number} options.values buffer resource ID, `array<u32>`, at least `element_count` entries
- * @param {number} options.element_count number of input elements
- * @returns {{keys:number, values:number}} sorted output, in the caller's buffers
+ * @param {number} options.keys buffer resource ID, `array<u32>`, at least `element_count` (or
+ * `element_max_count`) entries
+ * @param {number} options.values buffer resource ID, `array<u32>`, as many entries as `keys`
+ * @param {number} [options.element_count] number of input elements, known on the host. Give this or
+ * `count_buffer`, not both
+ * @param {number} [options.count_buffer] buffer resource ID holding the number of input elements,
+ * written on the device; bound whole, read-only, so it needs `STORAGE`
+ * @param {number} [options.count_offset] with `count_buffer`: byte offset of the count, a multiple of 4
+ * @param {number} [options.element_max_count] with `count_buffer`: the most elements it can count,
+ * which sizes memory and nothing else
+ * @param {number} [options.key_bits=32] how many of the key's low bits it is sorted by, 1 to 32
+ * @returns {{keys:number, values:number}} the sorted keys and values: the caller's buffers or the
+ * sort's transients, see above
  */
 export function graph_radix_sort({
                                      graph,
                                      keys,
                                      values,
                                      element_count,
+                                     count_buffer,
+                                     count_offset,
+                                     element_max_count,
+                                     key_bits = 32,
                                  }) {
 
     assert.defined(graph, 'graph');
     assert.isNonNegativeInteger(keys, 'keys');
     assert.isNonNegativeInteger(values, 'values');
-    assert.isNonNegativeInteger(element_count, 'element_count');
+    assert.isNonNegativeInteger(key_bits, 'key_bits');
+    assert.greaterThanOrEqual(key_bits, 1, 'key_bits');
+    assert.lessThanOrEqual(key_bits, RADIX_PASSES * RADIX_LOG, 'key_bits');
+
+    const pass_count = Math.ceil(key_bits / RADIX_LOG);
+
+    // the key's low key_bits, all a digit is ever selected from: 2^32 - 1 is the whole key
+    const key_mask = 2 ** key_bits - 1;
+
+    if (count_buffer === undefined) {
+        assert.isNonNegativeInteger(element_count, 'element_count');
+        assert.equal(count_offset, undefined, 'count_offset is only read with a count_buffer');
+        assert.equal(element_max_count, undefined, 'element_max_count is only read with a count_buffer');
 
-    if (element_count <= 1) {
-        // nothing a sort could change
+        if (element_count <= 1) {
+            // nothing a sort could change
+            return { keys, values };
+        }
+
+        return record_host_count_sort({ graph, keys, values, element_count, pass_count, key_mask });
+    }
+
+    assert.equal(element_count, undefined, 'element_count is the host count; with a count_buffer the count is on the device');
+    assert.isNonNegativeInteger(count_buffer, 'count_buffer');
+    assert.isNonNegativeInteger(count_offset, 'count_offset');
+    assert.equal(count_offset % Uint32Array.BYTES_PER_ELEMENT, 0, 'count_offset must address a whole u32');
+    assert.isNonNegativeInteger(element_max_count, 'element_max_count');
+
+    if (element_max_count <= 1) {
+        // nothing a sort could change, whatever the device counted
         return { keys, values };
     }
 
+    return record_device_count_sort({
+        graph,
+        keys,
+        values,
+        count_buffer,
+        count_offset,
+        element_max_count,
+        pass_count,
+        key_mask,
+    });
+}
+
+/**
+ * Transients the digit passes ping-pong through, for up to `element_count` keys or values.
+ *
+ * @param {number} element_count
+ * @returns {BufferResourceDescriptor}
+ */
+function ping_pong_descriptor(element_count) {
+    // aligned on a 1k boundary to lower memory fragmentation, as the deleted port did
+    return BufferResourceDescriptor.from(
+        round_up(element_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
+        GPUBufferUsage.STORAGE
+    );
+}
+
+/**
+ * The digit passes, as both counts record them: histogram, scan and scatter for each 8-bit digit from
+ * the least significant, ping-ponging between the caller's pair and a pair of transients the first
+ * scatter creates. How a stage is dispatched, and what else it reads, is the count's: `declare_*` adds
+ * that to a pass, and `execute_*` dispatches it.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.keys
+ * @param {number} options.values
+ * @param {number} options.pass_count
+ * @param {number} options.spine_element_max_count cells of the largest spine a histogram writes
+ * @param {BufferResourceDescriptor} options.PING_PONG_DESCRIPTOR
+ * @param {function(Object, FramePassResources, GraphicsExecutionContext)} options.execute_histogram
+ * @param {function(FramePassBuilder, Object, number)} options.declare_histogram sets the data's `spine` to what the pass writes
+ * @param {function(Object, FramePassResources, GraphicsExecutionContext)} options.execute_scatter
+ * @param {function(FramePassBuilder, Object)} options.declare_scatter
+ * @returns {{keys:number, values:number}} what the last scatter wrote
+ */
+function record_digit_passes({
+                                 graph,
+                                 keys,
+                                 values,
+                                 pass_count,
+                                 spine_element_max_count,
+                                 PING_PONG_DESCRIPTOR,
+                                 execute_histogram,
+                                 declare_histogram,
+                                 execute_scatter,
+                                 declare_scatter,
+                             }) {
+
+    const SCANNED_SPINE_DESCRIPTOR = prefix_scan_csdldf_output_descriptor(spine_element_max_count);
+
+    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 < pass_count; 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);
+        declare_histogram(histogram_pass, histogram_data, pass_index);
+
+        const scanned_spine = graph_prefix_scan_csdldf({
+            graph,
+            input: histogram_data.spine,
+            output: graph_create_buffer(graph, `radix sort/scanned spine ${pass_index}`, SCANNED_SPINE_DESCRIPTOR),
+            element_max_count: spine_element_max_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);
+        declare_scatter(scatter_pass, scatter_data);
+
+        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,
+    };
+}
+
+/**
+ * {@link graph_radix_sort} over a count the host knows: the histogram and scatter are dispatched
+ * directly over its tiles, and each digit pass has a spine of its own.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.keys
+ * @param {number} options.values
+ * @param {number} options.element_count at least 2
+ * @param {number} options.pass_count
+ * @param {number} options.key_mask
+ * @returns {{keys:number, values:number}}
+ */
+function record_host_count_sort({
+                                    graph,
+                                    keys,
+                                    values,
+                                    element_count,
+                                    pass_count,
+                                    key_mask,
+                                }) {
+
     const tile_count = Math.ceil(element_count / SORT_TILE_SIZE);
 
     const spine_element_count = tile_count * RADIX;
@@ -91,14 +306,6 @@ export function graph_radix_sort({
         0, spine_size
     );
 
-    const SCANNED_SPINE_DESCRIPTOR = prefix_scan_csdldf_output_descriptor(spine_element_count);
-
-    // 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
@@ -121,6 +328,7 @@ export function graph_radix_sort({
                     shift: pass_data.shift,
                     element_count,
                     tile_count,
+                    key_mask,
                 },
                 keys: resources.get(pass_data.keys),
                 spine: resources.get(pass_data.spine),
@@ -128,6 +336,15 @@ export function graph_radix_sort({
         });
     }
 
+    /**
+     * @param {FramePassBuilder} pass
+     * @param {Object} pass_data
+     * @param {number} pass_index
+     */
+    function declare_histogram(pass, pass_data, pass_index) {
+        pass_data.spine = pass.create(`radix sort/spine ${pass_index}`, SPINE_DESCRIPTOR);
+    }
+
     /**
      * @param pass_data
      * @param {FramePassResources} resources
@@ -156,6 +373,7 @@ export function graph_radix_sort({
                     shift: pass_data.shift,
                     element_count,
                     tile_count,
+                    key_mask,
                 },
                 in_keys,
                 in_values,
@@ -166,55 +384,186 @@ export function graph_radix_sort({
         });
     }
 
-    let read_keys = keys;
-    let read_values = values;
+    return record_digit_passes({
+        graph,
+        keys,
+        values,
+        pass_count,
+        spine_element_max_count: spine_element_count,
+        PING_PONG_DESCRIPTOR: ping_pong_descriptor(element_count),
+        execute_histogram,
+        declare_histogram,
+        execute_scatter,
+        // reads nothing past the ping-pong and the spine every scatter reads
+        declare_scatter: noop,
+    });
+}
 
-    // the ping-pong halves, created by the first scatter and then alternated into
-    let write_keys;
-    let write_values;
+/**
+ * {@link graph_radix_sort} over a count on the device: one thread reads it, and the histogram and
+ * scatter of every digit pass are dispatched indirectly through the command it writes, over the live
+ * tiles alone. Every digit pass reuses the one spine, whose count word that thread writes.
+ *
+ * Nothing is sized by `element_max_count` but memory. The command is a buffer of its own, which no
+ * dispatch that reads it binds: Dawn refuses a dispatch whose indirect buffer it also binds.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.keys
+ * @param {number} options.values
+ * @param {number} options.count_buffer
+ * @param {number} options.count_offset
+ * @param {number} options.element_max_count at least 2
+ * @param {number} options.pass_count
+ * @param {number} options.key_mask
+ * @returns {{keys:number, values:number}}
+ */
+function record_device_count_sort({
+                                      graph,
+                                      keys,
+                                      values,
+                                      count_buffer,
+                                      count_offset,
+                                      element_max_count,
+                                      pass_count,
+                                      key_mask,
+                                  }) {
 
-    for (let pass_index = 0; pass_index < RADIX_PASSES; pass_index++) {
+    const tile_max_count = Math.ceil(element_max_count / SORT_TILE_SIZE);
 
-        const shift = pass_index * RADIX_LOG;
+    const spine_element_max_count = tile_max_count * RADIX;
+    const spine_size = (SPINE_HEADER_WORDS + spine_element_max_count) * Uint32Array.BYTES_PER_ELEMENT;
 
-        const histogram_data = { shift };
-        const histogram_pass = graph.add(`radix sort/histogram ${pass_index}`, histogram_data, execute_histogram);
+    // Not cleared, which would be work by capacity: the prepare writes the count word, the histograms
+    // every cell below the live count, and the scan reads no further.
+    const SPINE_DESCRIPTOR = BufferResourceDescriptor.from(spine_size, GPUBufferUsage.STORAGE);
 
-        histogram_data.keys = histogram_pass.read(read_keys);
-        histogram_data.spine = histogram_pass.create(`radix sort/spine ${pass_index}`, SPINE_DESCRIPTOR);
+    const SIZE_DESCRIPTOR = BufferResourceDescriptor.from(SORT_SIZE_STRUCT.size, GPUBufferUsage.STORAGE);
 
-        const scanned_spine = graph_prefix_scan_csdldf({
-            graph,
-            input: histogram_data.spine,
-            output: graph_create_buffer(graph, `radix sort/scanned spine ${pass_index}`, SCANNED_SPINE_DESCRIPTOR),
-            element_max_count: spine_element_count,
+    // what the caller's buffers and the transients must hold, as many keys as can be counted
+    const required = element_max_count * Uint32Array.BYTES_PER_ELEMENT;
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_prepare(pass_data, resources, context) {
+        const count_source = resources.get(pass_data.count);
+
+        assert.notEqual(count_source.usage & GPUBufferUsage.STORAGE, 0, 'count_buffer needs STORAGE usage');
+        assert.greaterThanOrEqual(count_source.size, count_offset + Uint32Array.BYTES_PER_ELEMENT, 'count_buffer ends before count_offset');
+
+        shader_radix_sort_prepare.dispatch({
+            encoder: context.encoder,
+            bindings: {
+                settings: {
+                    count_word: count_offset / Uint32Array.BYTES_PER_ELEMENT,
+                    element_max_count,
+                },
+                count_source,
+                sort_size: resources.get(pass_data.size),
+                command: resources.get(pass_data.command),
+                spine: resources.get(pass_data.spine),
+            }
         });
+    }
 
-        const scatter_data = { shift };
-        const scatter_pass = graph.add(`radix sort/scatter ${pass_index}`, scatter_data, execute_scatter);
+    const prepare_data = {};
+    const prepare_pass = graph.add("radix sort/prepare", prepare_data, execute_prepare);
 
-        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);
+    prepare_data.count = prepare_pass.read(count_buffer);
+    prepare_data.size = prepare_pass.create("radix sort/size", SIZE_DESCRIPTOR);
+    prepare_data.command = prepare_pass.create("radix sort/command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+    prepare_data.spine = prepare_pass.create("radix sort/spine", SPINE_DESCRIPTOR);
 
-        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);
-        }
+    // the one spine, as the last histogram to write it left it
+    let spine = prepare_data.spine;
 
-        scatter_data.out_keys = write_keys;
-        scatter_data.out_values = write_values;
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_histogram(pass_data, resources, context) {
+        shader_radix_sort_histogram_indirect.dispatchIndirect({
+            encoder: context.encoder,
+            command: resources.get(pass_data.command),
+            bindings: {
+                settings: {
+                    shift: pass_data.shift,
+                    key_mask,
+                },
+                keys: resources.get(pass_data.keys),
+                spine: resources.get(pass_data.spine),
+                sort_size: resources.get(pass_data.size),
+            }
+        });
+    }
 
-        // 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];
+    /**
+     * @param {FramePassBuilder} pass
+     * @param {Object} pass_data
+     */
+    function declare_histogram(pass, pass_data) {
+        pass_data.size = pass.read(prepare_data.size);
+        pass_data.command = pass.read(prepare_data.command);
+        pass_data.spine = spine = pass.write(spine);
     }
 
-    return {
-        keys: read_keys,
-        values: read_values,
-    };
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_scatter(pass_data, resources, context) {
+        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);
+
+        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_indirect.dispatchIndirect({
+            encoder: context.encoder,
+            command: resources.get(pass_data.command),
+            bindings: {
+                settings: {
+                    shift: pass_data.shift,
+                    key_mask,
+                },
+                in_keys,
+                in_values,
+                out_keys,
+                out_values,
+                spine: resources.get(pass_data.spine),
+                sort_size: resources.get(pass_data.size),
+            }
+        });
+    }
+
+    /**
+     * @param {FramePassBuilder} pass
+     * @param {Object} pass_data
+     */
+    function declare_scatter(pass, pass_data) {
+        pass_data.size = pass.read(prepare_data.size);
+        pass_data.command = pass.read(prepare_data.command);
+    }
+
+    return record_digit_passes({
+        graph,
+        keys,
+        values,
+        pass_count,
+        spine_element_max_count,
+        PING_PONG_DESCRIPTOR: ping_pong_descriptor(element_max_count),
+        execute_histogram,
+        declare_histogram,
+        execute_scatter,
+        declare_scatter,
+    });
 }

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

@@ -1,5 +1,8 @@
 /**
- * Per-tile 256-bin digit histogram — stage (a) of one digit pass of {@link graph_radix_sort}.
+ * Per-tile 256-bin digit histogram — stage (a) of one digit pass of {@link graph_radix_sort} over a
+ * host count, which it dispatches directly, a workgroup per tile. The tile's work is
+ * {@link chunk_sort_histogram_tile}; {@link shader_radix_sort_histogram_indirect} is the same work
+ * over a device count.
  *
  * 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.

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

@@ -1 +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":"AAsEA;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAMpB;8BApF2B,+BAA+B"}
+{"version":3,"file":"shader_radix_sort_histogram.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/shader_radix_sort_histogram.js"],"names":[],"mappings":"AAyCA;;;;;;;;;;;;;;;GAeG;AACH,0CAFU,aAAa,CAMpB;8BA5D2B,+BAA+B"}