@woosh/meep-engine 3.59.0 → 3.60.0

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.js

@@ -4,7 +4,14 @@ import { ComputeShader } from "../../../shader/ComputeShader.js";
 import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
 import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
-import { chunk_probe_clipmap, PROBE_DISPATCH_RESOURCE, PROBE_TRACE_READ_RESOURCE } from "./chunk_probe_clipmap.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_DISPATCH_RESOURCE,
+    PROBE_RAY_COUNTS_WRITE_RESOURCE,
+    PROBE_RAY_REQUESTS_WRITE_RESOURCE,
+    PROBE_RAY_SUMS_WRITE_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
 
 /**
  * @type {WebGPUStruct}
@@ -12,8 +19,6 @@ import { chunk_probe_clipmap, PROBE_DISPATCH_RESOURCE, PROBE_TRACE_READ_RESOURCE
 export const PROBE_TRACE_COMMAND_SETTINGS = WebGPUStruct.from({
     /** probes a frame updates at most: the trace list's bound */
     trace_capacity: u32,
-    /** rays an update casts, R */
-    rays_per_probe: u32,
     /** octahedral radiance texels a side, n_r */
     radiance_resolution: u32,
     /** octahedral depth texels a side, n_d */
@@ -26,17 +31,24 @@ resources.setImmediate("settings", PROBE_TRACE_COMMAND_SETTINGS);
 
 resources.createGroup()
     .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_RAY_COUNTS_WRITE_RESOURCE)
