@woosh/meep-engine 3.17.1 → 3.18.0

package/src/shade/renderer/particles/warmup/shader_particle_warmup.js

@@ -0,0 +1,318 @@
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_WARMUP_LAUNCH_LANES,
+    PARTICLE_WARMUP_QUEUE_WORDS,
+    PARTICLE_WARMUP_WORKGROUP_SIZE,
+} from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { PARTICLE_EMITTER_DESCRIPTOR, PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+import { chunk_particle_spawn_budget } from "../shaders/chunk_particle_spawn_budget.js";
+
+/**
+ * The passes that are the warm-up's own. The rest of the loop is the main pipeline's, bound to a
+ * population of its own — see `./graph_particle_warmup.js` for the loop and for why it is separate.
+ *
+ * - {@link shader_particle_warmup_init} — hand the transient pool its free list, once per warm-up.
+ * - {@link shader_particle_warmup_reset} — roll the transient counters over, once per tick.
+ * - {@link shader_particle_warmup_tick} — one thread per queued emitter: the spawn decision for a
+ *   tick, over a queue the host wrote rather than over the emitter table.
+ * - {@link shader_particle_warmup_migrate} — one thread per warmed particle: move it into the main
+ *   pool, once the loop is done.
+ *
+ * Everything the warm-up integrates per emitter lives in the queue entry (its accumulator), not in
+ * the emitter's state row — with one exception, deliberately: the emitter's *age*. INIT and UPDATE
+ * read `EMITTER_AGE` off the state row through the same chunk whether the main emit pass or the
+ * warm-up's runs them, so the warm-up tick writes the age the emitter has reached into that row as it
+ * goes. When the loop ends the row says `prewarm`, and the next real tick adds its `dt` to that.
+ */
+
+/**
+ * Word offsets within one entry of the warm-up queue the host writes:
+ * `[emitter row, pre-warm seconds, spawn accumulator, clock]`.
+ *
+ * The accumulator is the host's to seed and the GPU's from then on — a fraction in `[0, 1)` hashed
+ * from the row, so that two emitters queued together do not put their first whole particle on the
+ * same tick. The clock is the emitter's own tick rate, `1 ± PARTICLE_WARMUP_EMITTER_JITTER / 2`, for
+ * the same reason a beat further in.
+ *
+ * Raw words rather than a `WebGPUStruct`, like the spawn-command list: it is a short host-authored
+ * list read once a tick, and the floats are `bitcast` on the way in and out.
+ */
+export const WARMUP_QUEUE = Object.freeze({
+    ROW: 0,
+    PREWARM: 1,
+    ACCUMULATOR: 2,
+    CLOCK: 3,
+});
+
+/** Workgroups the bounded per-particle passes launch. */
+export const PARTICLE_WARMUP_WORKGROUP_COUNT = PARTICLE_WARMUP_LAUNCH_LANES / PARTICLE_WARMUP_WORKGROUP_SIZE;
+
+const WG = PARTICLE_WARMUP_WORKGROUP_SIZE;
+
+// --- init -------------------------------------------------------------------------------------
+
+const init_resources = new ShaderResourceSetDescriptor();
+
+init_resources.setImmediate("u_capacity", u32);
+
+init_resources.createGroup()
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * One thread per slot of the transient pool: every slot onto the free list, and the counters to
+ * match. What the main system does once on the CPU when it allocates its pool, done on the GPU here
+ * because the pool is a graph transient and there is no CPU moment to write it in.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_warmup_init = ComputeShader.from({
+    label: "Particle Warm-up Init",
+    resources: init_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+
+    if (i == 0u) {
+        atomicStore(&counters[${PARTICLE_COUNTER.DEAD}u], u_capacity);
+        atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
+        atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], 0u);
+    }
+
+    if (i >= u_capacity) { return; }
+
+    dead[i] = i;
+}
+`),
+});
+
+// --- reset ------------------------------------------------------------------------------------
+
+const reset_resources = new ShaderResourceSetDescriptor();
+
+reset_resources.createGroup()
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * The top of a warm-up tick: last tick's alive list becomes this tick's advance input, the alive
+ * count starts over, and the tick's spawn budget is the free list as it stands.
+ *
+ * The main frame splits this between its reset pass and its build-indirect pass, because its
+ * simulate consumes the program-coherent list the bucketing built rather than the alive list
+ * itself. The warm-up's advance consumes the alive list directly (see `./chunk_particle_warmup_step.js`
+ * for why it can), so the snapshot is just the count.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_warmup_reset = ComputeShader.from({
+    label: "Particle Warm-up Reset",
+    resources: reset_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+@compute @workgroup_size(1, 1, 1)
+fn main() {
+    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], atomicLoad(&counters[${PARTICLE_COUNTER.ALIVE}u]));
+    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
+    atomicStore(&counters[${PARTICLE_COUNTER.SPAWN_BUDGET}u], atomicLoad(&counters[${PARTICLE_COUNTER.DEAD}u]));
+}
+`),
+});
+
+// --- tick -------------------------------------------------------------------------------------
+
+/**
+ * Per-dispatch, 20 bytes, read-only.
+ * @type {WebGPUStruct}
+ */
+export const WARMUP_TICK_SETTINGS = WebGPUStruct.from({
+    /** seconds this tick advances the population by */
+    u_dt: f32,
+    /** seconds from the start of this tick to "now" — the end of the loop */
+    u_remaining: f32,
+    /** transient pool capacity — the accumulator's ceiling and the budget's wrap guard */
+    u_capacity: u32,
+    /** element capacity of the emitter table — the length of the counts list the scan consumes */
+    u_emitter_capacity: u32,
+    /** entries in the queue */
+    u_count: u32,
+}, "ParticleWarmupTickSettings");
+
+const EMITTER = PARTICLE_EMITTER_DESCRIPTOR;
+const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
+
+// Generated once and held: each call builds a fresh chunk declaring the same function.
+const WRITE_AGE = STATE.wgsl_gen_write_field_code("age");
+
+const tick_resources = new ShaderResourceSetDescriptor();
+
+tick_resources.setImmediate("settings", WARMUP_TICK_SETTINGS);
+
+tick_resources.createGroup()
+    .addStorageBuffer("queue", WebGPUArray.u32, true)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("spawn_counts", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * One thread per queued emitter: how many particles it spawns this tick.
+ *
+ * The main emitter tick's spawn decision — integrate the rate, take from the budget, write the
+ * count by row for the scan — over the host's queue instead of the emitter table, and without the
+ * parts that belong to a live frame: no generation test (the host holds the queue for exactly one
+ * frame), no culling (a warm-up is what makes an emitter measurable in the first place), no pending
+ * bursts (they are the frame's, not the past's).
+ *
+ * ## When an emitter takes part
+ *
+ * Once `u_remaining` is within its own pre-warm: the loop's clock counts down to now, and an emitter
+ * joins it when the time left is what it asked to have been running for. Two emitters queued with
+ * different durations therefore end the same loop having each run for its own — the shorter one
+ * simply sat out the start — rather than the shorter one being run for the longer's time and
+ * arriving with a population that is all dead of old age.
+ *
+ * ## The count list is the emitter table's
+ *
+ * The counts are written by emitter *row*, into a list as long as the table, exactly as the main
+ * tick writes them. That is what lets the main emit pass be reused unchanged: it finds a newborn's
+ * emitter by searching the scan of that list, and the row it finds is the row its record reads.
+ * Rows not in the queue count zero, which the cleared buffer already says.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_warmup_tick = ComputeShader.from({
+    label: "Particle Warm-up Tick",
+    resources: tick_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+const WARMUP_QUEUE_WORDS : u32 = ${PARTICLE_WARMUP_QUEUE_WORDS}u;
+const WARMUP_Q_ROW : u32 = ${WARMUP_QUEUE.ROW}u;
+const WARMUP_Q_PREWARM : u32 = ${WARMUP_QUEUE.PREWARM}u;
+const WARMUP_Q_ACCUMULATOR : u32 = ${WARMUP_QUEUE.ACCUMULATOR}u;
+const WARMUP_Q_CLOCK : u32 = ${WARMUP_QUEUE.CLOCK}u;
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+
+    // The scan reads exactly this many counts, queued or not.
+    if (i == 0u) {
+        spawn_counts.count = settings.u_emitter_capacity;
+    }
+
+    if (i >= settings.u_count) { return; }
+
+    let base = i * WARMUP_QUEUE_WORDS;
+    let row = queue[base + WARMUP_Q_ROW];
+    let prewarm = bitcast<f32>(queue[base + WARMUP_Q_PREWARM]);
+    var accumulator = bitcast<f32>(queue[base + WARMUP_Q_ACCUMULATOR]);
+    let clock = bitcast<f32>(queue[base + WARMUP_Q_CLOCK]);
+
+    var count = 0u;
+
+    if (settings.u_remaining <= prewarm) {
+        let em = ${EMITTER.marshalling_method_read_rw}(&emitter_database, row);
+
+        // This emitter's own beat: the tick, at its own clock.
+        accumulator = min(accumulator + em.spawn_rate * settings.u_dt * clock, f32(settings.u_capacity));
+
+        let wanted = u32(floor(accumulator));
+
+        if (wanted > 0u) {
+            count = particle_take_spawn_budget(wanted, settings.u_capacity);
+            accumulator = accumulator - f32(count);
+        }
+
+        // How long the emitter has been running once this tick is done — what this tick's newborns
+        // and advances read as EMITTER_AGE, on the row the main passes read it from too.
+        ${STATE.marshalling_method_write_field("age")}(&emitter_database, row, prewarm - settings.u_remaining + settings.u_dt);
+    }
+
+    spawn_counts.elements[row] = count;
+    queue[base + WARMUP_Q_ACCUMULATOR] = bitcast<u32>(accumulator);
+}
+`, [
+        EMITTER.chunk_read_rw,
+        WRITE_AGE,
+        chunk_particle_spawn_budget,
+    ]),
+});
+
+// --- migrate ----------------------------------------------------------------------------------
+
+const migrate_resources = new ShaderResourceSetDescriptor();
+
+migrate_resources.setImmediate("u_capacity", u32);
+
+migrate_resources.createGroup()
+    .addStorageBuffer("warm_pool", WebGPUArray.u32, false)
+    .addStorageBuffer("warm_alive", WebGPUArray.u32, false)
+    .addStorageBuffer("warm_counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("pool", WebGPUArray.u32, true)
+    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * One thread per particle the loop left alive: a slot from the main pool, the record copied into
+ * it, and the slot onto the main alive list. The moment the warm-up's population becomes the
+ * scene's.
+ *
+ * The pop is the emit pass's, wrap guard and all, and it is the only thing this pass does to the
+ * main free list: it never pushes, so it is safe against nothing and needs no ordering beyond
+ * running after the main emit and simulate of the frame, which the graph gives it. A particle the
+ * main pool has no room for is dropped, as a spawn the pool has no room for is.
+ *
+ * The record is copied whole, header included. The header names the emitter's main-table row and
+ * generation — the warm-up's emit stamped it from the same record the main emit reads — so the
+ * copied particle is an ordinary one to every pass that meets it from here on.
+ *
+ * Bounded launch, grid stride over the transient alive count: the population is small and nothing
+ * should size a dispatch from the host to cover it.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_warmup_migrate = ComputeShader.from({
+    label: "Particle Warm-up Migrate",
+    resources: migrate_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
+const WARMUP_LAUNCH_LANES : u32 = ${PARTICLE_WARMUP_LAUNCH_LANES}u;
+const WARMUP_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let total = atomicLoad(&warm_counters[COUNTER_ALIVE]);
+
+    for (var i = gid.x; i < total; i = i + WARMUP_LAUNCH_LANES) {
+        let src = warm_alive[i];
+
+        // Pop a free slot off the main dead-list stack; drop the particle if the pool is exhausted.
+        // The guard catches WRAPPED values, not just 0 — see chunk_particle_emit_step for why.
+        let old_dead = atomicSub(&counters[COUNTER_DEAD], 1u);
+        if (old_dead == 0u || old_dead > u_capacity) {
+            atomicAdd(&counters[COUNTER_DEAD], 1u); // undo the over-pop
+            continue;
+        }
+        let dst = dead[old_dead - 1u];
+
+        let src_base = src * WARMUP_RECORD_WORDS;
+        let dst_base = dst * WARMUP_RECORD_WORDS;
+
+        for (var w = 0u; w < WARMUP_RECORD_WORDS; w = w + 1u) {
+            pool[dst_base + w] = warm_pool[src_base + w];
+        }
+
+        let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
+        alive_out[a] = dst;
+    }
+}
+`),
+});

