@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/graph_particles.d.ts

@@ -1,15 +1,28 @@
 /**
- * Per-frame frame-graph contribution for the GPU particle system — the reference wiring an
- * integrator (e.g. Renderer.render) calls once the CPU {@link GPUParticleSystem#update} has produced
- * this frame's spawn requests.
+ * The simulation half of the particle system's frame, recorded into the frame graph.
+ * {@link GPUParticleSystem#execute} is what calls it, with the buffers it owns; nothing else needs
+ * to.
  *
- * The passes run in dependency order:
+ * {@link graph_particles_simulate} is everything that moves particles:
  *
- *   reset counters -> emit (spawn) -> simulate (advance + compact) -> bucket -> build indirect args
+ *   reset counters -> spawn commands -> emitter tick -> scan -> spawn args -> emit -> simulate
+ *   -> bucket -> build indirect
  *
- * with the depth sort + billboard render appended by the caller (the render pass needs the frame's
- * colour + depth attachments, which live in the caller's graph). Alive lists ping-pong by frame
- * parity: `alive_write` receives this frame's survivors + newborns.
+ * and it leaves the frame's alive list, the pool and the indirect draw args as graph handles for
+ * whoever draws. Nothing here depends on how they will be drawn, which is why the render mode
+ * ({@link ParticleRenderMode}) selects only what `execute` records AFTER this: the depth sort and
+ * the billboard draw (`sort/graph_particle_sort.js`, `graph_particles_billboard.js`), or nothing at
+ * all, because the AVBOIT orchestrator will draw them later off these same handles
+ * (`graph_particles_avboit.js`).
+ *
+ * ## Spawning is decided here, on the GPU
+ *
+ * The emitter tick runs one thread per emitter row and writes each row's spawn count for the
+ * frame; a prefix scan turns the counts into offsets; a one-thread pass turns the scan's total into
+ * the emit dispatch; and the emit pass runs one thread per newborn, each locating its emitter in the
+ * scan. The host contributes two numbers to all of that: the table's element capacity, which sizes
+ * the scan, and the length of the spawn-command list it authored itself. Neither is a count of
+ * anything alive.
  *
  * ## Two orderings, kept apart
  *
@@ -19,90 +32,106 @@
  * ordering is camera-independent and changes only when emitters or their programs change.
  *
  * The RENDER ordering — back-to-front by view depth, from `sort/` — is a different list in a
- * different buffer, produced by different passes, and the billboard draw is what consumes it.
- * Reordering the render list for coherence would break premultiplied transparency; depth-sorting the
- * simulation list would destroy the coherence. They share no buffer and no counter slot.
+ * different buffer, produced by different passes, and the standalone billboard draw is the only
+ * thing that consumes it, so it is built only in that mode. Reordering the render list for
+ * coherence would break premultiplied transparency; depth-sorting the simulation list would destroy
+ * the coherence. They share no buffer and no counter slot.
  *
- * The simulate pass is fully GPU-driven: its workgroup count comes from `dispatch_args` (written by
- * LAST frame's build-indirect pass) via `dispatchWorkgroupsIndirect`, and its element bound comes
- * from the `ALIVE_IN` counter snapshot — never from a CPU count. Both are derived from one value,
- * the padded list length, so the thread count and the bound agree by construction. A CPU count is
- * inevitably stale and corrupts the pool (orphaned slots when the population grows, double-freed
- * slots when it shrinks). Only the spawn count is CPU-provided, because the CPU authored the
- * spawn-request list and knows its exact length. The caller renders with `drawIndirect(draw_args)`,
- * which build-indirect writes THIS frame, so the instance count is exact too.
+ * ## Nothing is sized from the CPU
+ *
+ * Simulate's workgroup count comes from `dispatch_args` (written by LAST frame's build-indirect
+ * pass) via `dispatchWorkgroupsIndirect`, and its element bound from the `ALIVE_IN` counter
+ * snapshot; the draw, and the sort's two per-particle passes when there is a sort, are sized the
+ * same way, from this frame's alive count. A CPU count is inevitably stale and corrupts the pool
+ * (orphaned slots when the population grows, double-freed slots when it shrinks).
  *
  * All persistent buffers are imported (owned by the feature, not the graph). Writing an imported
  * buffer marks the pass a side-effect so it always executes, and returns a renamed handle downstream
- * passes must read — exactly the ReSTIR reservoir pattern.
+ * passes must read — exactly the ReSTIR reservoir pattern. Every persistent buffer is imported
+ * exactly once: two imports of one buffer are two resource entries the graph cannot tell apart.
  *
  * On the very first frame `dispatch_args` must be zero-initialised (WebGPU zero-fills new buffers)
  * and the `ALIVE_IN` counter 0, so simulate is a no-op until the first build-indirect has run.
+ */
+/**
+ * @typedef {object} ParticleSimulationHandles
+ * @property {number} pool the particle pool, after this frame's INIT and UPDATE
+ * @property {number} alive this frame's compacted alive list — the render order's input
+ * @property {number} counters the atomic counters, after build-indirect
+ * @property {number} draw_args the billboard draw's indirect args: six vertices, one instance per live particle
+ * @property {number} sim_dispatch_args one workgroup per live particle, for a per-particle pass
+ * @property {number} emitter_database the emitter database, after the tick wrote its state rows
+ */
+/**
+ * Everything that moves particles, up to the indirect args a draw consumes.
  *
  * @param {object} params
  * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
- * @param {object} params.gpu handles/objects for the persistent buffers (GPUBuffer instances)
- * @param {GPUBuffer} params.gpu.emitters
- * @param {GPUBuffer} params.gpu.program
- * @param {GPUBuffer} params.gpu.constants
- * @param {GPUBuffer} params.gpu.pool
- * @param {GPUBuffer} params.gpu.alive_read the other half of the ping-pong. These passes no longer
- *   read it — simulate's input is `sim_list` — but the caller keeps swapping the two so this frame's
- *   render is not read-after-written by next frame's emit, which would serialise them
- * @param {GPUBuffer} params.gpu.alive_write this-frame alive list: survivors + newborns
- * @param {GPUBuffer} params.gpu.dead free-list stack
- * @param {GPUBuffer} params.gpu.counters atomic counters
- * @param {GPUBuffer} params.gpu.spawn_requests
- * @param {GPUBuffer} params.gpu.dispatch_args indirect simulate dispatch (usage must include INDIRECT)
- * @param {GPUBuffer} params.gpu.draw_args indirect billboard draw (usage must include INDIRECT)
- * @param {GPUBuffer} params.gpu.sim_list program-coherent simulate input, rebuilt here for next frame
- * @param {GPUBuffer} params.gpu.sim_keys see {@link graph_particle_bucket}
- * @param {GPUBuffer} params.gpu.sim_histogram see {@link graph_particle_bucket}
- * @param {GPUBuffer} params.gpu.sim_bucket_counts see {@link graph_particle_bucket}
- * @param {GPUBuffer} params.gpu.sim_cursor see {@link graph_particle_bucket}
- * @param {GPUBuffer} params.gpu.sim_dispatch_args see {@link graph_particle_bucket} (usage must include INDIRECT)
- * @param {number} params.capacity pool capacity in particles (bounds the emit pass's free-list pops)
- * @param {number} params.bucket_count distinct compiled programs — `GPUParticleSystem#bucketCount()`
+ * @param {number} params.camera graph handle of the view's camera uniform (`CAMERA_UNIFORM_STRUCT`)
+ * @param {number} params.scene_database graph handle of the scene database — the emitters' nodes
+ * @param {object} params.gpu the persistent buffers, see {@link GPUParticleSystem}
+ * @param {object} params.emitters the emitter table's shape this frame
+ * @param {number} params.emitters.capacity the table's element capacity — the length of the count
+ *   list the scan consumes
+ * @param {number} params.emitters.group_count workgroups the tick needs to walk every page group
+ * @param {number} params.capacity pool capacity in particles
+ * @param {number} params.bucket_count simulation-order buckets, one per program id the registry
+ *   can hand out — `GPUParticleSystem#bucketCount()`
+ * @param {boolean} params.wide_registers run the VM over the wide (storage-backed) register file
+ *   because some registered effect needs more slots than the fast interpreter's file holds. A
+ *   whole-system choice, not a per-emitter one — see `runtime/ProgramHeap.js`.
  * @param {object} params.frame per-frame scalars
  * @param {number} params.frame.dt
  * @param {number} params.frame.time
  * @param {number} params.frame.index
- * @param {number} params.frame.spawn_count number of spawn requests this frame (CPU-authored, exact)
+ * @param {number} params.frame.max_catchup seconds of missed spawning a woken emitter makes up
+ * @param {number} params.frame.spawn_command_count entries in `gpu.spawn_commands` this frame
+ * @returns {ParticleSimulationHandles}
  */