+    .add(PROBE_RAY_REQUESTS_WRITE_RESOURCE)
+    .add(PROBE_RAY_SUMS_WRITE_RESOURCE)
     .add(PROBE_DISPATCH_RESOURCE);
 
 /**
  * The update's commands (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, once the due passes
  * have listed the frame's updates, the list's count clamped to U:
- * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation and the probes' projection;
- * - a thread a ray of theirs, R a probe, at `PROBE_DISPATCH_RAYS`: trace and shade;
+ * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation, the ray counts and the probes'
+ *   projection;
  * - a thread a texel of their maps, n_r² + n_d² a probe, at `PROBE_DISPATCH_TEXELS`: accumulate;
  * - a thread a row of their radiance maps, n_r a probe, at `PROBE_DISPATCH_ROWS`: the projection's rows;
  * - a thread a texel of their tiles, (n_r + 2)² + (n_d + 2)² a probe, at `PROBE_DISPATCH_PUBLISH`.
  *
+ * It writes the count of the ray counts, the ray requests and the rays' layout, the probes listed, which
+ * the passes after fill in (`shader_probe_clipmap_ray_layout.js`): a probe's rays are its own update's,
+ * even when none is listed.
+ *
  * @type {ComputeShader}
  */
 export const shader_probe_clipmap_trace_command = ComputeShader.from({
@@ -54,11 +66,9 @@ fn main() {
     probe_dispatch[PROBE_DISPATCH_TRACED + 1u] = probes.y;
     probe_dispatch[PROBE_DISPATCH_TRACED + 2u] = probes.z;
 
-    let rays = folded_dispatch((traced * settings.rays_per_probe + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
-
-    probe_dispatch[PROBE_DISPATCH_RAYS] = rays.x;
-    probe_dispatch[PROBE_DISPATCH_RAYS + 1u] = rays.y;
-    probe_dispatch[PROBE_DISPATCH_RAYS + 2u] = rays.z;
+    probe_ray_counts.count = traced;
+    probe_ray_requests.count = traced;
+    probe_ray_sums.count = traced;
 
     let n = settings.radiance_resolution;
     let m = settings.depth_resolution;
@@ -80,6 +90,12 @@ fn main() {
     probe_dispatch[PROBE_DISPATCH_PUBLISH] = tiles.x;
     probe_dispatch[PROBE_DISPATCH_PUBLISH + 1u] = tiles.y;
     probe_dispatch[PROBE_DISPATCH_PUBLISH + 2u] = tiles.z;
+
+    let runs = folded_dispatch((traced + PROBE_ORDER_RUN - 1u) / PROBE_ORDER_RUN);
+
+    probe_dispatch[PROBE_DISPATCH_ORDER] = runs.x;
+    probe_dispatch[PROBE_DISPATCH_ORDER + 1u] = runs.y;
+    probe_dispatch[PROBE_DISPATCH_ORDER + 2u] = runs.z;
 }
 `, [
             chunk_probe_clipmap,

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.d.ts

@@ -16,8 +16,9 @@ export const PROBE_WANT_HITS_SETTINGS: WebGPUStruct;
  * want nothing in turn: the chain stops after one step, as Enshrouded's world-cache probes do. Unstopped,
  * hits would want a probe at every surface the windows hold, the dense lattice D31 turned down.
  *
- * It binds the last frame's trace list, origins and rays, which the frame's trace writes over later, and
- * is told that frame's U and R.
+ * It binds the last frame's trace list, origins and rays, which the frame's trace writes over later. A ray
+ * names its probe, its place in that list, in its flags; a record of no ray (`PROBE_RAY_NONE`) is past
+ * that frame's last.
  *
  * @type {ComputeShader}
  */

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_want_hits.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.js"],"names":[],"mappings":"AAoBA;;GAEG;AACH,uCAFU,YAAY,CAYM;AAe5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,6CAFU,aAAa,CA4CpB;6BAvG0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_want_hits.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.js"],"names":[],"mappings":"AAqBA;;GAEG;AACH,uCAFU,YAAY,CAQM;AAe5B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6CAFU,aAAa,CA8CpB;6BAvG0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.js

@@ -7,6 +7,7 @@ import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import {
     chunk_probe_clipmap,
+    chunk_probe_clipmap_ray_origin,
     PROBE_LEVELS_RESOURCE,
     PROBE_ORIGINS_READ_RESOURCE,
     PROBE_RAYS_READ_RESOURCE,
@@ -27,10 +28,6 @@ export const PROBE_WANT_HITS_SETTINGS = WebGPUStruct.from({
     resolution: u32,
     /** keys over every cascade: what the wanted list holds at most */
     key_count: u32,
-    /** the trace list's bound in the rays' frame, its U */
-    trace_capacity: u32,
-    /** rays an update in the rays' frame, its R */
-    rays_per_probe: u32,
 }, "ProbeWantHitsSettings");
 
 const resources = new ShaderResourceSetDescriptor();
@@ -60,8 +57,9 @@ resources.createGroup()
  * want nothing in turn: the chain stops after one step, as Enshrouded's world-cache probes do. Unstopped,
  * hits would want a probe at every surface the windows hold, the dense lattice D31 turned down.
  *
- * It binds the last frame's trace list, origins and rays, which the frame's trace writes over later, and
- * is told that frame's U and R.
+ * It binds the last frame's trace list, origins and rays, which the frame's trace writes over later. A ray
+ * names its probe, its place in that list, in its flags; a record of no ray (`PROBE_RAY_NONE`) is past
+ * that frame's last.
  *
  * @type {ComputeShader}
  */
@@ -77,24 +75,25 @@ fn main(
     @builtin(local_invocation_index) lane: u32,
 ) {
     let ray = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
-    let rays = settings.rays_per_probe;
 
     var wants = false;
     var position = vec3<f32>(0.0);
     var bias_direction = vec3<f32>(0.0);
 
-    if (ray < min(probe_trace.count, settings.trace_capacity) * rays) {
-        let record = probe_rays[ray];
-        let slot = probe_trace.elements[ray / rays];
+    let record = probe_rays[ray];
+
+    if ((record.flags & PROBE_RAY_KIND_MASK) != PROBE_RAY_NONE) {
+        let k = record.flags >> PROBE_RAY_PROBE_SHIFT;
+        let slot = probe_trace.elements[k];
 
         // shade left a front-face hit's albedo in its row and zero in any other ray's: a ray that takes no
         // bounce, a black hit's among them, wants nothing
-        wants = record.row != 0u && probe_records[slot].screen != 0u;
+        wants = record.row != 0u && (probe_records[slot].flags & PROBE_RECORD_SCREEN) != 0u;
 
         let direction = uv_octahedral_unit_decode(unpack2x16unorm(record.direction));
         let normal = uv_octahedral_unit_decode(unpack2x16unorm(record.normal));
 
-        position = probe_origins[ray / rays].xyz + record.t * direction;
+        position = probe_clipmap_ray_origin(probe_origins[k], slot, record.direction) + record.t * direction;
         // the view back along the ray, as the light pass's pick takes it
         bias_direction = mix(normal, -direction, ${PROBE_RECEIVER_BIAS_VIEW});
     }
@@ -103,6 +102,7 @@ fn main(
 }
 `, [
             chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_origin,
             chunk_folded_workgroup_index,
             chunk_uv_octahedral_unit_decode,
             chunk_probe_clipmap_want,

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

@@ -0,0 +1,10 @@
+/**
+ * Per-digit-pass constants of a sort over a device count, shared by
+ * {@link shader_radix_sort_histogram_indirect} and {@link shader_radix_sort_scatter_indirect}. The
+ * host knows these; the size of the input it does not, and that lives in {@link SORT_SIZE_STRUCT}.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_DIGIT_SETTINGS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=SORT_DIGIT_SETTINGS_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SORT_DIGIT_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/SORT_DIGIT_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,yCAFU,YAAY,CAYE;6BAnBK,mCAAmC"}

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

@@ -0,0 +1,21 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Per-digit-pass constants of a sort over a device count, shared by
+ * {@link shader_radix_sort_histogram_indirect} and {@link shader_radix_sort_scatter_indirect}. The
+ * host knows these; the size of the input it does not, and that lives in {@link SORT_SIZE_STRUCT}.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_DIGIT_SETTINGS_STRUCT = WebGPUStruct.from({
+    /**
+     * Bit position of the digit this pass sorts on — 0, 8, 16, 24.
+     */
+    shift: u32,
+    /**
+     * The key's bits, `key_bits` of them set from the bottom: what a digit is selected from. See
+     * `sort_extract_key_digit` in {@link chunk_sort_digit}.
+     */
+    key_mask: u32,
+}, "SortDigitSettings");

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

@@ -1,6 +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.
+ * Per-digit-pass constants of a sort over a host count, shared by the histogram and the scatter so
+ * the two agree on which keys exist and where their counts live in the spine.
+ *
+ * A sort over a device count reads `element_count` and `tile_count` from {@link SORT_SIZE_STRUCT}
+ * instead, and carries the rest as {@link SORT_DIGIT_SETTINGS_STRUCT}.
  *
  * @type {WebGPUStruct}
  */

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

@@ -1 +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"}
+{"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;;;;;;;;GAQG;AACH,wCAFU,YAAY,CAoBC;6BA7BM,mCAAmC"}

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

@@ -1,23 +1,31 @@
-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");
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Per-digit-pass constants of a sort over a host count, shared by the histogram and the scatter so
+ * the two agree on which keys exist and where their counts live in the spine.
+ *
+ * A sort over a device count reads `element_count` and `tile_count` from {@link SORT_SIZE_STRUCT}
+ * instead, and carries the rest as {@link SORT_DIGIT_SETTINGS_STRUCT}.
+ *
+ * @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,
+    /**
+     * The key's bits, `key_bits` of them set from the bottom: what a digit is selected from. See
+     * `sort_extract_key_digit` in {@link chunk_sort_digit}.
+     */
+    key_mask: u32,
+}, "SortPassSettings");

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

@@ -0,0 +1,10 @@
+/**
+ * The live size of a sort over a device count, written once by {@link shader_radix_sort_prepare} and
+ * read by every histogram and scatter after it. The same two numbers a host-count sort carries in
+ * {@link SORT_PASS_SETTINGS_STRUCT}, which the host cannot know here.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_SIZE_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=SORT_SIZE_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SORT_SIZE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/SORT_SIZE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,+BAFU,YAAY,CAaP;6BApBc,mCAAmC"}

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

@@ -0,0 +1,22 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * The live size of a sort over a device count, written once by {@link shader_radix_sort_prepare} and
+ * read by every histogram and scatter after it. The same two numbers a host-count sort carries in
+ * {@link SORT_PASS_SETTINGS_STRUCT}, which the host cannot know here.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_SIZE_STRUCT = WebGPUStruct.from({
+    /**
+     * Keys being sorted: the device count, at most the sort's `element_max_count`. The tail tile is
+     * partial and every read is bounds-checked against this.
+     */
+    element_count: u32,
+    /**
+     * Tiles those keys fill, which is the stride between adjacent bins in the bin-major spine and the
+     * number of workgroups the histogram and scatter are dispatched over.
+     */
+    tile_count: u32,
+}, "SortSize");

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