package/src/shade/renderer/particles/warmup/shader_particle_warmup_advance.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The warm-up's advance pass over the fast register file: one warm-up tick of UPDATE over every
+ * particle the previous tick left alive, compacting survivors into the next alive list and the dead
+ * onto the transient free list.
+ *
+ * What the main simulate pass is to a frame, this is to a warm-up tick, and it is a shader of its
+ * own rather than that pass bound to other buffers for the reasons `./chunk_particle_warmup_step.js`
+ * gives: it reads the alive list directly, so it decodes per lane, and it jitters the tick per
+ * particle. Nothing about it is linked into the main passes.
+ *
+ * A bounded launch with a grid-stride loop over the transient alive count — the wide interpreter's
+ * shape — so no indirect-args pass is needed per tick and the loop's passes are all sized by
+ * constants. `alive_in` is the list the previous tick built (or the emit pass of this one appended
+ * to, on the pass before); `alive_out` is the other of the pair.
+ *
+ * @type {ComputeShader}
+ */
+/**
+ * Per-dispatch, 12 bytes, read-only. The same three numbers the main simulate takes, as a struct of
+ * this pass's own rather than that pass's export: the two must be free to diverge.
+ * @type {WebGPUStruct}
+ */
+export const WARMUP_ADVANCE_SETTINGS: WebGPUStruct;
+/**
+ * The entry point both register backings share, as WGSL text: the wide variant prepends its
+ * register bind and is otherwise this.
+ * @type {string}
+ */
+export const WARMUP_ADVANCE_BODY: string;
+export const shader_particle_warmup_advance: ComputeShader;
+export { PARTICLE_WARMUP_WORKGROUP_COUNT };
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { PARTICLE_WARMUP_WORKGROUP_COUNT } from "./shader_particle_warmup.js";
+//# sourceMappingURL=shader_particle_warmup_advance.d.ts.map

