@woosh/meep-engine 3.14.5 → 3.15.0

package/src/shade/renderer/particles/coherence/graph_particle_bucket.js

@@ -0,0 +1,179 @@
+import { assert } from "../../../../core/assert.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 {
+    PREFIX_SCAN_CSDLDF_HEADER_WORDS,
+} from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import { graph_prefix_scan_csdldf } from "../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "../ParticleConstants.js";
+import {
+    shader_particle_bucket_fill,
+    shader_particle_bucket_histogram,
+    shader_particle_bucket_pad,
+    shader_particle_bucket_reset,
+    shader_particle_bucket_scatter,
+} from "./shader_particle_bucket.js";
+
+/**
+ * Frame-graph wiring for the simulation-order bucketing: turns the frame's freshly compacted alive
+ * list into the program-coherent, workgroup-padded list NEXT frame's simulate consumes.
+ *
+ * Runs at the end of the frame, after emit and simulate have both finished appending to the alive
+ * list and before the build-indirect pass, which reads the padded length this produces
+ * ({@link PARTICLE_COUNTER.SIM_PADDED}) and turns it into next frame's dispatch args and bound.
+ *
+ * Six passes, the middle one being `graph_prefix_scan_csdldf` reused unchanged — the same scan the
+ * radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan in this
+ * codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so the pass
+ * makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here would be
+ * a second place to get that wrong.
+ *
+ * Nothing on this path reads back to the CPU. The only host-supplied number is `bucket_count`, and
+ * that is static topology — it changes when the emitter set does, never as particles are born and
+ * die. The per-frame quantities (the alive count, the bin sizes, the padded total) are produced and
+ * consumed entirely on the GPU, including the dispatch size of the two per-particle passes, which
+ * the reset pass writes into `sim_dispatch_args` from the GPU's own alive count.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {object} params.gpu persistent buffers owned by the feature (GPUBuffer instances)
+ * @param {GPUBuffer} params.gpu.sim_list the padded, program-coherent index list this produces
+ * @param {GPUBuffer} params.gpu.sim_keys per-alive-entry program id
+ * @param {GPUBuffer} params.gpu.sim_histogram `{count, elements}` bins for the CSDLDF scan
+ * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
+ * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
+ * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
+ * @param {number} params.emitters graph handle of the packed emitter records
+ * @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.sim_list graph handle of the list this rewrites. Passed in rather than
+ *   imported here because the simulate pass reads it earlier in the same frame: importing the same
+ *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
+ *   and the write end up on separate dependency chains
+ * @param {number} params.bucket_count number of distinct compiled programs
+ * @returns {{counters: number, sim_list: number}} the threaded handles downstream passes must read
+ */
+export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, counters, sim_list, bucket_count }) {
+    assert.defined(graph, "graph");
+    assert.isPositiveInteger(bucket_count, "bucket_count");
+    assert.isNonNegativeInteger(sim_list, "sim_list");
+
+    // Sized from the bucket count, which only changes when the emitter set does — so a caller that
+    // added an emitter and did not reallocate gets told here rather than scattering out of bounds.
+    const bin_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count);
+    assert.greaterThanOrEqual(gpu.sim_histogram.size, bin_words * Uint32Array.BYTES_PER_ELEMENT, "sim_histogram is too small for the bucket count");
+    assert.greaterThanOrEqual(gpu.sim_cursor.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_cursor is too small for the bucket count");
+    assert.greaterThanOrEqual(gpu.sim_bucket_counts.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_bucket_counts is too small for the bucket count");
+
+    // Every buffer a pass WRITES must be THREADED: the write returns a renamed (versioned) handle
+    // and the next pass must read THAT one. Reading the original import instead leaves the ordering
+    // between the two passes unexpressed — the graph's own validator rejects it, because both
+    // versions name one piece of memory and the stale-looking read silently returns the new
+    // contents.
+    let keys = graph_import_buffer(graph, gpu.sim_keys, "particles/sim_keys");
+    let histogram = graph_import_buffer(graph, gpu.sim_histogram, "particles/sim_histogram");
+    let cursor = graph_import_buffer(graph, gpu.sim_cursor, "particles/sim_cursor");
+    let bucket_counts = graph_import_buffer(graph, gpu.sim_bucket_counts, "particles/sim_bucket_counts");
+    let dispatch_args = graph_import_buffer(graph, gpu.sim_dispatch_args, "particles/sim_dispatch_args");
+
+    // 0. Clear the bins and cursors, write the scan's {count} header, and size the two per-particle
+    //    passes below from the GPU's own alive count.
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_bucket_reset,
+            bindings: { counters, histogram, cursor, sim_dispatch_args: dispatch_args, u_bucket_count: bucket_count },
+            group_count: [reset_group_count(bucket_count), 1, 1],
+        });
+        counters = out.counters;
+        histogram = out.histogram;
+        cursor = out.cursor;
+        dispatch_args = out.sim_dispatch_args;
+    }
+
+    // 1. One bin per PROGRAM. Indirect, because the thread count is the alive count.
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_bucket_histogram,
+            bindings: { emitters, pool, alive, keys, histogram, counters },
+            command: dispatch_args,
+        });
+        keys = out.keys;
+        histogram = out.histogram;
+        counters = out.counters;
+    }
+
+    // 2. Round every bin up to a whole workgroup BEFORE the scan — that is what puts each bucket
+    //    boundary on a wave boundary rather than in the middle of one.
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_bucket_pad,
+            bindings: { histogram, bucket_counts, u_bucket_count: bucket_count },
+            group_count: [Math.ceil(bucket_count / PARTICLE_SIMULATE_WORKGROUP_SIZE), 1, 1],
+        });
+        histogram = out.histogram;
+        bucket_counts = out.bucket_counts;
+    }
+
+    // 3. Inclusive prefix sums of the padded bins, in place.
+    const scanned = graph_prefix_scan_csdldf({
+        graph,
+        data: histogram,
+        element_max_count: bucket_count,
+    });
+
+    // 4. Place each alive entry at its bucket's offset plus an atomic rank.
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_bucket_scatter,
+            bindings: { keys, alive, scanned, cursor, sim_list, counters },
+            command: dispatch_args,
+        });
+        cursor = out.cursor;
+        sim_list = out.sim_list;
+        counters = out.counters;
+    }
+
+    // 5. Stamp the padding sentinel into each bucket's tail and publish the padded total. One
+    //    workgroup per bucket: padding is at most a workgroup less one entry, and a bucket whose
+    //    particles all died has no scatter thread to ride along with.
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_bucket_fill,
+            bindings: { bucket_counts, scanned, sim_list, counters, u_bucket_count: bucket_count },
+            group_count: [bucket_count, 1, 1],
+        });
+        sim_list = out.sim_list;
+        counters = out.counters;
+    }
+
+    return { counters, sim_list };
+}
+
+/**
+ * Workgroups the reset pass needs to cover its widest loop — the scan header plus the bins, rounded
+ * up to the whole `vec4` the last bin lands in (the scan reads whole `vec4`s, so the tail has to be
+ * cleared too or garbage joins the sums).
+ *
+ * @param {number} bucket_count
+ * @returns {number}
+ */
+function reset_group_count(bucket_count) {
+    const words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count);
+
+    return Math.ceil(words / PARTICLE_SIMULATE_WORKGROUP_SIZE);
+}
+
+/**
+ * @param {number} value
+ * @returns {number} `value` rounded up to a multiple of four — the scan reads whole `vec4`s
+ */
+function round_up_4(value) {
+    return (value + 3) & ~3;
+}

