@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,123 @@
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { atomic_u32, f32 } 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_SIMULATE_WORKGROUP_SIZE, PARTICLE_VM_WIDE_LAUNCH_LANES } from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { chunk_particle_vm_registers_wide } from "../vm/chunk_particle_vm_registers_wide.js";
+import { chunk_particle_curve_disabled } from "./chunk_particle_curve_disabled.js";
+import { chunk_particle_simulate_step } from "./chunk_particle_simulate_step.js";
+import { SIMULATE_SETTINGS } from "./shader_particle_simulate.js";
+
+/**
+ * The simulate pass over the WIDE register file — the fallback interpreter.
+ *
+ * Same simulation as {@link ./shader_particle_simulate.js}, down to the shared
+ * {@link ./chunk_particle_simulate_step.js}: one dispatch, every live particle, the emitter's UPDATE
+ * program, compaction into the alive and free lists. Two things differ, and both follow from the
+ * register file living in a storage buffer.
+ *
+ * ## The launch is bounded, and the loop is grid-stride
+ *
+ * The fast pass runs one invocation per particle and sizes its dispatch indirectly from
+ * `counters[ALIVE_IN]`. This one cannot: it needs a register file per invocation in flight, so
+ * one-lane-per-particle would size the register buffer by pool capacity — a gigabyte at a million
+ * particles.
+ *
+ * So it launches exactly {@link ../ParticleConstants.js PARTICLE_VM_WIDE_LAUNCH_LANES} lanes,
+ * whatever the particle count, and each walks `sim_list` in strides of that. The register buffer is
+ * then sized by a constant this engine chose rather than by a number the pool decides. There is no
+ * indirect command and no CPU-side count: the launch is fixed, and the loop bound is still the
+ * on-GPU `counters[ALIVE_IN]` snapshot, read in the shader exactly as before. Every guarantee the
+ * fast pass's sizing comment describes holds here for the same reason.
+ *
+ * The stride is a whole number of workgroups, which is what keeps the coherence pass's bucketing
+ * intact: each iteration covers a workgroup-aligned span of `sim_list`, so a wave still sees one
+ * program and the wave-uniform section decode is still sound. That decode is worth keeping even
+ * here — it is what makes the instruction fetch and the opcode switch scalar. Only the register
+ * indexing goes per-lane, because in this backing it always is.
+ *
+ * ## Nine storage buffers
+ *
+ * The fast passes fit in the eight a stage gets by default; this one adds `vm_registers` and needs
+ * nine. That is inside what the engine already demands of an adapter — {@link
+ * ../../Renderer.js} refuses one offering fewer than ten — so it costs no new capability, but it is
+ * why the particle system's "everything fits in eight" note does not cover this shader.
+ *
+ * @type {ComputeShader}
+ */
+
+/**
+ * Workgroups this pass dispatches. Constant: the launch does not depend on the particle count.
+ * @type {number}
+ */
+export const PARTICLE_SIMULATE_WIDE_WORKGROUP_COUNT =
+    PARTICLE_VM_WIDE_LAUNCH_LANES / PARTICLE_SIMULATE_WORKGROUP_SIZE;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', SIMULATE_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("scene_database", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
+    .addStorageBuffer("program", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, true)
+    .addStorageBuffer("sim_list", WebGPUArray.u32, false)
+    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("vm_registers", WebGPUArray.from(f32), true);
+
+
+const body = CodeChunk.from(/* language=wgsl */ `
+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>) {
+    // This invocation's column of the register file. The launch is exactly
+    // PARTICLE_VM_WIDE_LAUNCH_LANES wide, so gid.x is in range by construction — that is the whole
+    // reason the launch is bounded.
+    particle_vm_bind_registers(gid.x);
+
+    // The exact input length, snapshotted on-GPU last frame — never a stale CPU value.
+    let alive_in = atomicLoad(&counters[COUNTER_ALIVE_IN]);
+
+    for (var i = gid.x; i < alive_in; i = i + PARTICLE_VM_WIDE_LAUNCH_LANES) {
+        let slot = sim_list[i];
+
+        let verdict = particle_simulate_one(
+            &scene_database, &emitter_database, &program, &pool,
+            slot,
+            settings.u_dt, settings.u_time, settings.u_frame,
+        );
+
+        // A padding lane's verdict is SKIP and books nothing. Appending it would put the padding
+        // sentinel on the alive or the free list, and the free list would then hand 0xffffffff to a
+        // later emit as a record base.
+        if (verdict == PARTICLE_SIM_ALIVE) {
+            let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
+            alive_out[a] = slot;
+        } else if (verdict == PARTICLE_SIM_KILLED) {
+            let d = atomicAdd(&counters[COUNTER_DEAD], 1u);
+            dead[d] = slot;
+        }
+    }
+}
+`, [
+    chunk_particle_simulate_step,
+    chunk_particle_vm_registers_wide,
+    chunk_particle_curve_disabled,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+export const shader_particle_simulate_wide = ComputeShader.from({
+    label: "Particle Simulate (wide registers)",
+    resources,
+    body,
+});

package/src/shade/renderer/particles/shaders/shader_particle_spawn_commands.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The CPU's way in to GPU spawning: a list of `(emitter row, particle count)` pairs the host
+ * authored this frame, each added to that emitter's `pending` in the GPU-owned state table. The
+ * tick pass, which runs next, folds `pending` into the emitter's accumulator and decides the actual
+ * spawn count along with everything else.
+ *
+ * Deliberately a facade over the GPU path rather than a second path: a burst asked for here goes
+ * through the same budget, the same expansion and the same INIT program as the emitter's own rate,
+ * and is subject to the same culling. It is also the channel a VM opcode would use to spawn from
+ * the GPU — a sub-emitter or a trail would add to its target's `pending` the same way, with an
+ * atomic binding of its own since many threads would race one row.
+ *
+ * **One command per row.** The state table shares its buffer with the emitter table, bound as a
+ * plain `array<u32>`, so the add here is a read-modify-write and two commands naming one row would
+ * lose one of them. The host merges duplicates before upload ({@link GPUParticleSystem#spawn}),
+ * which is a few dozen entries at most and costs it nothing.
+ *
+ * The dispatch is sized by the host, because the host wrote the list and knows its length exactly;
+ * it is the one host-provided count in the frame that is not stale by construction.
+ *
+ * @type {ComputeShader}
+ */
+export const PARTICLE_SPAWN_COMMAND_WORKGROUP_SIZE: ComputeShader;
+export const shader_particle_spawn_commands: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_spawn_commands.d.ts.map

package/src/shade/renderer/particles/shaders/shader_particle_spawn_commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_spawn_commands.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_spawn_commands.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,oDAHU,aAAa,CAGiC;AA8BxD,2DAIG;8BA/D2B,+BAA+B"}

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

@@ -0,0 +1,66 @@
+import { 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_SPAWN_COMMAND_WORDS } from "../ParticleConstants.js";
+import { PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+
+/**
+ * The CPU's way in to GPU spawning: a list of `(emitter row, particle count)` pairs the host
+ * authored this frame, each added to that emitter's `pending` in the GPU-owned state table. The
+ * tick pass, which runs next, folds `pending` into the emitter's accumulator and decides the actual
+ * spawn count along with everything else.
+ *
+ * Deliberately a facade over the GPU path rather than a second path: a burst asked for here goes
+ * through the same budget, the same expansion and the same INIT program as the emitter's own rate,
+ * and is subject to the same culling. It is also the channel a VM opcode would use to spawn from
+ * the GPU — a sub-emitter or a trail would add to its target's `pending` the same way, with an
+ * atomic binding of its own since many threads would race one row.
+ *
+ * **One command per row.** The state table shares its buffer with the emitter table, bound as a
+ * plain `array<u32>`, so the add here is a read-modify-write and two commands naming one row would
+ * lose one of them. The host merges duplicates before upload ({@link GPUParticleSystem#spawn}),
+ * which is a few dozen entries at most and costs it nothing.
+ *
+ * The dispatch is sized by the host, because the host wrote the list and knows its length exactly;
+ * it is the one host-provided count in the frame that is not stale by construction.
+ *
+ * @type {ComputeShader}
+ */
+
+export const PARTICLE_SPAWN_COMMAND_WORKGROUP_SIZE = 64;
+
+const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+resources.setImmediate("u_count", u32);
+
+resources.createGroup()
+    .addStorageBuffer("commands", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, true);
+
+const body = CodeChunk.from(/* language=wgsl */ `
+const COMMAND_WORDS : u32 = ${PARTICLE_SPAWN_COMMAND_WORDS}u;
+
+@compute @workgroup_size(${PARTICLE_SPAWN_COMMAND_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= u_count) { return; }
+
+    let row = commands[i * COMMAND_WORDS];
+    let count = commands[i * COMMAND_WORDS + 1u];
+
+    var state = ${STATE.marshalling_method_read_rw}(&emitter_database, row);
+    state.pending = state.pending + count;
+    ${STATE.marshalling_method_write}(&emitter_database, row, state);
+}
+`, [STATE.chunk_read_rw, STATE.chunk_write]);
+
+export const shader_particle_spawn_commands = ComputeShader.from({
+    label: "Particle Spawn Commands",
+    resources,
+    body,
+});

package/src/shade/renderer/particles/sort/graph_particle_sort.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Frame-graph wiring for the RENDER order: the frame's alive list quantised by view depth and
+ * scattered back-to-front, into `gpu.sorted`, for a draw whose blending is order-dependent.
+ *
+ * reset -> histogram -> csdldf scan -> scatter. The two per-particle passes are indirect, sized by
+ * the same `sim_dispatch_args` the coherence reset wrote from the GPU's own alive count, so nothing
+ * here is sized by a host-side particle count.
+ *
+ * This is the ONLY producer of a depth ordering, and only {@link ParticleRenderMode.BILLBOARD} runs
+ * it. It must never be confused with the simulation order the coherence passes build (`coherence/`):
+ * that one groups by VM program so a wave runs one program, is camera-independent, and lives in a
+ * different buffer with a different counter slot. Depth-sorting it would destroy the coherence;
+ * running the padded coherence list through a blended draw would draw its sentinels.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {object} params.gpu the persistent buffers owned by {@link GPUParticleSystem}
+ * @param {GPUBuffer} params.gpu.sort_histogram `{count, elements}` bins for the CSDLDF scan
+ * @param {GPUBuffer} params.gpu.sort_cursor per-bin scatter cursor
+ * @param {GPUBuffer} params.gpu.sort_keys per-alive-entry depth bin
+ * @param {GPUBuffer} params.gpu.sorted the back-to-front slot list this produces
+ * @param {number} params.camera graph handle of the camera uniform buffer
+ * @param {number} params.emitter_database graph handle
+ * @param {number} params.pool graph handle of the particle pool
+ * @param {number} params.alive graph handle of this frame's compacted alive list
+ * @param {number} params.counters graph handle of the atomic counters
+ * @param {number} params.dispatch_args graph handle of one workgroup per live particle
+ * @param {number} params.bucket_count depth bins the sort quantises into
+ * @param {number} params.near view depth the first bin starts at
+ * @param {number} params.far view depth the last bin ends at
+ * @returns {number} graph handle of the sorted slot list
+ */
+export function graph_particle_sort({ graph, gpu, camera, emitter_database, pool, alive, counters, dispatch_args, bucket_count, near, far, }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    gpu: {
+        sort_histogram: GPUBuffer;
+        sort_cursor: GPUBuffer;
+        sort_keys: GPUBuffer;
+        sorted: GPUBuffer;
+    };
+    camera: number;
+    emitter_database: number;
+    pool: number;
+    alive: number;
+    counters: number;
+    dispatch_args: number;
+    bucket_count: number;
+    near: number;
+    far: number;
+}): number;
+//# sourceMappingURL=graph_particle_sort.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/graph_particle_sort.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH;IAjBqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,GAAG;QACI,cAAc;QACd,WAAW;QACX,SAAS;QACT,MAAM;;IACb,MAAM,EAArB,MAAM;IACS,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,aAAa,EAA5B,MAAM;IACS,YAAY,EAA3B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,GAAG,EAAlB,MAAM;IACJ,MAAM,CA2ElB"}

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

@@ -0,0 +1,120 @@
+import { assert } from "../../../../core/assert.js";
+import { align_4 } from "../../../../core/binary/align_4.js";
+import { graph_prefix_scan_csdldf } from "../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import { graph_compute_indirect_pass } from "../../shader/graph/compute/graph_compute_indirect_pass.js";
+import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
+import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
+import {
+    PARTICLE_SORT_WORKGROUP_SIZE,
+    shader_particle_sort_histogram,
+    shader_particle_sort_reset,
+    shader_particle_sort_scatter,
+} from "./shader_particle_sort.js";
+
+/**
+ * Frame-graph wiring for the RENDER order: the frame's alive list quantised by view depth and
+ * scattered back-to-front, into `gpu.sorted`, for a draw whose blending is order-dependent.
+ *
+ * reset -> histogram -> csdldf scan -> scatter. The two per-particle passes are indirect, sized by
+ * the same `sim_dispatch_args` the coherence reset wrote from the GPU's own alive count, so nothing
+ * here is sized by a host-side particle count.
+ *
+ * This is the ONLY producer of a depth ordering, and only {@link ParticleRenderMode.BILLBOARD} runs
+ * it. It must never be confused with the simulation order the coherence passes build (`coherence/`):
+ * that one groups by VM program so a wave runs one program, is camera-independent, and lives in a
+ * different buffer with a different counter slot. Depth-sorting it would destroy the coherence;
+ * running the padded coherence list through a blended draw would draw its sentinels.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {object} params.gpu the persistent buffers owned by {@link GPUParticleSystem}
+ * @param {GPUBuffer} params.gpu.sort_histogram `{count, elements}` bins for the CSDLDF scan
+ * @param {GPUBuffer} params.gpu.sort_cursor per-bin scatter cursor
+ * @param {GPUBuffer} params.gpu.sort_keys per-alive-entry depth bin
+ * @param {GPUBuffer} params.gpu.sorted the back-to-front slot list this produces
+ * @param {number} params.camera graph handle of the camera uniform buffer
+ * @param {number} params.emitter_database graph handle
+ * @param {number} params.pool graph handle of the particle pool
+ * @param {number} params.alive graph handle of this frame's compacted alive list
+ * @param {number} params.counters graph handle of the atomic counters
+ * @param {number} params.dispatch_args graph handle of one workgroup per live particle
+ * @param {number} params.bucket_count depth bins the sort quantises into
+ * @param {number} params.near view depth the first bin starts at
+ * @param {number} params.far view depth the last bin ends at
+ * @returns {number} graph handle of the sorted slot list
+ */
+export function graph_particle_sort({
+                                        graph,
+                                        gpu,
+                                        camera,
+                                        emitter_database,
+                                        pool,
+                                        alive,
+                                        counters,
+                                        dispatch_args,
+                                        bucket_count,
+                                        near,
+                                        far,
+                                    }) {
+    // The four buffers below are made on the first frame that sorts, not with the rest of the pool,
+    // because a system drawn through AVBOIT never sorts. Naming the missing one is worth a line:
+    // `graph_import_buffer` of an undefined buffer fails a long way from the cause.
+    for (const name of ["sort_histogram", "sort_cursor", "sort_keys", "sorted"]) {
+        assert.defined(gpu[name], `gpu.${name} — the render-order scratch was not allocated before the sort`);
+    }
+
+    let histogram = graph_import_buffer(graph, gpu.sort_histogram, "particles/sort_histogram");
+    let cursor = graph_import_buffer(graph, gpu.sort_cursor, "particles/sort_cursor");
+    let keys = graph_import_buffer(graph, gpu.sort_keys, "particles/sort_keys");
+    let sorted = graph_import_buffer(graph, gpu.sorted, "particles/sorted");
+
+    // The reset's widest loop is the scan header plus the bins rounded up to a whole vec4.
+    const reset_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count);
+
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_sort_reset,
+            bindings: { histogram, cursor, settings: { u_bucket_count: bucket_count } },
+            group_count: [Math.ceil(reset_words / PARTICLE_SORT_WORKGROUP_SIZE), 1, 1],
+        });
+        histogram = out.histogram;
+        cursor = out.cursor;
+    }
+
+    // The counters are only read here, but an atomic read needs a read_write binding, and the
+    // graph sees a write — so the handle is threaded through like any other.
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_sort_histogram,
+            bindings: {
+                camera, emitter_database, pool, alive, counters, keys, histogram,
+                settings: { u_near: near, u_far: far, u_bucket_count: bucket_count },
+            },
+            command: dispatch_args,
+        });
+        keys = out.keys;
+        histogram = out.histogram;
+        counters = out.counters;
+    }
+
+    const scanned = graph_prefix_scan_csdldf({
+        graph,
+        data: histogram,
+        element_max_count: bucket_count,
+    });
+
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_sort_scatter,
+            bindings: { keys, alive, scanned, counters, cursor, sorted },
+            command: dispatch_args,
+        });
+        sorted = out.sorted;
+    }
+
+    return sorted;
+}

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