@@ -0,0 +1,9 @@
+/**
+ * The sort's tile geometry from `defs.js`, as WGSL constants: one declaration for every chunk and
+ * shader of the sort that links it, rather than a copy in each.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_constants: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sort_constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sort_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/chunk_sort_constants.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,mCAFU,SAAS,CAUhB;0BAjBuB,oCAAoC"}

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

@@ -0,0 +1,18 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { RADIX, RADIX_LOG, SORT_KEYS_PER_THREAD, SORT_TILE_SIZE, SORT_WORKGROUP_SIZE } from "./defs.js";
+
+/**
+ * The sort's tile geometry from `defs.js`, as WGSL constants: one declaration for every chunk and
+ * shader of the sort that links it, rather than a copy in each.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_constants = CodeChunk.from(
+    //language=WGSL
+    `
+const SORT_WORKGROUP_SIZE = ${SORT_WORKGROUP_SIZE}u;
+const SORT_KEYS_PER_THREAD = ${SORT_KEYS_PER_THREAD}u;
+const SORT_TILE_SIZE = ${SORT_TILE_SIZE}u;
+const SORT_RADIX = ${RADIX}u;
+const SORT_RADIX_LOG = ${RADIX_LOG}u;
+`);

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

@@ -1,10 +1,15 @@
 /**
- * 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.
+ * The 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_extract_key_digit` is the digit the sort orders by: the same selector over the key's low
+ * `key_bits` alone, `key_mask` being those bits set. A key narrower than its last digit pass — 20 bits
+ * sorted in three 8-bit passes, say — would otherwise be ordered by whatever sits in the bits above
+ * it, which a caller is not required to clear. Every stage that reads a digit or a digit's bit reads
+ * it through this, so they all see the same key.
+ *
  * `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

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

@@ -1 +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"}
+{"version":3,"file":"chunk_sort_digit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/chunk_sort_digit.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+BAFU,SAAS,CAmBhB;0BAxCuB,oCAAoC"}

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

@@ -1,32 +1,41 @@
-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;
-}
-`);
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { RADIX, SPINE_HEADER_WORDS } from "./defs.js";
+
+/**
+ * The 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_extract_key_digit` is the digit the sort orders by: the same selector over the key's low
+ * `key_bits` alone, `key_mask` being those bits set. A key narrower than its last digit pass — 20 bits
+ * sorted in three 8-bit passes, say — would otherwise be ordered by whatever sits in the bits above
+ * it, which a caller is not required to clear. Every stage that reads a digit or a digit's bit reads
+ * it through this, so they all see the same key.
+ *
+ * `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_extract_key_digit(key: u32, shift: u32, key_mask: u32) -> u32 {
+    return sort_extract_digit(key & key_mask, shift);
+}
+
+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_histogram_tile.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The keys a histogram counts.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_HISTOGRAM_KEYS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * `{count: u32, elements: array<vec4u>}` as the scan sees it, flat as the histogram 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.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_HISTOGRAM_SPINE_RESOURCE: ShaderResourceDescriptor;
+/**
+ * One tile's 256-bin digit histogram, written into the spine bin-major — the body of both
+ * {@link shader_radix_sort_histogram} and {@link shader_radix_sort_histogram_indirect}, which differ
+ * only in where the tile and the sort's size come from.
+ *
+ * ```wgsl
+ * fn sort_histogram_tile(tile: u32, element_count: u32, tile_count: u32, shift: u32, key_mask: u32, thread_id: u32)
+ * ```
+ *
+ * Call from workgroup-uniform control flow, every thread of a {@link SORT_WORKGROUP_SIZE}-wide
+ * workgroup with its `local_invocation_index`: it holds barriers. `tile` must be below `tile_count`,
+ * since the cell it writes for a tile past them belongs to the next bin.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_histogram_tile: CodeChunk;
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sort_histogram_tile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sort_histogram_tile.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/chunk_sort_histogram_tile.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH,2CAFU,wBAAwB,CAEuF;AAEzH;;;;;GAKG;AACH,4CAFU,wBAAwB,CAEwF;AAE1H;;;;;;;;;;;;;;GAcG;AACH,wCAFU,SAAS,CAiChB;yCAlEsC,mDAAmD;0BADlE,oCAAoC"}

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

@@ -0,0 +1,71 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_sort_constants } from "./chunk_sort_constants.js";
+import { chunk_sort_digit } from "./chunk_sort_digit.js";
+
+/**
+ * The keys a histogram counts.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_HISTOGRAM_KEYS_RESOURCE = ShaderResourceDescriptor.storageBuffer("keys", WebGPUArray.from(u32), false);
+
+/**
+ * `{count: u32, elements: array<vec4u>}` as the scan sees it, flat as the histogram 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.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_HISTOGRAM_SPINE_RESOURCE = ShaderResourceDescriptor.storageBuffer("spine", WebGPUArray.from(u32), true);
+
+/**
+ * One tile's 256-bin digit histogram, written into the spine bin-major — the body of both
+ * {@link shader_radix_sort_histogram} and {@link shader_radix_sort_histogram_indirect}, which differ
+ * only in where the tile and the sort's size come from.
+ *
+ * ```wgsl
+ * fn sort_histogram_tile(tile: u32, element_count: u32, tile_count: u32, shift: u32, key_mask: u32, thread_id: u32)
+ * ```
+ *
+ * Call from workgroup-uniform control flow, every thread of a {@link SORT_WORKGROUP_SIZE}-wide
+ * workgroup with its `local_invocation_index`: it holds barriers. `tile` must be below `tile_count`,
+ * since the cell it writes for a tile past them belongs to the next bin.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_histogram_tile = CodeChunk.from(
+    //language=WGSL
+    `
+// 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_sort_tile_counts: array<atomic<u32>, SORT_RADIX>;
+
+fn sort_histogram_tile(tile: u32, element_count: u32, tile_count: u32, shift: u32, key_mask: u32, thread_id: u32) {
+    atomicStore(&wg_sort_tile_counts[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 * SORT_TILE_SIZE;
+    for (var k = 0u; k < SORT_KEYS_PER_THREAD; k += 1u) {
+        let source = tile_base + k * SORT_WORKGROUP_SIZE + thread_id;
+
+        if (source < element_count) {
+            atomicAdd(&wg_sort_tile_counts[sort_extract_key_digit(keys[source], shift, key_mask)], 1u);
+        }
+    }
+
+    workgroupBarrier();
+
+    spine[sort_spine_index(thread_id, tile, tile_count)] = atomicLoad(&wg_sort_tile_counts[thread_id]);
+}
+`, [
+    chunk_sort_constants,
+    chunk_sort_digit,
+]);
+
+chunk_sort_histogram_tile.requireResource(SORT_HISTOGRAM_KEYS_RESOURCE);
+chunk_sort_histogram_tile.requireResource(SORT_HISTOGRAM_SPINE_RESOURCE);

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

@@ -0,0 +1,47 @@
+/**
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_SCATTER_IN_KEYS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_SCATTER_IN_VALUES_RESOURCE: ShaderResourceDescriptor;
+/**
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_SCATTER_OUT_KEYS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_SCATTER_OUT_VALUES_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The scanned spine, read flat past its `{count, elements}` header.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SORT_SCATTER_SPINE_RESOURCE: ShaderResourceDescriptor;
+/**
+ * One tile's rank-and-scatter — the body of both {@link shader_radix_sort_scatter} and
+ * {@link shader_radix_sort_scatter_indirect}, which differ only in where the tile and the sort's size
+ * come from.
+ *
+ * ```wgsl
+ * fn sort_scatter_tile(tile: u32, element_count: u32, tile_count: u32, shift: u32, key_mask: u32,
+ *                      thread_id: u32, lane_id: u32, lane_count: u32)
+ * ```
+ *
+ * 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`.
+ *
+ * Call from workgroup-uniform control flow, every thread of a {@link SORT_WORKGROUP_SIZE}-wide
+ * workgroup with its `local_invocation_index` and subgroup builtins: it holds barriers and subgroup
+ * operations. `tile` must be below `tile_count`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_scatter_tile: CodeChunk;
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sort_scatter_tile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sort_scatter_tile.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/chunk_sort_scatter_tile.js"],"names":[],"mappings":"AAUA;;GAEG;AACH,4CAFU,wBAAwB,CAE2F;AAE7H;;GAEG;AACH,8CAFU,wBAAwB,CAE+F;AAEjI;;GAEG;AACH,6CAFU,wBAAwB,CAE4F;AAE9H;;GAEG;AACH,+CAFU,wBAAwB,CAEgG;AAElI;;;GAGG;AACH,0CAFU,wBAAwB,CAEuF;AAEzH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,sCAFU,SAAS,CAiJhB;yCAvMsC,mDAAmD;0BADlE,oCAAoC"}