@woosh/meep-engine 3.16.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/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/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,7 +24,10 @@ 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)

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":"AAWA;;;;;;;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;EA2PhD"}
+{"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"}