@@ -1,6 +1,6 @@
 export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
 /**
- * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count)` threads, not over
+ * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count)` threads, not over
  * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
  * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
  * and the scan adds them in.

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":"AAsDA,8CAA+C;AAgD/C;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;AA0EH,2DAIG;AAyCH,yDAIG;8BA1O2B,+BAA+B"}
+{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAyDA,8CAA+C;AAgD/C;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;AAgEH,2DAIG;AAiCH,yDAIG;8BA3N2B,+BAA+B"}

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

@@ -5,9 +5,12 @@ import { ComputeShader } from "../../shader/ComputeShader.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
 import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
-import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_LAYOUT.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_STRUCT.js";
 import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+import { chunk_particle_header } from "../data/particle_header.js";
 
 /**
  * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
@@ -101,7 +104,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
 `);
 
 /**
- * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count)` threads, not over
+ * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count)` threads, not over
  * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
  * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
  * and the scan adds them in.
@@ -114,40 +117,32 @@ export const shader_particle_sort_reset = ComputeShader.from({
     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;
+ * Per-dispatch, 12 bytes, read-only. Separate uniforms meant a transient buffer each per sort;
  * WGSL allows one immediate per entry point, so they travel together.
  *
+ * The particle count is NOT here: it is the alive counter the simulate pass finished writing on
+ * the GPU, read from the counters buffer. A host-supplied count would be last frame's.
+ *
  * @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)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
     .addStorageBuffer("pool", WebGPUArray.u32, false)
     .addStorageBuffer("alive", WebGPUArray.u32, false)
-    .addStorageBuffer("view_matrix", WebGPUArray.u32, false)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true) // atomics require a read_write binding even for atomicLoad
     .addStorageBuffer("keys", WebGPUArray.u32, true)
     .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true);
 const histogram_body = CodeChunk.from(/* wgsl */ `
@@ -155,18 +150,17 @@ ${COMMON}
 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}
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
 
 @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; }
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { 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);
+    let emitter_index = particle_header_emitter(pool[base + PARTICLE_HEADER_EMITTER]);
+    let em = particle_emitter_read(&emitter_database, emitter_index);
 
     var world_pos = vec3<f32>(0.0);
     if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) {
@@ -174,8 +168,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
         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 view_depth = -(camera.view_matrix * 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);
@@ -184,7 +177,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     keys[i] = bucket;
     atomicAdd(&histogram[SORT_HEADER_WORDS + bucket], 1u);
 }
-`, [chunk_particle_emitter]);
+`, [chunk_particle_emitter, chunk_particle_header]);
 
 export const shader_particle_sort_histogram = ComputeShader.from({
     label: "Particle Sort Histogram",
@@ -194,31 +187,23 @@ export const shader_particle_sort_histogram = ComputeShader.from({
 
 // --- 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("counters", WebGPUArray.from(atomic_u32), true) // atomics require a read_write binding even for atomicLoad
     .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
     .addStorageBuffer("sorted", WebGPUArray.u32, true);
 const scatter_body = CodeChunk.from(/* wgsl */ `
 ${COMMON}
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
 
 @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; }
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
 
     let bucket = keys[i];
 