package/src/shade/renderer/particles/coherence/particle_program_buckets.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Round `value` up to a multiple of {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}.
+ *
+ * Mirrors the WGSL, which does this with a mask rather than a divide — see
+ * {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} for why.
+ *
+ * @param {number} value
+ * @returns {number}
+ */
+export function particle_bucket_round_up(value: number): number;
+/**
+ * @typedef {object} ParticleProgramBucketLayout
+ * @property {number[]} counts particles per program, before padding
+ * @property {number[]} padded_counts each count rounded up to a whole workgroup
+ * @property {number[]} offsets first index of each program's run in the padded list
+ * @property {number} total length of the padded list — what sizes the simulate dispatch
+ */
+/**
+ * Bucket sizes and start offsets, exactly as the GPU derives them: an atomic histogram, a round-up
+ * of each bin to a whole workgroup, and an exclusive prefix sum of the *padded* bins (the GPU takes
+ * that sum from `graph_prefix_scan_csdldf`, the same scan the radix sort runs its spine through).
+ *
+ * A program with no particles contributes nothing: `round_up(0)` is 0, so empty buckets neither
+ * consume a workgroup nor shift the offsets of the buckets after them.
+ *
+ * @param {ArrayLike<number>} programs program id of each alive entry
+ * @param {number} program_count number of distinct programs (the bucket count)
+ * @returns {ParticleProgramBucketLayout}
+ */
+export function particle_program_bucket_layout(programs: ArrayLike<number>, program_count: number): ParticleProgramBucketLayout;
+/**
+ * The simulate pass's input list: pool slot indices grouped by program, each group padded out to a
+ * workgroup boundary with {@link PARTICLE_SIM_PAD_SLOT}.
+ *
+ * Order within a bucket is arrival order here and arbitrary on the GPU (the scatter takes its rank
+ * from an atomic), which is fine — nothing downstream depends on the order of particles running the
+ * same program.
+ *
+ * @param {ArrayLike<number>} slots pool slot index of each alive entry
+ * @param {ArrayLike<number>} programs program id of each alive entry, parallel to `slots`
+ * @param {number} program_count number of distinct programs (the bucket count)
+ * @returns {number[]} the padded, program-coherent indirection list
+ */
+export function particle_program_bucket_list(slots: ArrayLike<number>, programs: ArrayLike<number>, program_count: number): number[];
+export type ParticleProgramBucketLayout = {
+    /**
+     * particles per program, before padding
+     */
+    counts: number[];
+    /**
+     * each count rounded up to a whole workgroup
+     */
+    padded_counts: number[];
+    /**
+     * first index of each program's run in the padded list
+     */
+    offsets: number[];
+    /**
+     * length of the padded list — what sizes the simulate dispatch
+     */
+    total: number;
+};
+//# sourceMappingURL=particle_program_buckets.d.ts.map

