@woosh/meep-engine 3.12.0 → 3.13.0

package/src/shade/renderer/particles/shaders/shader_particle_emit.js

@@ -1,117 +1,132 @@
-import { atomic_u32, f32, u32 } 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_RECORD_HEADER_EMITTER,
-    PARTICLE_RECORD_USER_WORD_START,
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_VM_INSTRUCTION_WORDS,
-} from "../ParticleConstants.js";
-import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import {
-    SPAWN_REQUEST_EMITTER_MASK,
-    SPAWN_REQUEST_FRACTION_MAX,
-    SPAWN_REQUEST_FRACTION_SHIFT,
-} from "../runtime/spawn_request_encoding.js";
-import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_particle_context.js";
-
-/**
- * The particle emit (spawn) pass.
- *
- * Input is a flat list of spawn requests (one packed emitter-index + batch-fraction per particle
- * to create; built by ParticleSpawnScheduler). Per request: pop a free slot from the dead
- * list, clear the record, stamp the owning emitter, run that emitter's compiled SPAWN program to
- * initialise the particle's user-defined state, then append the slot to the new alive list.
- *
- * Runs after simulate in the frame so newly born particles join the same alive list the survivors
- * were compacted into. Shares the VM + context + emitter chunks with simulate.
- *
- * @type {ComputeShader}
- */
-
-export const PARTICLE_EMIT_WORKGROUP_SIZE = 64;
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
-    .addStorageBuffer("program", WebGPUArray.u32, false)
-    .addStorageBuffer("vm_constants", WebGPUArray.u32, false)
-    .addStorageBuffer("pool", WebGPUArray.u32, true)
-    .addStorageBuffer("spawn_requests", WebGPUArray.u32, false)
-    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
-    .addStorageBuffer("dead", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
-    .addUniform("u_dt", f32)
-    .addUniform("u_time", f32)
-    .addUniform("u_frame", u32)
-    .addUniform("u_count", u32)
-    .addUniform("u_capacity", u32);
-
-const body = CodeChunk.from(/* wgsl */ `
-const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
-const PARTICLE_USER_WORD_START : u32 = ${PARTICLE_RECORD_USER_WORD_START}u;
-const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
-const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
-const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
-
-@compute @workgroup_size(${PARTICLE_EMIT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i >= u_count) { return; }
-
-    // Packed request: low 16 bits = emitter index, high 16 = batch fraction (see
-    // spawn_request_encoding.js). The fraction is LOCAL to this emitter's batch this frame
-    // (SPAWN_FRACTION contract: n / spawn_count), not the global request index / u_count.
-    let request = spawn_requests[i];
-    let emitter_index = request & ${SPAWN_REQUEST_EMITTER_MASK}u;
-    let spawn_fraction = f32(request >> ${SPAWN_REQUEST_FRACTION_SHIFT}u) / ${SPAWN_REQUEST_FRACTION_MAX}.0;
-
-    // Pop a free slot off the dead-list stack; drop the spawn if the pool is exhausted.
-    //
-    // The guard must catch WRAPPED values, not just 0: when many threads race an empty stack, the
-    // first over-pop wraps the counter to 0xFFFFFFFF before its undo lands, and a concurrent thread
-    // then observes a huge old value. Checking only ==0 would let it index dead[old-1] with garbage
-    // and hand out a bogus slot, corrupting a live record. The dead count can never legitimately
-    // exceed the pool capacity, so >u_capacity identifies every wrapped state; each thread that
-    // subtracted also adds back exactly once, so the counter converges to 0.
-    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
-        return;
-    }
-    let slot = dead[old_dead - 1u];
-    let record_base = slot * PARTICLE_RECORD_WORDS;
-
-    // Clear stale user state from a recycled slot (each write targets a distinct word).
-    for (var w = PARTICLE_USER_WORD_START; w < PARTICLE_RECORD_WORDS; w = w + 1u) {
-        pool[record_base + w] = 0u;
-    }
-    pool[record_base + PARTICLE_HEADER_EMITTER] = emitter_index;
-
-    let em = particle_emitter_read(&emitters, emitter_index);
-
-    particle_vm_reset();
-    particle_setup_context(em, slot, u_dt, u_time, 0.0, spawn_fraction, u_frame);
-    particle_vm_execute(
-        &program,
-        em.spawn_offset * PARTICLE_INSTRUCTION_WORDS,
-        em.spawn_count,
-        &vm_constants,
-        em.constant_offset,
-        &pool,
-        record_base,
-    );
-
-    let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
-    alive_out[a] = slot;
-}
-`, [chunk_particle_context, chunk_particle_curve_disabled]);
-
-export const shader_particle_emit = ComputeShader.from({
-    label: "Particle Emit",
-    resources,
-    body,
-});
+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_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_USER_WORD_START,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+} from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import {
+    SPAWN_REQUEST_EMITTER_MASK,
+    SPAWN_REQUEST_FRACTION_MAX,
+    SPAWN_REQUEST_FRACTION_SHIFT,
+} from "../runtime/spawn_request_encoding.js";
+import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_particle_context.js";
+
+/**
+ * The particle emit (spawn) pass.
+ *
+ * Input is a flat list of spawn requests (one packed emitter-index + batch-fraction per particle
+ * to create; built by ParticleSpawnScheduler). Per request: pop a free slot from the dead
+ * list, clear the record, stamp the owning emitter, run that emitter's compiled SPAWN program to
+ * initialise the particle's user-defined state, then append the slot to the new alive list.
+ *
+ * Runs after simulate in the frame so newly born particles join the same alive list the survivors
+ * were compacted into. Shares the VM + context + emitter chunks with simulate.
+ *
+ * @type {ComputeShader}
+ */
+
+export const PARTICLE_EMIT_WORKGROUP_SIZE = 64;
+
+/**
+ * Per-dispatch, 20 bytes, read-only.
+ *
+ * These were five separate uniforms, which meant five transient buffers, five staging copies and
+ * five bind group entries for twenty bytes of frame state. WGSL allows one immediate per entry
+ * point, so carrying them as immediate data means carrying them together.
+ *
+ * @type {WebGPUStruct}
+ */
+const EMIT_SETTINGS = WebGPUStruct.from({
+    u_dt: f32,
+    u_time: f32,
+    u_frame: u32,
+    u_count: u32,
+    u_capacity: u32,
+}, 'ParticleEmitSettings');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', EMIT_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("program", WebGPUArray.u32, false)
+    .addStorageBuffer("vm_constants", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, true)
+    .addStorageBuffer("spawn_requests", WebGPUArray.u32, false)
+    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+const body = CodeChunk.from(/* wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_USER_WORD_START : u32 = ${PARTICLE_RECORD_USER_WORD_START}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
+
+@compute @workgroup_size(${PARTICLE_EMIT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= settings.u_count) { return; }
+
+    // Packed request: low 16 bits = emitter index, high 16 = batch fraction (see
+    // spawn_request_encoding.js). The fraction is LOCAL to this emitter's batch this frame
+    // (SPAWN_FRACTION contract: n / spawn_count), not the global request index / settings.u_count.
+    let request = spawn_requests[i];
+    let emitter_index = request & ${SPAWN_REQUEST_EMITTER_MASK}u;
+    let spawn_fraction = f32(request >> ${SPAWN_REQUEST_FRACTION_SHIFT}u) / ${SPAWN_REQUEST_FRACTION_MAX}.0;
+
+    // Pop a free slot off the dead-list stack; drop the spawn if the pool is exhausted.
+    //
+    // The guard must catch WRAPPED values, not just 0: when many threads race an empty stack, the
+    // first over-pop wraps the counter to 0xFFFFFFFF before its undo lands, and a concurrent thread
+    // then observes a huge old value. Checking only ==0 would let it index dead[old-1] with garbage
+    // and hand out a bogus slot, corrupting a live record. The dead count can never legitimately
+    // exceed the pool capacity, so >settings.u_capacity identifies every wrapped state; each thread that
+    // subtracted also adds back exactly once, so the counter converges to 0.
+    let old_dead = atomicSub(&counters[COUNTER_DEAD], 1u);
+    if (old_dead == 0u || old_dead > settings.u_capacity) {
+        atomicAdd(&counters[COUNTER_DEAD], 1u); // undo the over-pop
+        return;
+    }
+    let slot = dead[old_dead - 1u];
+    let record_base = slot * PARTICLE_RECORD_WORDS;
+
+    // Clear stale user state from a recycled slot (each write targets a distinct word).
+    for (var w = PARTICLE_USER_WORD_START; w < PARTICLE_RECORD_WORDS; w = w + 1u) {
+        pool[record_base + w] = 0u;
+    }
+    pool[record_base + PARTICLE_HEADER_EMITTER] = emitter_index;
+
+    let em = particle_emitter_read(&emitters, emitter_index);
+
+    particle_vm_reset();
+    particle_setup_context(em, slot, settings.u_dt, settings.u_time, 0.0, spawn_fraction, settings.u_frame);
+    particle_vm_execute(
+        &program,
+        em.spawn_offset * PARTICLE_INSTRUCTION_WORDS,
+        em.spawn_count,
+        &vm_constants,
+        em.constant_offset,
+        &pool,
+        record_base,
+    );
+
+    let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
+    alive_out[a] = slot;
+}
+`, [chunk_particle_context, chunk_particle_curve_disabled]);
+
+export const shader_particle_emit = ComputeShader.from({
+    label: "Particle Emit",
+    resources,
+    body,
+});

package/src/shade/renderer/particles/shaders/shader_particle_finalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AA4BA,2DAWG;AAWH,2DAwBG;;8BAxE2B,+BAA+B;iDAIZ,+BAA+B"}
+{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AA4BA,2DAWG;AAaH,2DAwBG;;8BA1E2B,+BAA+B;iDAIZ,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_finalize.js

@@ -1,77 +1,79 @@
-import { atomic_u32, u32 } 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_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./shader_particle_simulate.js";
-
-/**
- * Small housekeeping passes that keep the pipeline GPU-driven:
- *
- * - {@link shader_particle_reset_counters} — zero the alive / spawn / sorted counters at the top of
- *   the frame (the dead count and the ALIVE_IN snapshot persist across frames).
- * - {@link shader_particle_build_indirect} — read the frame's final alive count and (a) snapshot it
- *   into {@link PARTICLE_COUNTER.ALIVE_IN} — the exact input length for NEXT frame's simulate, (b)
- *   write the indirect dispatch args next frame's simulate consumes, and (c) write the indirect draw
- *   args for THIS frame's billboard render. Nothing round-trips to the CPU. Sizing the dispatch or
- *   draw from a stale CPU readback instead is a correctness bug: when the alive count grows the tail
- *   of the list is never simulated (slots leak into limbo), and when it shrinks stale entries beyond
- *   the written range get re-simulated — a dead slot is pushed to the free list twice and later
- *   popped twice, leaving two live particles sharing one record.
- */
-
-// --- reset ---
-
-const reset_resources = new ShaderResourceSetDescriptor();
-reset_resources.createGroup().addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
-
-export const shader_particle_reset_counters = ComputeShader.from({
-    label: "Particle Reset Counters",
-    resources: reset_resources,
-    body: CodeChunk.from(/* wgsl */ `
-@compute @workgroup_size(1, 1, 1)
-fn main() {
-    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
-    atomicStore(&counters[${PARTICLE_COUNTER.SPAWN}u], 0u);
-    atomicStore(&counters[${PARTICLE_COUNTER.SORTED}u], 0u);
-}
-`),
-});
-
-// --- build indirect args ---
-
-const indirect_resources = new ShaderResourceSetDescriptor();
-indirect_resources.createGroup()
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true) // atomics require a read_write binding even for atomicLoad
-    .addStorageBuffer("dispatch_args", WebGPUArray.u32, true) // {x,y,z}
-    .addStorageBuffer("draw_args", WebGPUArray.u32, true)     // {vertexCount, instanceCount, firstVertex, firstInstance}
-    .addUniform("u_workgroup_size", u32);
-
-export const shader_particle_build_indirect = ComputeShader.from({
-    label: "Particle Build Indirect",
-    resources: indirect_resources,
-    body: CodeChunk.from(/* wgsl */ `
-@compute @workgroup_size(1, 1, 1)
-fn main() {
-    let alive = atomicLoad(&counters[${PARTICLE_COUNTER.ALIVE}u]);
-
-    // Snapshot: this frame's final alive count is next frame's exact simulate input length.
-    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], alive);
-
-    // Simulate dispatch (consumed NEXT frame): one thread per alive particle, whole workgroups.
-    let groups = (alive + u_workgroup_size - 1u) / max(u_workgroup_size, 1u);
-    dispatch_args[0] = groups;
-    dispatch_args[1] = 1u;
-    dispatch_args[2] = 1u;
-
-    // Instanced billboard draw (consumed THIS frame): 6 verts per particle, one instance per alive.
-    draw_args[0] = 6u;
-    draw_args[1] = alive;
-    draw_args[2] = 0u;
-    draw_args[3] = 0u;
-}
-`),
-});
-
-export { PARTICLE_SIMULATE_WORKGROUP_SIZE };
+import { atomic_u32, u32 } 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_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./shader_particle_simulate.js";
+
+/**
+ * Small housekeeping passes that keep the pipeline GPU-driven:
+ *
+ * - {@link shader_particle_reset_counters} — zero the alive / spawn / sorted counters at the top of
+ *   the frame (the dead count and the ALIVE_IN snapshot persist across frames).
+ * - {@link shader_particle_build_indirect} — read the frame's final alive count and (a) snapshot it
+ *   into {@link PARTICLE_COUNTER.ALIVE_IN} — the exact input length for NEXT frame's simulate, (b)
+ *   write the indirect dispatch args next frame's simulate consumes, and (c) write the indirect draw
+ *   args for THIS frame's billboard render. Nothing round-trips to the CPU. Sizing the dispatch or
+ *   draw from a stale CPU readback instead is a correctness bug: when the alive count grows the tail
+ *   of the list is never simulated (slots leak into limbo), and when it shrinks stale entries beyond
+ *   the written range get re-simulated — a dead slot is pushed to the free list twice and later
+ *   popped twice, leaving two live particles sharing one record.
+ */
+
+// --- reset ---
+
+const reset_resources = new ShaderResourceSetDescriptor();
+reset_resources.createGroup().addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+export const shader_particle_reset_counters = ComputeShader.from({
+    label: "Particle Reset Counters",
+    resources: reset_resources,
+    body: CodeChunk.from(/* wgsl */ `
+@compute @workgroup_size(1, 1, 1)
+fn main() {
+    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
+    atomicStore(&counters[${PARTICLE_COUNTER.SPAWN}u], 0u);
+    atomicStore(&counters[${PARTICLE_COUNTER.SORTED}u], 0u);
+}
+`),
+});
+
+// --- build indirect args ---
+
+const indirect_resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+indirect_resources.setImmediate("u_workgroup_size", u32);
+indirect_resources.createGroup()
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true) // atomics require a read_write binding even for atomicLoad
+    .addStorageBuffer("dispatch_args", WebGPUArray.u32, true) // {x,y,z}
+    .addStorageBuffer("draw_args", WebGPUArray.u32, true)     // {vertexCount, instanceCount, firstVertex, firstInstance};
+
+export const shader_particle_build_indirect = ComputeShader.from({
+    label: "Particle Build Indirect",
+    resources: indirect_resources,
+    body: CodeChunk.from(/* wgsl */ `
+@compute @workgroup_size(1, 1, 1)
+fn main() {
+    let alive = atomicLoad(&counters[${PARTICLE_COUNTER.ALIVE}u]);
+
+    // Snapshot: this frame's final alive count is next frame's exact simulate input length.
+    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], alive);
+
+    // Simulate dispatch (consumed NEXT frame): one thread per alive particle, whole workgroups.
+    let groups = (alive + u_workgroup_size - 1u) / max(u_workgroup_size, 1u);
+    dispatch_args[0] = groups;
+    dispatch_args[1] = 1u;
+    dispatch_args[2] = 1u;
+
+    // Instanced billboard draw (consumed THIS frame): 6 verts per particle, one instance per alive.
+    draw_args[0] = 6u;
+    draw_args[1] = alive;
+    draw_args[2] = 0u;
+    draw_args[3] = 0u;
+}
+`),
+});
+
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE };

package/src/shade/renderer/particles/shaders/shader_particle_simulate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,+CAHU,aAAa,CAG4B;AA0DnD,qDAIG;8BAhG2B,+BAA+B"}
+{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,+CAHU,aAAa,CAG4B;AAqEnD,qDAIG;8BA3G2B,+BAA+B"}