package/src/shade/renderer/particles/vm/PARTICLE_VM_CONTEXT_STRUCT.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Per-invocation builtin inputs the host assembles before running a program.
+ */
+export const PARTICLE_VM_CONTEXT_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=PARTICLE_VM_CONTEXT_STRUCT.d.ts.map

package/src/shade/renderer/particles/vm/PARTICLE_VM_CONTEXT_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PARTICLE_VM_CONTEXT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/PARTICLE_VM_CONTEXT_STRUCT.js"],"names":[],"mappings":"AAGA;;GAEG;AACH,sDASU;6BAdmB,mCAAmC"}

package/src/shade/renderer/particles/vm/PARTICLE_VM_CONTEXT_STRUCT.js

@@ -0,0 +1,16 @@
+import { f32, vec3f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Per-invocation builtin inputs the host assembles before running a program.
+ */
+export const PARTICLE_VM_CONTEXT_STRUCT = WebGPUStruct.from({
+    delta_time: f32,
+    emitter_age: f32,
+    time: f32,
+    spawn_fraction: f32,
+    particle_index: f32,
+    emitter_position: vec3f,
+    emitter_direction: vec3f,
+    emitter_up: vec3f,
+}).pack();

package/src/shade/renderer/particles/vm/ParticleVMReference.d.ts

@@ -24,12 +24,15 @@ export function u32_to_unit_f32(u: number): number;
  * particle asked to be destroyed and the advanced RNG state so the caller can persist it.
  *
  * This is the CPU reference semantics — the WGSL interpreter is written to match it exactly, and the
- * parity spec cross-checks them.
+ * parity spec cross-checks them. The shape is the interpreter's: every source is resolved, lane by
+ * lane as far as the opcode reads it, before the opcode runs, and the destination is written after,
+ * so a source may overlap the destination in any way and still mean what it held before the
+ * instruction.
  *
  * @param {object} params
  * @param {Uint32Array} params.words instruction words for the section (SPAWN or UPDATE)
- * @param {Float32Array} params.constants constant pool (4 floats per entry)
- * @param {number} params.register_count
+ * @param {Float32Array} params.constants constant pool, one float per word
+ * @param {number} params.register_count size of the register file in `f32` slots
  * @param {Uint32Array} params.record particle record words (mutated in place); attributes are f32 bits
  * @param {number[][]} [params.builtins] builtin values indexed by {@link VM_BUILTIN} id, each a 4-array
  * @param {number} [params.rng_state] initial RNG state (u32)

package/src/shade/renderer/particles/vm/ParticleVMReference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleVMReference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/ParticleVMReference.js"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,gCAHW,MAAM;WACK,MAAM;WAAS,MAAM;EAW1C;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH;WATW,WAAW;eACX,YAAY;oBACZ,MAAM;YACN,WAAW;eACX,MAAM,EAAE,EAAE;gBACV,MAAM;2BACG,MAAM,KAAK,MAAM,KAAK,MAAM;;YACzB,OAAO;eAAa,MAAM;EAoPhD"}
+{"version":3,"file":"ParticleVMReference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/ParticleVMReference.js"],"names":[],"mappings":"AA0BA;;;;;;;GAOG;AACH,gCAHW,MAAM;WACK,MAAM;WAAS,MAAM;EAW1C;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAqED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;WATW,WAAW;eACX,YAAY;oBACZ,MAAM;YACN,WAAW;eACX,MAAM,EAAE,EAAE;gBACV,MAAM;2BACG,MAAM,KAAK,MAAM,KAAK,MAAM;;YACzB,OAAO;eAAa,MAAM;EA+RhD"}