package/src/shade/renderer/particles/coherence/particle_program_buckets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_program_buckets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/particle_program_buckets.js"],"names":[],"mappings":"AAwCA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,yDAJW,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,2BAA2B,CAkBvC;AAED;;;;;;;;;;;;GAYG;AACH,oDALW,UAAU,MAAM,CAAC,YACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,MAAM,EAAE,CAapB;;;;;YA5Da,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;aACR,MAAM,EAAE;;;;WACR,MAAM"}

package/src/shade/renderer/particles/coherence/particle_program_buckets.js

@@ -0,0 +1,116 @@
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_SIM_PAD_SLOT } from "../ParticleConstants.js";
+
+/**
+ * CPU reference for the simulation-order bucketing — the readable statement of the answer the GPU
+ * passes in {@link ./shader_particle_bucket.js} have to produce, the same role
+ * {@link ../sort/particle_counting_sort.js} plays for the render-order depth sort.
+ *
+ * ## What it is for
+ *
+ * The simulate pass is one dispatch interpreting every emitter's compiled UPDATE bytecode over the
+ * whole alive list. The alive list comes out of compaction — survivors are appended with
+ * `atomicAdd(&counters[ALIVE])` — so its order says nothing about which emitter a particle belongs
+ * to, and a single wave routinely holds particles running different programs. That costs twice
+ * over: the interpreter's opcode `switch` diverges, so the wave serially executes the union of the
+ * opcodes its lanes want; and the VM register file is dynamically indexed, which on AMD compiles to
+ * a `v_movrels`/`v_movreld` waterfall whose trip count is the number of *distinct* register indices
+ * live in the wave.
+ *
+ * Grouping the list by program collapses both. Padding each group out to
+ * {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} is what makes the grouping actually hold at wave
+ * granularity: an unpadded boundary lands mid-wave and that wave spans two programs again.
+ *
+ * ## What it is NOT
+ *
+ * This is the *simulation* order: camera-independent, changing only when emitters and their
+ * programs change. It is a different ordering from the *render* order in `../sort/`, which is
+ * back-to-front by view depth and exists so premultiplied transparency composites correctly. The
+ * two must stay in separate buffers and separate passes — reordering the render list for coherence
+ * breaks transparency, and depth-sorting the simulation list destroys the coherence.
+ *
+ * ## Indirection only
+ *
+ * Everything here permutes *indices into the pool*. Particle records never move: a slot is
+ * referenced by the dead (free) list and by the alive list across frames, so relocating a record
+ * would leave both pointing at the wrong particle.
+ */
+
+/** @type {number} bucket granularity — one whole simulate workgroup, and so at least one whole wave */
+const WG = PARTICLE_SIMULATE_WORKGROUP_SIZE;
+
+/**
+ * Round `value` up to a multiple of {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}.
+ *
+ * Mirrors the WGSL, which does this with a mask rather than a divide — see
+ * {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} for why.
+ *
+ * @param {number} value
+ * @returns {number}
+ */
+export function particle_bucket_round_up(value) {
+    return (value + (WG - 1)) & ~(WG - 1);
+}
+
+/**
+ * @typedef {object} ParticleProgramBucketLayout
+ * @property {number[]} counts particles per program, before padding
+ * @property {number[]} padded_counts each count rounded up to a whole workgroup
+ * @property {number[]} offsets first index of each program's run in the padded list
+ * @property {number} total length of the padded list — what sizes the simulate dispatch
+ */
+
+/**
+ * Bucket sizes and start offsets, exactly as the GPU derives them: an atomic histogram, a round-up
+ * of each bin to a whole workgroup, and an exclusive prefix sum of the *padded* bins (the GPU takes
+ * that sum from `graph_prefix_scan_csdldf`, the same scan the radix sort runs its spine through).
+ *
+ * A program with no particles contributes nothing: `round_up(0)` is 0, so empty buckets neither
+ * consume a workgroup nor shift the offsets of the buckets after them.
+ *
+ * @param {ArrayLike<number>} programs program id of each alive entry
+ * @param {number} program_count number of distinct programs (the bucket count)
+ * @returns {ParticleProgramBucketLayout}
+ */
+export function particle_program_bucket_layout(programs, program_count) {
+    const counts = new Array(program_count).fill(0);
+    for (let i = 0; i < programs.length; i++) {
+        counts[programs[i]]++;
+    }
+
+    const padded_counts = counts.map(particle_bucket_round_up);
+
+    const offsets = new Array(program_count);
+    let total = 0;
+    for (let b = 0; b < program_count; b++) {
+        offsets[b] = total;
+        total += padded_counts[b];
+    }
+
+    return { counts, padded_counts, offsets, total };
+}
+
+/**
+ * The simulate pass's input list: pool slot indices grouped by program, each group padded out to a
+ * workgroup boundary with {@link PARTICLE_SIM_PAD_SLOT}.
+ *
+ * Order within a bucket is arrival order here and arbitrary on the GPU (the scatter takes its rank
+ * from an atomic), which is fine — nothing downstream depends on the order of particles running the
+ * same program.
+ *
+ * @param {ArrayLike<number>} slots pool slot index of each alive entry
+ * @param {ArrayLike<number>} programs program id of each alive entry, parallel to `slots`
+ * @param {number} program_count number of distinct programs (the bucket count)
+ * @returns {number[]} the padded, program-coherent indirection list
+ */
+export function particle_program_bucket_list(slots, programs, program_count) {
+    const layout = particle_program_bucket_layout(programs, program_count);
+
+    const list = new Array(layout.total).fill(PARTICLE_SIM_PAD_SLOT);
+
+    const cursor = layout.offsets.slice();
+    for (let i = 0; i < slots.length; i++) {
+        list[cursor[programs[i]]++] = slots[i];
+    }
+
+    return list;
+}

