@woosh/meep-engine 3.12.0 → 3.13.0

package/src/shade/renderer/particles/shaders/shader_particle_simulate.js

@@ -1,99 +1,111 @@
-import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    PARTICLE_RECORD_HEADER_EMITTER,
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_VM_INSTRUCTION_WORDS,
-} from "../ParticleConstants.js";
-import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_particle_context.js";
-
-/**
- * The particle simulate pass — Destiny-style single execution shader.
- *
- * One dispatch processes the entire alive list across every emitter. Per particle: read its owning
- * emitter, set up the VM context + RNG, run that emitter's compiled UPDATE program over the record,
- * then compact — killed particles are pushed back to the dead (free) list, survivors are appended to
- * the new alive list. There is exactly one pipeline regardless of how many distinct effects exist,
- * because behaviour is data (the bytecode program), not code.
- *
- * The input length is read from `counters[ALIVE_IN]` — the previous frame's final alive count,
- * snapshotted on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count
- * is inevitably stale (readback latency) and corrupts the pool: under-counting orphans the tail of
- * the alive list (slots leak into limbo), over-counting re-simulates stale entries and double-frees
- * their slots. Dispatch this shader with `dispatchWorkgroupsIndirect` using the args the
- * build-indirect pass wrote last frame, so thread count and bound agree by construction.
- *
- * All structured reads go through `array<u32>` for emulator-testability. Curve sampling uses the
- * pluggable `particle_vm_sample_curve` — here the no-op provider; the feature swaps in the
- * animation-database-backed one.
- *
- * @type {ComputeShader}
- */
-
-export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
-    .addStorageBuffer("program", WebGPUArray.u32, false)
-    .addStorageBuffer("vm_constants", WebGPUArray.u32, false)
-    .addStorageBuffer("pool", WebGPUArray.u32, true)
-    .addStorageBuffer("alive_in", WebGPUArray.u32, false)
-    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
-    .addStorageBuffer("dead", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
-    .addUniform("u_dt", f32)
-    .addUniform("u_time", f32)
-    .addUniform("u_frame", u32);
-
-const body = CodeChunk.from(/* wgsl */ `
-const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
-const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
-const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
-const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
-const COUNTER_ALIVE_IN : u32 = ${PARTICLE_COUNTER.ALIVE_IN}u;
-
-@compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    // The exact alive-list length, snapshotted on-GPU last frame — never a stale CPU value.
-    if (i >= atomicLoad(&counters[COUNTER_ALIVE_IN])) { return; }
-
-    let slot = alive_in[i];
-    let record_base = slot * PARTICLE_RECORD_WORDS;
-    let emitter_index = pool[record_base + PARTICLE_HEADER_EMITTER];
-
-    let em = particle_emitter_read(&emitters, emitter_index);
-
-    particle_vm_reset();
-    particle_setup_context(em, slot, u_dt, u_time, 0.0, 0.0, u_frame);
-    particle_vm_execute(
-        &program,
-        em.update_offset * PARTICLE_INSTRUCTION_WORDS,
-        em.update_count,
-        &vm_constants,
-        em.constant_offset,
-        &pool,
-        record_base,
-    );
-
-    if (vm_killed) {
-        let d = atomicAdd(&counters[COUNTER_DEAD], 1u);
-        dead[d] = slot;
-    } else {
-        let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
-        alive_out[a] = slot;
-    }
-}
-`, [chunk_particle_context, chunk_particle_curve_disabled]);
-
-export const shader_particle_simulate = ComputeShader.from({
-    label: "Particle Simulate",
-    resources,
-    body,
-});
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+} from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_particle_context.js";
+
+/**
+ * The particle simulate pass — Destiny-style single execution shader.
+ *
+ * One dispatch processes the entire alive list across every emitter. Per particle: read its owning
+ * emitter, set up the VM context + RNG, run that emitter's compiled UPDATE program over the record,
+ * then compact — killed particles are pushed back to the dead (free) list, survivors are appended to
+ * the new alive list. There is exactly one pipeline regardless of how many distinct effects exist,
+ * because behaviour is data (the bytecode program), not code.
+ *
+ * The input length is read from `counters[ALIVE_IN]` — the previous frame's final alive count,
+ * snapshotted on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count
+ * is inevitably stale (readback latency) and corrupts the pool: under-counting orphans the tail of
+ * the alive list (slots leak into limbo), over-counting re-simulates stale entries and double-frees
+ * their slots. Dispatch this shader with `dispatchWorkgroupsIndirect` using the args the
+ * build-indirect pass wrote last frame, so thread count and bound agree by construction.
+ *
+ * All structured reads go through `array<u32>` for emulator-testability. Curve sampling uses the
+ * pluggable `particle_vm_sample_curve` — here the no-op provider; the feature swaps in the
+ * animation-database-backed one.
+ *
+ * @type {ComputeShader}
+ */
+
+export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
+
+/**
+ * Per-dispatch, 12 bytes, read-only — see shader_particle_emit for why the three travel
+ * together rather than as three uniforms.
+ *
+ * @type {WebGPUStruct}
+ */
+const SIMULATE_SETTINGS = WebGPUStruct.from({
+    u_dt: f32,
+    u_time: f32,
+    u_frame: u32,
+}, 'ParticleSimulateSettings');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', SIMULATE_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("program", WebGPUArray.u32, false)
+    .addStorageBuffer("vm_constants", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, true)
+    .addStorageBuffer("alive_in", WebGPUArray.u32, false)
+    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+const body = CodeChunk.from(/* wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
+const COUNTER_ALIVE_IN : u32 = ${PARTICLE_COUNTER.ALIVE_IN}u;
+
+@compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    // The exact alive-list length, snapshotted on-GPU last frame — never a stale CPU value.
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE_IN])) { return; }
+
+    let slot = alive_in[i];
+    let record_base = slot * PARTICLE_RECORD_WORDS;
+    let emitter_index = pool[record_base + PARTICLE_HEADER_EMITTER];
+
+    let em = particle_emitter_read(&emitters, emitter_index);
+
+    particle_vm_reset();
+    particle_setup_context(em, slot, settings.u_dt, settings.u_time, 0.0, 0.0, settings.u_frame);
+    particle_vm_execute(
+        &program,
+        em.update_offset * PARTICLE_INSTRUCTION_WORDS,
+        em.update_count,
+        &vm_constants,
+        em.constant_offset,
+        &pool,
+        record_base,
+    );
+
+    if (vm_killed) {
+        let d = atomicAdd(&counters[COUNTER_DEAD], 1u);
+        dead[d] = slot;
+    } else {
+        let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
+        alive_out[a] = slot;
+    }
+}
+`, [chunk_particle_context, chunk_particle_curve_disabled]);
+
+export const shader_particle_simulate = ComputeShader.from({
+    label: "Particle Simulate",
+    resources,
+    body,
+});

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8CAA+C;AAyB/C,uDAIG;AA+DH,2DAIG;AA4BH,yDAIG;8BA3J2B,+BAA+B"}
+{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8CAA+C;AAkC/C,uDAIG;AAyEH,2DAIG;AAqCH,yDAIG;8BAvL2B,+BAA+B"}

package/src/shade/renderer/particles/sort/shader_particle_sort.js

@@ -1,158 +1,187 @@
-import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
-import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_LAYOUT.js";
-import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
-
-/**
- * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
- *
- * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
- *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
- *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
- *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
- * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
- *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
- *    `keys`, and atomically bump the per-bucket `histogram`.
- * 2. graph_prefix_scan_csdldf turns the histogram into inclusive prefix sums.
- * 3. {@link shader_particle_sort_scatter} — per particle, read its bucket, take the exclusive
- *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
- *    into `sorted` at that position.
- *
- * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
- * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
- * algorithm.
- */
-
-export const PARTICLE_SORT_WORKGROUP_SIZE = 64;
-
-// --- reset pass ---
-
-const reset_resources = new ShaderResourceSetDescriptor();
-reset_resources.createGroup()
-    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
-    .addUniform("u_bucket_count", u32);
-
-const reset_body = CodeChunk.from(/* wgsl */ `
-@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i == 0u) {
-        // The {count, elements} header the csdldf scan sizes itself from.
-        atomicStore(&histogram[0], u_bucket_count);
-    }
-    if (i < u_bucket_count) {
-        atomicStore(&histogram[1u + i], 0u);
-        atomicStore(&cursor[i], 0u);
-    }
-}
-`);
-
-export const shader_particle_sort_reset = ComputeShader.from({
-    label: "Particle Sort Reset",
-    resources: reset_resources,
-    body: reset_body,
-});
-
-const READ_MAT4 = /* wgsl */ `
-fn particle_read_mat4(m : ptr<storage, array<u32>, read>, o : u32) -> mat4x4<f32> {
-    return mat4x4<f32>(
-        vec4<f32>(bitcast<f32>((*m)[o + 0u]), bitcast<f32>((*m)[o + 1u]), bitcast<f32>((*m)[o + 2u]), bitcast<f32>((*m)[o + 3u])),
-        vec4<f32>(bitcast<f32>((*m)[o + 4u]), bitcast<f32>((*m)[o + 5u]), bitcast<f32>((*m)[o + 6u]), bitcast<f32>((*m)[o + 7u])),
-        vec4<f32>(bitcast<f32>((*m)[o + 8u]), bitcast<f32>((*m)[o + 9u]), bitcast<f32>((*m)[o + 10u]), bitcast<f32>((*m)[o + 11u])),
-        vec4<f32>(bitcast<f32>((*m)[o + 12u]), bitcast<f32>((*m)[o + 13u]), bitcast<f32>((*m)[o + 14u]), bitcast<f32>((*m)[o + 15u])),
-    );
-}
-`;
-
-// --- histogram pass ---
-
-const histogram_resources = new ShaderResourceSetDescriptor();
-histogram_resources.createGroup()
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
-    .addStorageBuffer("pool", WebGPUArray.u32, false)
-    .addStorageBuffer("alive", WebGPUArray.u32, false)
-    .addStorageBuffer("view_matrix", WebGPUArray.u32, false)
-    .addStorageBuffer("keys", WebGPUArray.u32, true)
-    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
-    .addUniform("u_near", f32)
-    .addUniform("u_far", f32)
-    .addUniform("u_bucket_count", u32)
-    .addUniform("u_count", u32);
-
-const histogram_body = CodeChunk.from(/* wgsl */ `
-const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
-const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
-
-${READ_MAT4}
-
-@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i >= u_count) { return; }
-
-    let slot = alive[i];
-    let base = slot * PARTICLE_RECORD_WORDS;
-    let emitter_index = pool[base + PARTICLE_HEADER_EMITTER];
-    let em = particle_emitter_read(&emitters, emitter_index);
-
-    var world_pos = vec3<f32>(0.0);
-    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) {
-        let o = base + em.render_position;
-        world_pos = vec3<f32>(bitcast<f32>(pool[o]), bitcast<f32>(pool[o + 1u]), bitcast<f32>(pool[o + 2u]));
-    }
-
-    let view = particle_read_mat4(&view_matrix, 0u);
-    let view_depth = -(view * vec4<f32>(world_pos, 1.0)).z;
-
-    let t = (view_depth - u_near) / max(u_far - u_near, 1e-6);
-    let clamped = clamp(1.0 - t, 0.0, 1.0);
-    let bucket = min(u32(clamped * f32(u_bucket_count)), u_bucket_count - 1u);
-
-    keys[i] = bucket;
-    atomicAdd(&histogram[1u + bucket], 1u);
-}
-`, [chunk_particle_emitter]);
-
-export const shader_particle_sort_histogram = ComputeShader.from({
-    label: "Particle Sort Histogram",
-    resources: histogram_resources,
-    body: histogram_body,
-});
-
-// --- scatter pass ---
-
-const scatter_resources = new ShaderResourceSetDescriptor();
-scatter_resources.createGroup()
-    .addStorageBuffer("keys", WebGPUArray.u32, false)
-    .addStorageBuffer("alive", WebGPUArray.u32, false)
-    .addStorageBuffer("scanned", WebGPUArray.u32, false)
-    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("sorted", WebGPUArray.u32, true)
-    .addUniform("u_count", u32);
-
-const scatter_body = CodeChunk.from(/* wgsl */ `
-@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i >= u_count) { return; }
-
-    let bucket = keys[i];
-    // Exclusive offset = inclusive prefix sum up to bucket-1. With the count field at index 0 the
-    // scanned inclusive value for bucket b lives at index (1+b), so bucket b-1 is at index b.
-    let exclusive = select(0u, scanned[bucket], bucket > 0u);
-    let rank = atomicAdd(&cursor[bucket], 1u);
-    sorted[exclusive + rank] = alive[i];
-}
-`);
-
-export const shader_particle_sort_scatter = ComputeShader.from({
-    label: "Particle Sort Scatter",
-    resources: scatter_resources,
-    body: scatter_body,
-});
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
+import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_LAYOUT.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+
+/**
+ * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
+ *
+ * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
+ *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
+ *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
+ *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
+ * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
+ *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
+ *    `keys`, and atomically bump the per-bucket `histogram`.
+ * 2. graph_prefix_scan_csdldf turns the histogram into inclusive prefix sums.
+ * 3. {@link shader_particle_sort_scatter} — per particle, read its bucket, take the exclusive
+ *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
+ *    into `sorted` at that position.
+ *
+ * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
+ * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
+ * algorithm.
+ */
+
+export const PARTICLE_SORT_WORKGROUP_SIZE = 64;
+
+// --- reset pass ---
+
+/**
+ * Per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer.
+ *
+ * @type {WebGPUStruct}
+ */
+const SORT_RESET_SETTINGS = WebGPUStruct.from({
+    u_bucket_count: u32,
+}, 'ParticleSortResetSettings');
+
+const reset_resources = new ShaderResourceSetDescriptor();
+
+reset_resources.setImmediate('settings', SORT_RESET_SETTINGS);
+reset_resources.createGroup()
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true);
+const reset_body = CodeChunk.from(/* wgsl */ `
+@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i == 0u) {
+        // The {count, elements} header the csdldf scan sizes itself from.
+        atomicStore(&histogram[0], settings.u_bucket_count);
+    }
+    if (i < settings.u_bucket_count) {
+        atomicStore(&histogram[1u + i], 0u);
+        atomicStore(&cursor[i], 0u);
+    }
+}
+`);
+
+export const shader_particle_sort_reset = ComputeShader.from({
+    label: "Particle Sort Reset",
+    resources: reset_resources,
+    body: reset_body,
+});
+
+const READ_MAT4 = /* wgsl */ `
+fn particle_read_mat4(m : ptr<storage, array<u32>, read>, o : u32) -> mat4x4<f32> {
+    return mat4x4<f32>(
+        vec4<f32>(bitcast<f32>((*m)[o + 0u]), bitcast<f32>((*m)[o + 1u]), bitcast<f32>((*m)[o + 2u]), bitcast<f32>((*m)[o + 3u])),
+        vec4<f32>(bitcast<f32>((*m)[o + 4u]), bitcast<f32>((*m)[o + 5u]), bitcast<f32>((*m)[o + 6u]), bitcast<f32>((*m)[o + 7u])),
+        vec4<f32>(bitcast<f32>((*m)[o + 8u]), bitcast<f32>((*m)[o + 9u]), bitcast<f32>((*m)[o + 10u]), bitcast<f32>((*m)[o + 11u])),
+        vec4<f32>(bitcast<f32>((*m)[o + 12u]), bitcast<f32>((*m)[o + 13u]), bitcast<f32>((*m)[o + 14u]), bitcast<f32>((*m)[o + 15u])),
+    );
+}
+`;
+
+// --- histogram pass ---
+
+/**
+ * Per-dispatch, 16 bytes, read-only. Four uniforms meant four transient buffers per sort;
+ * WGSL allows one immediate per entry point, so they travel together.
+ *
+ * @type {WebGPUStruct}
+ */
+const SORT_HISTOGRAM_SETTINGS = WebGPUStruct.from({
+    u_near: f32,
+    u_far: f32,
+    u_bucket_count: u32,
+    u_count: u32,
+}, 'ParticleSortHistogramSettings');
+
+const histogram_resources = new ShaderResourceSetDescriptor();
+
+histogram_resources.setImmediate('settings', SORT_HISTOGRAM_SETTINGS);
+histogram_resources.createGroup()
+    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("view_matrix", WebGPUArray.u32, false)
+    .addStorageBuffer("keys", WebGPUArray.u32, true)
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true);
+const histogram_body = CodeChunk.from(/* wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
+
+${READ_MAT4}
+
+@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= settings.u_count) { return; }
+
+    let slot = alive[i];
+    let base = slot * PARTICLE_RECORD_WORDS;
+    let emitter_index = pool[base + PARTICLE_HEADER_EMITTER];
+    let em = particle_emitter_read(&emitters, emitter_index);
+
+    var world_pos = vec3<f32>(0.0);
+    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) {
+        let o = base + em.render_position;
+        world_pos = vec3<f32>(bitcast<f32>(pool[o]), bitcast<f32>(pool[o + 1u]), bitcast<f32>(pool[o + 2u]));
+    }
+
+    let view = particle_read_mat4(&view_matrix, 0u);
+    let view_depth = -(view * vec4<f32>(world_pos, 1.0)).z;
+
+    let t = (view_depth - settings.u_near) / max(settings.u_far - settings.u_near, 1e-6);
+    let clamped = clamp(1.0 - t, 0.0, 1.0);
+    let bucket = min(u32(clamped * f32(settings.u_bucket_count)), settings.u_bucket_count - 1u);
+
+    keys[i] = bucket;
+    atomicAdd(&histogram[1u + bucket], 1u);
+}
+`, [chunk_particle_emitter]);
+
+export const shader_particle_sort_histogram = ComputeShader.from({
+    label: "Particle Sort Histogram",
+    resources: histogram_resources,
+    body: histogram_body,
+});
+
+// --- scatter pass ---
+
+/**
+ * Per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer.
+ *
+ * @type {WebGPUStruct}
+ */
+const SORT_SCATTER_SETTINGS = WebGPUStruct.from({
+    u_count: u32,
+}, 'ParticleSortScatterSettings');
+
+const scatter_resources = new ShaderResourceSetDescriptor();
+
+scatter_resources.setImmediate('settings', SORT_SCATTER_SETTINGS);
+scatter_resources.createGroup()
+    .addStorageBuffer("keys", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("scanned", WebGPUArray.u32, false)
+    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("sorted", WebGPUArray.u32, true);
+const scatter_body = CodeChunk.from(/* wgsl */ `
+@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= settings.u_count) { return; }
+
+    let bucket = keys[i];
+    // Exclusive offset = inclusive prefix sum up to bucket-1. With the count field at index 0 the
+    // scanned inclusive value for bucket b lives at index (1+b), so bucket b-1 is at index b.
+    let exclusive = select(0u, scanned[bucket], bucket > 0u);
+    let rank = atomicAdd(&cursor[bucket], 1u);
+    sorted[exclusive + rank] = alive[i];
+}
+`);
+
+export const shader_particle_sort_scatter = ComputeShader.from({
+    label: "Particle Sort Scatter",
+    resources: scatter_resources,
+    body: scatter_body,
+});

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AccumulatingPathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AACH;IA8EI;;;OAGG;IACH,uCAgBC;IAhGD;;;;OAIG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,eAFU,OAAO,CAEK;IA+NtB;;;;;;OAMG;IACH,yCAFa,MAAM,CA4JlB;;CACJ"}
+{"version":3,"file":"AccumulatingPathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AACH;IA8EI;;;OAGG;IACH,uCAgBC;IAhGD;;;;OAIG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,eAFU,OAAO,CAEK;IA+NtB;;;;;;OAMG;IACH,yCAFa,MAAM,CAyJlB;;CACJ"}

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js

@@ -5,7 +5,7 @@ import { PerspectiveCamera } from "../../camera/PerspectiveCamera.js";
 import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
 import { graph_flood_fill } from "./graph_flood_fill.js";
 import { graph_float32rgba_to_float16rgba } from "./graph_float32rgba_to_float16rgba.js";
-import { ACCUMULATING_RT_UNIFORMS_STRUCT, shader_accumulating_path_tracer } from "./shader_accumulating_path_tracer.js";
+import { shader_accumulating_path_tracer } from "./shader_accumulating_path_tracer.js";
 
 
 const RGBA32FLOAT_BYTES_PER_PIXEL = 16;
@@ -359,15 +359,12 @@ export class AccumulatingPathTracer {
                 [output_resource.width, output_resource.height, 1]
             );
 
-            const settings = context.encoder.allocateTransientValueBuffer(
-                ACCUMULATING_RT_UNIFORMS_STRUCT,
-                {
-                    tile_offset: [tile_offset_x, tile_offset_y],
-                    tile_size: tile_size,
-                    random_seed: random_seed,
-                    alpha: alpha,
-                }
-            );
+            const settings = {
+                tile_offset: [tile_offset_x, tile_offset_y],
+                tile_size: tile_size,
+                random_seed: random_seed,
+                alpha: alpha,
+            };
 
             shader_accumulating_path_tracer.dispatch({
                 encoder: context.encoder,

package/src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_accumulating_path_tracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.js"],"names":[],"mappings":"AAiBA,2DAKG;AA2EH,4DAIG;6BAnG0B,mCAAmC;8BAOlC,+BAA+B"}
+{"version":3,"file":"shader_accumulating_path_tracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.js"],"names":[],"mappings":"AAiBA,2DAKG;AA8EH,4DAIG;6BAtG0B,mCAAmC;8BAOlC,+BAA+B"}