package/src/shade/renderer/particles/warmup/shader_particle_warmup_advance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_warmup_advance.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/warmup/shader_particle_warmup_advance.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;GAIG;AACH,sCAFU,YAAY,CAMc;AAgBpC;;;;GAIG;AACH,kCAFU,MAAM,CA6Bd;AAEF,2DAeG;;6BAvG0B,mCAAmC;8BAClC,+BAA+B;gDAQb,6BAA6B"}

package/src/shade/renderer/particles/warmup/shader_particle_warmup_advance.js

@@ -0,0 +1,108 @@
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PARTICLE_WARMUP_LAUNCH_LANES, PARTICLE_WARMUP_WORKGROUP_SIZE } from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { chunk_particle_curve_disabled } from "../shaders/chunk_particle_curve_disabled.js";
+import { chunk_particle_vm_registers_fast } from "../vm/chunk_particle_vm_registers_fast.js";
+import { chunk_particle_warmup_step } from "./chunk_particle_warmup_step.js";
+import { PARTICLE_WARMUP_WORKGROUP_COUNT } from "./shader_particle_warmup.js";
+
+/**
+ * The warm-up's advance pass over the fast register file: one warm-up tick of UPDATE over every
+ * particle the previous tick left alive, compacting survivors into the next alive list and the dead
+ * onto the transient free list.
+ *
+ * What the main simulate pass is to a frame, this is to a warm-up tick, and it is a shader of its
+ * own rather than that pass bound to other buffers for the reasons `./chunk_particle_warmup_step.js`
+ * gives: it reads the alive list directly, so it decodes per lane, and it jitters the tick per
+ * particle. Nothing about it is linked into the main passes.
+ *
+ * A bounded launch with a grid-stride loop over the transient alive count — the wide interpreter's
+ * shape — so no indirect-args pass is needed per tick and the loop's passes are all sized by
+ * constants. `alive_in` is the list the previous tick built (or the emit pass of this one appended
+ * to, on the pass before); `alive_out` is the other of the pair.
+ *
+ * @type {ComputeShader}
+ */
+
+/**
+ * Per-dispatch, 12 bytes, read-only. The same three numbers the main simulate takes, as a struct of
+ * this pass's own rather than that pass's export: the two must be free to diverge.
+ * @type {WebGPUStruct}
+ */
+export const WARMUP_ADVANCE_SETTINGS = WebGPUStruct.from({
+    u_dt: f32,
+    u_time: f32,
+    u_frame: u32,
+}, "ParticleWarmupAdvanceSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", WARMUP_ADVANCE_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("alive_in", WebGPUArray.u32, false)
+    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * The entry point both register backings share, as WGSL text: the wide variant prepends its
+ * register bind and is otherwise this.
+ * @type {string}
+ */
+export const WARMUP_ADVANCE_BODY = /* 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;
+const WARMUP_LAUNCH_LANES : u32 = ${PARTICLE_WARMUP_LAUNCH_LANES}u;
+
+fn particle_warmup_advance_all(lane : u32) {
+    let total = atomicLoad(&counters[COUNTER_ALIVE_IN]);
+
+    for (var i = lane; i < total; i = i + WARMUP_LAUNCH_LANES) {
+        let slot = alive_in[i];
+
+        let survived = particle_warmup_advance_one(
+            &scene_database, &emitter_database, &program, &pool,
+            slot,
+            settings.u_dt, settings.u_time, settings.u_frame,
+        );
+
+        if (survived) {
+            let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
+            alive_out[a] = slot;
+        } else {
+            let d = atomicAdd(&counters[COUNTER_DEAD], 1u);
+            dead[d] = slot;
+        }
+    }
+}
+`;
+
+export const shader_particle_warmup_advance = ComputeShader.from({
+    label: "Particle Warm-up Advance",
+    resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+${WARMUP_ADVANCE_BODY}
+
+@compute @workgroup_size(${PARTICLE_WARMUP_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    particle_warmup_advance_all(gid.x);
+}
+`, [
+        chunk_particle_warmup_step,
+        chunk_particle_vm_registers_fast,
+        chunk_particle_curve_disabled,
+    ]),
+});
+
+export { PARTICLE_WARMUP_WORKGROUP_COUNT };

package/src/shade/renderer/particles/warmup/shader_particle_warmup_advance_wide.d.ts

@@ -0,0 +1,3 @@
+export const shader_particle_warmup_advance_wide: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_warmup_advance_wide.d.ts.map

package/src/shade/renderer/particles/warmup/shader_particle_warmup_advance_wide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_warmup_advance_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/warmup/shader_particle_warmup_advance_wide.js"],"names":[],"mappings":"AAkDA,gEAmBG;8BAlE2B,+BAA+B"}

package/src/shade/renderer/particles/warmup/shader_particle_warmup_advance_wide.js

@@ -0,0 +1,70 @@
+import { assert } from "../../../../core/assert.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_VM_WIDE_LAUNCH_LANES,
+    PARTICLE_WARMUP_LAUNCH_LANES,
+    PARTICLE_WARMUP_WORKGROUP_SIZE,
+} from "../ParticleConstants.js";
+import { chunk_particle_curve_disabled } from "../shaders/chunk_particle_curve_disabled.js";
+import { chunk_particle_vm_registers_wide } from "../vm/chunk_particle_vm_registers_wide.js";
+import { chunk_particle_warmup_step } from "./chunk_particle_warmup_step.js";
+import { WARMUP_ADVANCE_BODY, WARMUP_ADVANCE_SETTINGS } from "./shader_particle_warmup_advance.js";
+
+/**
+ * The warm-up's advance pass over the WIDE register file — for a system whose hungriest effect has
+ * put the interpreter on the storage-backed file. Same pass as
+ * {@link ./shader_particle_warmup_advance.js}, same entry point text, plus the register bind and the
+ * ninth binding, exactly as the main simulate's wide variant relates to its fast one.
+ *
+ * The register file is indexed by launch lane and reused across the grid-stride loop's iterations,
+ * which is sound for the reason `../vm/chunk_particle_vm_registers_wide.js` gives: a program writes
+ * a register before it reads it. It is the same buffer the main wide passes use, sized by
+ * {@link PARTICLE_VM_WIDE_LAUNCH_LANES}, which is why the warm-up's launch must be exactly that wide.
+ *
+ * @type {ComputeShader}
+ */
+
+assert.equal(
+    PARTICLE_WARMUP_LAUNCH_LANES, PARTICLE_VM_WIDE_LAUNCH_LANES,
+    "the warm-up's launch must match the wide register file's lane count, which sizes the file",
+);
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", WARMUP_ADVANCE_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("alive_in", 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);
+
+export const shader_particle_warmup_advance_wide = ComputeShader.from({
+    label: "Particle Warm-up Advance (wide registers)",
+    resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+${WARMUP_ADVANCE_BODY}
+
+@compute @workgroup_size(${PARTICLE_WARMUP_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_WARMUP_LAUNCH_LANES wide, so gid.x is in range by construction.
+    particle_vm_bind_registers(gid.x);
+
+    particle_warmup_advance_all(gid.x);
+}
+`, [
+        chunk_particle_warmup_step,
+        chunk_particle_vm_registers_wide,
+        chunk_particle_curve_disabled,
+    ]),
+});

package/src/shade/renderer/particles/warmup/warmup_schedule.d.ts

@@ -0,0 +1,62 @@
+/**
+ * How a batch of pre-warms is paid off: in how many ticks, and how long each is.
+ *
+ * Shared by the GPU loop (`./graph_particle_warmup.js`) and the editor's CPU preview
+ * (`editor/particles/effect/ParticleReferenceSimulation.js`), so the two integrate the same debt in
+ * the same steps and an author sees in the preview what the scene will show.
+ *
+ * The tick count is bounded and the tick length stretches to cover the debt — not the other way
+ * round — because the count is what the frame pays for: every tick is a handful of dispatches. A
+ * two-hundred-millisecond warm-up at a ten-millisecond floor is twenty ticks of ten; a three-second
+ * one is {@link PARTICLE_WARMUP_MAX_TICKS} ticks of ninety-odd.
+ *
+ * @typedef {object} WarmupSchedule
+ * @property {number} ticks how many times the loop runs; zero for nothing owed
+ * @property {number} dt seconds each tick advances the population by
+ * @property {number} duration `ticks * dt` — the loop's whole span, never less than the longest
+ *   pre-warm in the batch and less than one tick more
+ */
+/**
+ * @param {number} max_prewarm the longest pre-warm in the batch, seconds
+ * @returns {WarmupSchedule}
+ */
+export function warmup_schedule(max_prewarm: number): WarmupSchedule;
+/**
+ * Seconds between the start of tick `tick` and "now" — the moment the loop ends and the population
+ * joins the scene. An emitter takes part in a tick once this is within its own pre-warm, so that
+ * whatever the longest pre-warm in the batch was, every emitter has run for exactly its own by the
+ * end.
+ *
+ * @param {WarmupSchedule} schedule
+ * @param {number} tick
+ * @returns {number}
+ */
+export function warmup_remaining(schedule: WarmupSchedule, tick: number): number;
+/**
+ * How a batch of pre-warms is paid off: in how many ticks, and how long each is.
+ *
+ * Shared by the GPU loop (`./graph_particle_warmup.js`) and the editor's CPU preview
+ * (`editor/particles/effect/ParticleReferenceSimulation.js`), so the two integrate the same debt in
+ * the same steps and an author sees in the preview what the scene will show.
+ *
+ * The tick count is bounded and the tick length stretches to cover the debt — not the other way
+ * round — because the count is what the frame pays for: every tick is a handful of dispatches. A
+ * two-hundred-millisecond warm-up at a ten-millisecond floor is twenty ticks of ten; a three-second
+ * one is {@link PARTICLE_WARMUP_MAX_TICKS } ticks of ninety-odd.
+ */
+export type WarmupSchedule = {
+    /**
+     * how many times the loop runs; zero for nothing owed
+     */
+    ticks: number;
+    /**
+     * seconds each tick advances the population by
+     */
+    dt: number;
+    /**
+     * `ticks * dt` — the loop's whole span, never less than the longest
+     * pre-warm in the batch and less than one tick more
+     */
+    duration: number;
+};
+//# sourceMappingURL=warmup_schedule.d.ts.map

package/src/shade/renderer/particles/warmup/warmup_schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warmup_schedule.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/warmup/warmup_schedule.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,6CAHW,MAAM,GACJ,cAAc,CAgB1B;AAED;;;;;;;;;GASG;AACH,2CAJW,cAAc,QACd,MAAM,GACJ,MAAM,CAIlB;;;;;;;;;;;;;;;;;WAtCa,MAAM;;;;QACN,MAAM;;;;;cACN,MAAM"}

package/src/shade/renderer/particles/warmup/warmup_schedule.js

@@ -0,0 +1,55 @@
+import { assert } from "../../../../core/assert.js";
+import { PARTICLE_WARMUP_MAX_TICKS, PARTICLE_WARMUP_TICK_SECONDS } from "../ParticleConstants.js";
+
+/**
+ * How a batch of pre-warms is paid off: in how many ticks, and how long each is.
+ *
+ * Shared by the GPU loop (`./graph_particle_warmup.js`) and the editor's CPU preview
+ * (`editor/particles/effect/ParticleReferenceSimulation.js`), so the two integrate the same debt in
+ * the same steps and an author sees in the preview what the scene will show.
+ *
+ * The tick count is bounded and the tick length stretches to cover the debt — not the other way
+ * round — because the count is what the frame pays for: every tick is a handful of dispatches. A
+ * two-hundred-millisecond warm-up at a ten-millisecond floor is twenty ticks of ten; a three-second
+ * one is {@link PARTICLE_WARMUP_MAX_TICKS} ticks of ninety-odd.
+ *
+ * @typedef {object} WarmupSchedule
+ * @property {number} ticks how many times the loop runs; zero for nothing owed
+ * @property {number} dt seconds each tick advances the population by
+ * @property {number} duration `ticks * dt` — the loop's whole span, never less than the longest
+ *   pre-warm in the batch and less than one tick more
+ */
+
+/**
+ * @param {number} max_prewarm the longest pre-warm in the batch, seconds
+ * @returns {WarmupSchedule}
+ */
+export function warmup_schedule(max_prewarm) {
+    assert.isNumber(max_prewarm, "max_prewarm");
+    assert.greaterThanOrEqual(max_prewarm, 0, "max_prewarm");
+
+    if (max_prewarm <= 0) {
+        return { ticks: 0, dt: 0, duration: 0 };
+    }
+
+    const dt = Math.max(PARTICLE_WARMUP_TICK_SECONDS, max_prewarm / PARTICLE_WARMUP_MAX_TICKS);
+
+    // `max / (max / MAX)` is MAX up to rounding, and a rounding error's `ceil` is MAX + 1.
+    const ticks = Math.min(PARTICLE_WARMUP_MAX_TICKS, Math.ceil(max_prewarm / dt));
+
+    return { ticks, dt, duration: ticks * dt };
+}
+
+/**
+ * Seconds between the start of tick `tick` and "now" — the moment the loop ends and the population
+ * joins the scene. An emitter takes part in a tick once this is within its own pre-warm, so that
+ * whatever the longest pre-warm in the batch was, every emitter has run for exactly its own by the
+ * end.
+ *
+ * @param {WarmupSchedule} schedule
+ * @param {number} tick
+ * @returns {number}
+ */
+export function warmup_remaining(schedule, tick) {
+    return schedule.duration - tick * schedule.dt;
+}

package/src/shade/renderer/postprocess/PostProcess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PostProcess.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/postprocess/PostProcess.js"],"names":[],"mappings":"AAGA;IAYI;;;OAGG;IACH,uCAIC;IAnBD;;OAEG;IACH,MAFU,IAAI,CAEV;IAGJ;;OAEG;IACH,KAFU,GAAG,CAEV;IAYH;;;OAGG;IACH,oBAFW,MAAM,QAIhB;IAED,sBACC;CACJ;qBAnCoB,gBAAgB;oBACjB,cAAc"}
+{"version":3,"file":"PostProcess.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/postprocess/PostProcess.js"],"names":[],"mappings":"AAGA;IAYI;;;OAGG;IACH,uCAIC;IAnBD;;OAEG;IACH,MAFU,IAAI,CAEV;IAGJ;;OAEG;IACH,KAFU,GAAG,CAEV;IAYH;;;OAGG;IACH,oBAFW,MAAM,QAIhB;IAED,sBAEC;CACJ;qBApCoB,gBAAgB;oBACjB,cAAc"}