package/src/shade/renderer/particles/coherence/shader_particle_bucket.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Per-frame reset, and the only place the bucketing decides how big it is.
+ *
+ * WebGPU zero-fills a buffer on CREATION only, so without this the scan would consume last frame's
+ * bins and the scatter would compound last frame's ranks.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_reset: ComputeShader;
+/**
+ * One bin per PROGRAM, not per emitter: emitters compiled from the same graph share a program id
+ * (see {@link ../runtime/ProgramArena.js}) and belong in one wave-coherent run. Keying on the
+ * emitter index would split a run that was already coherent into one padded bucket per emitter.
+ *
+ * The emitter's program id is read by direct indexing rather than through
+ * `particle_emitter_read` — decoding a whole 41-word record, transform matrix included, to reach one
+ * word would be pure waste in a pass that touches every live particle.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_histogram: ComputeShader;
+/**
+ * Round every bin up to a whole workgroup, keeping the raw count in `bucket_counts` for the fill
+ * pass (which needs to know where the real entries stop and the padding starts).
+ *
+ * This is THE step that makes the bucketing worth doing. Scanning the raw counts would put a
+ * bucket boundary at an arbitrary index, and the wave straddling it would span two programs again —
+ * the exact divergence the pass exists to remove. An empty bin rounds up to zero, so a program with
+ * no live particles costs no lanes and shifts nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_pad: ComputeShader;
+/**
+ * Place each alive entry's pool slot at its bucket's exclusive offset plus an atomic rank.
+ *
+ * Order within a bucket is therefore arbitrary, which is exactly as much order as the simulation
+ * needs: every lane in the bucket runs the same program, so which of them runs where changes
+ * nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_scatter: ComputeShader;
+/**
+ * Stamp the padding sentinel into the tail of every bucket, and publish the padded total.
+ *
+ * Dispatched over one workgroup per bucket — a bucket's padding is at most `BUCKET_ALIGNMENT - 1`
+ * entries, so a workgroup always covers it. It cannot ride along with the scatter, which has no
+ * thread at all for a bucket whose particles all died.
+ *
+ * The padded total is the last bucket's inclusive scan value. It, and not the alive count, is what
+ * sizes next frame's simulate dispatch — the build-indirect pass reads it out of
+ * {@link PARTICLE_COUNTER.SIM_PADDED}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_fill: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_bucket.d.ts.map

package/src/shade/renderer/particles/coherence/shader_particle_bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/shader_particle_bucket.js"],"names":[],"mappings":"AAwGA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAyBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BArV2B,+BAA+B"}