@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -1,15 +1,26 @@
 /**
- * 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 particle system's frame, recorded into the frame graph. {@link GPUParticleSystem} is what
+ * calls these, with the buffers it owns; nothing else needs to.
  *
- * The passes run in dependency order:
+ * Two halves. {@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. {@link graph_particles_render} is the standalone drawing: a depth sort and one
+ * billboard draw straight over a colour target. Under the renderer the drawing is AVBOIT's instead
+ * (`graph_particles_avboit.js`), which reads the same handles and needs no sort.
+ * {@link graph_particles} is the two together, for a page with no transparency pipeline of its own.
+ *
+ * ## 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,76 +30,66 @@
  * 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 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.
+ *
+ * ## Nothing is sized from the CPU
  *
- * 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.
+ * 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 sort's two per-particle passes and the draw 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.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 distinct compiled programs — `GPUParticleSystem#bucketCount()`
  * @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, 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;
@@ -96,13 +97,87 @@ export function graph_particles({ graph, gpu, capacity, bucket_count, frame }: {
         dt: number;
         time: number;
         index: number;
-        spawn_count: number;
+        max_catchup: number;
+        spawn_command_count: number;
+    };
+}): ParticleSimulationHandles;
+/**
+ * The standalone drawing: the depth sort, then one billboard draw over a colour target with
+ * fixed-function blending.
+ *
+ * @param {object} params
+ * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.camera graph handle
+ * @param {number} params.color graph handle of the colour target the billboards draw over
+ * @param {number} params.depth graph handle of the scene depth, tested against and never written
+ * @param {object} params.gpu the persistent buffers
+ * @param {ParticleSimulationHandles} params.simulated what {@link graph_particles_simulate} returned
+ * @param {number} params.sort_bucket_count depth bins the render sort quantises into
+ * @param {object} params.frame
+ * @param {number} params.frame.sort_near view depth the sort's first bin starts at
+ * @param {number} params.frame.sort_far view depth the sort's last bin ends at
+ * @param {object} params.render
+ * @param {GPUTextureView} params.render.atlas sprite atlas
+ * @param {GPUSampler} params.render.atlas_sampler
+ * @param {(color_format: string, depth_format: string) => object} params.render.obtain_pipeline
+ *   the billboard pipeline for the frame's attachment formats
+ * @returns {number} the colour handle after the draw
+ */
+export function graph_particles_render({ graph, camera, color, depth, gpu, simulated, sort_bucket_count, frame, render, }: {
+    graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    camera: number;
+    color: number;
+    depth: number;
+    gpu: object;
+    simulated: ParticleSimulationHandles;
+    sort_bucket_count: number;
+    frame: {
+        sort_near: number;
+        sort_far: number;
     };
-}): {
-    alive: any;
-    pool: any;
-    counters: any;
-    dispatch_args: any;
-    draw_args: any;
+    render: {
+        atlas: GPUTextureView;
+        atlas_sampler: GPUSampler;
+        obtain_pipeline: (color_format: string, depth_format: string) => object;
+    };
+}): number;
+/**
+ * The whole standalone frame: simulate, then sort and draw.
+ *
+ * @param {object} params every parameter of {@link graph_particles_simulate} and
+ *   {@link graph_particles_render}
+ * @returns {{color: number, alive: number, pool: number, counters: number}}
+ */
+export function graph_particles(params: object): {
+    color: number;
+    alive: number;
+    pool: number;
+    counters: number;
+};
+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":"AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAlBkG,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;IACS,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACe,WAAW,EAAhC,MAAM;QACe,mBAAmB,EAAxC,MAAM;;IACJ,yBAAyB,CAgMrC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;WAjBW,OAAO,2DAA2D,EAAE,UAAU;YAC9E,MAAM;WACN,MAAM;WACN,MAAM;SACN,MAAM;eACN,yBAAyB;uBACzB,MAAM;;QAEe,SAAS,EAA9B,MAAM;QACe,QAAQ,EAA7B,MAAM;;;;;wCAIS,MAAM,gBAAgB,MAAM,KAAK,MAAM;;IAEpD,MAAM,CA6ClB;AAED;;;;;;GAMG;AACH,wCAJW,MAAM;WAEI,MAAM;WAAS,MAAM;UAAQ,MAAM;cAAY,MAAM;EAazE;;;;;UAnTa,MAAM;;;;WACN,MAAM;;;;cACN,MAAM;;;;eACN,MAAM;;;;uBACN,MAAM;;;;sBACN,MAAM"}