-export function graph_particles({ graph, gpu, capacity, bucket_count, frame }: {
+export function graph_particles_simulate({ graph, camera, scene_database, gpu, emitters, capacity, bucket_count, wide_registers, frame, }: {
     graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
-    gpu: {
-        emitters: GPUBuffer;
-        program: GPUBuffer;
-        constants: GPUBuffer;
-        pool: GPUBuffer;
-        alive_read: GPUBuffer;
-        alive_write: GPUBuffer;
-        dead: GPUBuffer;
-        counters: GPUBuffer;
-        spawn_requests: GPUBuffer;
-        dispatch_args: GPUBuffer;
-        draw_args: GPUBuffer;
-        sim_list: GPUBuffer;
-        sim_keys: GPUBuffer;
-        sim_histogram: GPUBuffer;
-        sim_bucket_counts: GPUBuffer;
-        sim_cursor: GPUBuffer;
-        sim_dispatch_args: GPUBuffer;
+    camera: number;
+    scene_database: number;
+    gpu: object;
+    emitters: {
+        capacity: number;
+        group_count: number;
     };
     capacity: number;
     bucket_count: number;
+    wide_registers: boolean;
     frame: {
         dt: number;
         time: number;
         index: number;
-        spawn_count: number;
+        max_catchup: number;
+        spawn_command_count: number;
     };
-}): {
-    alive: any;
-    pool: any;
-    counters: any;
-    dispatch_args: any;
-    draw_args: any;
+}): ParticleSimulationHandles;
+export type ParticleSimulationHandles = {
+    /**
+     * the particle pool, after this frame's INIT and UPDATE
+     */
+    pool: number;
+    /**
+     * this frame's compacted alive list — the render order's input
+     */
+    alive: number;
+    /**
+     * the atomic counters, after build-indirect
+     */
+    counters: number;
+    /**
+     * the billboard draw's indirect args: six vertices, one instance per live particle
+     */
+    draw_args: number;
+    /**
+     * one workgroup per live particle, for a per-particle pass
+     */
+    sim_dispatch_args: number;
+    /**
+     * the emitter database, after the tick wrote its state rows
+     */
+    emitter_database: number;
 };
 //# sourceMappingURL=graph_particles.d.ts.map

package/src/shade/renderer/particles/graph_particles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_particles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH;IA7BkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,GAAG;QACI,QAAQ;QACR,OAAO;QACP,SAAS;QACT,IAAI;QACJ,UAAU;QAGV,WAAW;QACX,IAAI;QACJ,QAAQ;QACR,cAAc;QACd,aAAa;QACb,SAAS;QACT,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU;QACV,iBAAiB;;IACxB,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IACS,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACe,WAAW,EAAhC,MAAM;;;;;;;;EAwGhB"}
+{"version":3,"file":"graph_particles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles.js"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAtBkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,MAAM,EAArB,MAAM;IACS,cAAc,EAA7B,MAAM;IACS,GAAG,EAAlB,MAAM;IACS,QAAQ;QACC,QAAQ,EAAhC,MAAM;QAEkB,WAAW,EAAnC,MAAM;;IACS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IAEU,cAAc,EAA9B,OAAO;IAGQ,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACe,WAAW,EAAhC,MAAM;QACe,mBAAmB,EAAxC,MAAM;;IACJ,yBAAyB,CA8OrC;;;;;UA9Qa,MAAM;;;;WACN,MAAM;;;;cACN,MAAM;;;;eACN,MAAM;;;;uBACN,MAAM;;;;sBACN,MAAM"}