@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/playground/particle_system/README.md

@@ -0,0 +1,98 @@
+# GPU particle system — playground
+
+The whole GPU particle path running in a real scene: emitters, the VM, the alive/dead lists and the
+billboard renderer, driven end to end by the GPU with no renderer, no assets and no `Renderer`
+dependency. It moved here from `renderer/particles/prototypeParticleSystem.js`, which had no page to
+open it with.
+
+## Running it
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+then open <http://localhost:5173/src/shade/playground/particle_system/index.html>.
+
+It has to be `http://localhost` rather than `file://`: WebGPU needs a secure context, and module
+imports from `file://` are blocked by CORS anyway. The page imports nothing but meep's own relative
+ESM, so any static server rooted at the repo also serves it.
+
+**It needs immediate data**, and refuses to start without it. Emit, simulate and build-indirect each
+carry their per-dispatch state (`u_dt`, `u_time`, `u_frame`, and for emit the request count and the
+pool capacity) as an immediate block rather than as a transient uniform buffer, so an adapter whose
+WGSL lacks the `immediate` address space cannot build any of the three. The refusal names the byte
+counts. Chrome/Edge 113+ with immediates; Claude Code's in-app browser pane is **not** one — it
+reports no adapter at all today, and no `immediate_address_space` in `wgslLanguageFeatures`.
+
+## What is on screen
+
+Four emitters sharing one 32k pool, chosen so each renderer path is visible at once:
+
+| emitter | blend | projection | what it is there to show |
+|---|---|---|---|
+| fire | additive | billboard | `fire_effect()` straight out of `particle_prototype.js`, at the foot of the pillar |
+| smoke | alpha | billboard, soft-depth | a rising column that fades where it meets the pillar rather than cutting into it |
+| sparks | additive | **stretched** | short-lived, gravity-fed, stretched along velocity — the one non-billboard projection |
+| dust | alpha | billboard, soft-depth | a wide slow drift, so the ground plane and the low wall both get a soft intersection |
+
+Ground plane and three boxes are drawn first into a reverse-Z `depth32float` buffer. The billboard
+pass loads that colour target and depth-tests against the same buffer read-only, so particles are
+**occluded** by the boxes and the soft-depth emitters sample the depth they were occluded by.
+
+Things worth looking at:
+
+- particles disappearing behind the pillar as the camera orbits — that is the depth test,
+- smoke and dust softening where they touch a surface instead of showing a hard intersection line —
+  that is `PARTICLE_FLAG_SOFT_DEPTH` and the reverse-Z linearisation,
+- sparks leaning into their own velocity — `EMITTER_PROJECTION.STRETCHED`,
+- both blend modes in **one** draw with one pipeline: `particle_premultiply` picks per particle, so
+  there is no additive pass and no alpha pass.
+
+The overlay shows fps and, every 30 frames, the alive count, the free-list length and the two
+indirect arg buffers. Those are read back **to look at**. Nothing on the CPU sizes a pass.
+
+## The property the page exists to demonstrate
+
+The frame is GPU-driven end to end. `shader_particle_build_indirect` writes both the simulate
+dispatch args and the billboard draw args on the GPU; the next frame's simulate runs through
+`dispatchWorkgroupsIndirect` and this frame's draw through `drawIndirect`. The host's only sizing
+decision is how many *new* particles to spawn, which is a per-emitter rate times `dt` and has
+nothing to do with how many are already alive.
+
+Sizing either from a CPU readback instead would be a correctness bug rather than a latency one: a
+stale count that is too small leaves the tail of the alive list unsimulated, so those slots are
+never freed, and one that is too large re-simulates entries past the end, pushing a dead slot onto
+the free list twice — it is then popped twice and two live particles share one record.
+
+## Verifying it
+
+`particle_scene.js` holds the scene with every reference to the page removed, so
+`particle_scene.spec.js` can encode the same frames against `SoftwareGPUDevice`:
+
+```bash
+npx vitest run src/shade/playground/particle_system/particle_scene.spec.js
+```
+
+That mock runs no shaders, so the spec asserts nothing about what a pass computed. What it does
+assert is that the frame is legal and wired the way the design requires — pass order and
+attachments, the alive lists ping-ponging so no frame reads the list it appends to, the immediate
+blocks written before every dispatch that declares them, and simulate and the draw both taking their
+counts from the indirect buffers. Any WebGPU validation failure anywhere in the frame arrives as an
+uncaptured error, which every test fails on.
+
+The picture is the browser's job; the spec cannot see it.
+
+### Stepping frames by hand
+
+Add `?debug` to the URL. `requestAnimationFrame` is then not used at all, and `window.__step(n)`
+runs exactly `n` frames and returns the frame counter — which is what makes the loop drivable in a
+hidden or headless tab, where rAF is suspended. `window.__stats` carries the last counters snapshot.
+
+## What this page does not cover
+
+Depth sorting. `EMITTER_FLAG.SORT` and the bucketed depth sort in `particles/sort/` (histogram →
+csdldf scan → scatter) are not wired in here: the billboard pass draws the alive list directly, so
+alpha-blended emitters are in emission order rather than back-to-front. The two soft-depth emitters are faint and diffuse enough that it
+does not read as wrong, which is exactly why it should not be taken as evidence that sorting works.
+Lighting is the unlit hook, too — `chunk_particle_lighting_unlit`, not the shading-chunk-backed one
+the renderer feature swaps in.

package/src/shade/playground/particle_system/index.html

@@ -0,0 +1,124 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — GPU particle system</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --bg: #05070a;
+            --panel: #1c1f25e0;
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --fail: #ff6b6b;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body { height: 100%; }
+
+        body {
+            margin: 0;
+            overflow: hidden;
+            background: var(--bg);
+            color: var(--text);
+            font: 14px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        #view {
+            display: block;
+            width: 100%;
+            height: 100%;
+        }
+
+        #hud {
+            position: fixed;
+            top: 12px;
+            left: 12px;
+            min-width: 210px;
+            padding: 10px 12px;
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            background: var(--panel);
+            backdrop-filter: blur(6px);
+            font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+            font-size: 12px;
+            pointer-events: none;
+        }
+
+        #hud h1 {
+            font: inherit;
+            font-weight: 600;
+            margin: 0 0 6px;
+            letter-spacing: 0.04em;
+            text-transform: uppercase;
+            color: var(--muted);
+        }
+
+        #hud div { display: flex; gap: 10px; justify-content: space-between; }
+        #hud .key { color: var(--muted); }
+
+        #legend {
+            position: fixed;
+            bottom: 12px;
+            left: 12px;
+            max-width: 62ch;
+            padding: 10px 12px;
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            background: var(--panel);
+            backdrop-filter: blur(6px);
+            font-size: 12.5px;
+            color: var(--muted);
+            pointer-events: none;
+        }
+
+        #legend b { color: var(--text); font-weight: 600; }
+        #legend p { margin: 0 0 4px; }
+        #legend p:last-child { margin-bottom: 0; }
+
+        #message {
+            position: fixed;
+            inset: 0;
+            display: none;
+            align-items: center;
+            justify-content: center;
+            padding: 32px;
+            text-align: center;
+            background: #05070ae6;
+            color: var(--fail);
+            font-size: 16px;
+            white-space: pre-wrap;
+        }
+
+        #message:not(:empty) { display: flex; }
+    </style>
+</head>
+<body>
+
+<canvas id="view"></canvas>
+
+<div id="hud">
+    <h1>GPU particles</h1>
+    <div><span class="key">fps</span><span id="stat-fps">—</span></div>
+    <div><span class="key">alive</span><span id="stat-alive">—</span></div>
+    <div><span class="key">free</span><span id="stat-dead">—</span></div>
+    <div><span class="key">draw instances</span><span id="stat-draw">—</span></div>
+    <div><span class="key">sim workgroups</span><span id="stat-dispatch">—</span></div>
+</div>
+
+<div id="legend">
+    <p><b>Four emitters, one pool.</b> Additive fire at the pillar, an alpha soft-depth smoke column
+        above it, velocity-stretched sparks by the block, and a wide soft-depth dust drift.</p>
+    <p>Emit, simulate and the billboard draw are all GPU-sized — the simulate dispatch and the draw
+        read indirect args the build-indirect pass writes. The counters above are read back purely to
+        display; nothing on the CPU sizes a pass.</p>
+</div>
+
+<div id="message"></div>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>

package/src/shade/playground/particle_system/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/particle_system/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/main.js"],"names":[],"mappings":""}

package/src/shade/playground/particle_system/main.js

@@ -0,0 +1,180 @@
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import {
+    device_supports_immediate_size,
+    immediate_data_supported,
+} from "../../device/immediate_data_supported.js";
+import { GraphicsContext } from "../../renderer/GraphicsContext.js";
+import {
+    PARTICLE_IMMEDIATE_BYTES,
+    PARTICLE_STATS_BYTES,
+    create_particle_scene,
+} from "./particle_scene.js";
+
+/**
+ * The page for the GPU particle playground: acquire a device, build the scene
+ * ({@link ./particle_scene.js}, which is where the interesting part lives), and drive it from
+ * `requestAnimationFrame`.
+ *
+ * Serve the workspace with `npm run dev --workspace @woosh/meep-engine` and open
+ * `/src/shade/playground/particle_system/index.html`. See README.md for what to look at, and for
+ * the `?debug` query flag that swaps rAF for manual stepping.
+ */
+
+/** How often the counters are copied back for the overlay. Display only — nothing sizes a pass. */
+const STATS_INTERVAL_FRAMES = 30;
+
+/** Device pixels per CSS pixel, capped: 32k billboards at 3x cost more than they show. */
+const MAX_PIXEL_RATIO = 2;
+
+async function main() {
+    const canvas = document.getElementById("view");
+
+    if (navigator.gpu === undefined) {
+        return show_message("WebGPU is not available in this browser.");
+    }
+
+    const adapter = await navigator.gpu.requestAdapter();
+
+    if (adapter === null) {
+        return show_message("No WebGPU adapter — this browser exposes the API but has no usable GPU.");
+    }
+
+    const device = await adapter.requestDevice();
+    device.addEventListener?.("uncapturederror", (e) => console.error("WebGPU error:", e.error.message));
+
+    // Every compute pass here carries its per-dispatch state as immediate data, an optional
+    // capability. Refusing by name beats the pipeline-creation error a device without it raises,
+    // which names neither the shader nor the feature.
+    if (!immediate_data_supported() || !device_supports_immediate_size(device, PARTICLE_IMMEDIATE_BYTES)) {
+        return show_message(
+            "This browser's WebGPU offers no usable immediate data "
+            + `(needs ${PARTICLE_IMMEDIATE_BYTES} bytes, offers ${device.limits.maxImmediateSize ?? 0}).\n`
+            + "The particle emit / simulate / build-indirect passes all carry their per-dispatch\n"
+            + "state that way, so none of them can be built here."
+        );
+    }
+
+    const graphics = new GraphicsContext(device);
+    const context = canvas.getContext("webgpu");
+    const format = navigator.gpu.getPreferredCanvasFormat();
+    context.configure({ device, format, alphaMode: "opaque" });
+
+    const scene = create_particle_scene(graphics, { color_format: format });
+
+    // Manual frame stepping instead of rAF — opt in with ?debug. Useful for driving the loop a
+    // known number of frames in a headless / hidden tab, where rAF is suspended.
+    const debug = new URLSearchParams(location.search).has("debug");
+
+    const stats_buffer = device.createBuffer({
+        label: "particles/stats",
+        size: PARTICLE_STATS_BYTES,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+    let stats_pending = false;
+
+    let last = performance.now();
+    let frame_index = 0;
+    let fps = 0;
+
+    function frame(now) {
+        const dt = Math.min((now - last) / 1000, 0.05);
+        last = now;
+        // A rAF-driven loop steps by wall clock; ?debug steps by hand, where dt can be 0.
+        fps = dt > 0 ? fps * 0.9 + 0.1 / dt : fps;
+
+        // Back the canvas with device pixels, so a HiDPI display gets a sharp image rather than an
+        // upscaled CSS-pixel one.
+        const ratio = Math.min(window.devicePixelRatio || 1, MAX_PIXEL_RATIO);
+        const width = Math.max(1, Math.round(canvas.clientWidth * ratio));
+        const height = Math.max(1, Math.round(canvas.clientHeight * ratio));
+
+        if (canvas.width !== width || canvas.height !== height) {
+            canvas.width = width;
+            canvas.height = height;
+        }
+
+        const cmd = ShadeGPUCommandContext.create(graphics, "particles/frame");
+
+        scene.encode_frame(cmd, {
+            color_view: context.getCurrentTexture().createView(),
+            width,
+            height,
+            dt,
+            time: now / 1000,
+        });
+
+        const capture_stats = !stats_pending && frame_index % STATS_INTERVAL_FRAMES === 0;
+        if (capture_stats) {
+            scene.encode_stats_copy(cmd, stats_buffer);
+        }
+
+        cmd.finish();
+
+        frame_index++;
+
+        if (capture_stats) {
+            stats_pending = true;
+            stats_buffer.mapAsync(GPUMapMode.READ).then(() => {
+                const bytes = stats_buffer.getMappedRange().slice(0);
+                stats_buffer.unmap();
+                stats_pending = false;
+
+                window.__stats = { frame: frame_index, fps, ...scene.read_stats(bytes) };
+                write_hud(window.__stats);
+            }).catch(() => {
+                stats_pending = false;
+            });
+        }
+
+        if (!debug) {
+            requestAnimationFrame(frame);
+        }
+    }
+
+    if (debug) {
+        // Drive frames by hand when the tab is hidden (rAF suspended) — headless verification.
+        // Nothing is scheduled: a stray rAF frame interleaved with __step would make the count the
+        // caller asked for and the count that ran two different numbers.
+        window.__step = (n = 1) => {
+            for (let i = 0; i < n; i++) {
+                frame(performance.now());
+            }
+            return frame_index;
+        };
+        return;
+    }
+
+    requestAnimationFrame(frame);
+}
+
+/** Push one stats snapshot into the overlay. Absent elements are simply skipped. */
+function write_hud({ fps, alive, dead, dispatch, draw }) {
+    const put = (id, value) => {
+        const node = document.getElementById(id);
+        if (node !== null) {
+            node.textContent = value;
+        }
+    };
+
+    put("stat-fps", fps.toFixed(0));
+    put("stat-alive", alive.toLocaleString());
+    put("stat-dead", dead.toLocaleString());
+    put("stat-draw", draw[1].toLocaleString());
+    put("stat-dispatch", dispatch[0].toLocaleString());
+}
+
+function show_message(text) {
+    const existing = document.getElementById("message");
+    const node = existing ?? document.body.appendChild(document.createElement("div"));
+
+    if (existing === null) {
+        node.style.cssText = "position:fixed;inset:0;display:flex;align-items:center;justify-content:center;color:#fff;font-family:sans-serif;font-size:16px;white-space:pre-wrap;text-align:center";
+    }
+
+    node.textContent = text;
+}
+
+main().catch((e) => {
+    console.error(e);
+    show_message("The particle playground failed to start — see the console.\n\n" + e.message);
+});

package/src/shade/playground/particle_system/particle_scene.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @typedef {object} ParticleSceneStats
+ * @property {number} alive particles alive at the end of the captured frame
+ * @property {number} dead free slots left in the pool
+ * @property {number} alive_in the snapshot next frame's simulate reads as its input length
+ * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
+ * @property {number[]} draw the billboard draw's indirect args, `[vertices, instances]`
+ */
+/**
+ * Build the scene against a live (or mock) device.
+ *
+ * @param {GraphicsContext} graphics
+ * @param {object} options
+ * @param {GPUTextureFormat} options.color_format format of the colour target frames are encoded into
+ * @param {number} [options.capacity] particle pool size
+ * @returns {object} the scene, see the returned object's own members
+ */
+export function create_particle_scene(graphics: GraphicsContext, { color_format, capacity }: {
+    color_format: GPUTextureFormat;
+    capacity?: number;
+}): object;
+/**
+ * The largest immediate block any of the three compute passes declares (emit's 20-byte settings
+ * struct). Immediate data is an optional WebGPU capability, so callers check for it up front rather
+ * than letting pipeline creation fail with an error that names neither pass nor feature.
+ */
+export const PARTICLE_IMMEDIATE_BYTES: 20;
+/** Bytes of stats {@link ParticleScene#encode_stats_copy} writes: 8 counters, then both arg buffers. */
+export const PARTICLE_STATS_BYTES: 64;
+export type ParticleSceneStats = {
+    /**
+     * particles alive at the end of the captured frame
+     */
+    alive: number;
+    /**
+     * free slots left in the pool
+     */
+    dead: number;
+    /**
+     * the snapshot next frame's simulate reads as its input length
+     */
+    alive_in: number;
+    /**
+     * simulate's indirect dispatch args, `[x, y, z]` workgroups
+     */
+    dispatch: number[];
+    /**
+     * the billboard draw's indirect args, `[vertices, instances]`
+     */
+    draw: number[];
+};
+//# sourceMappingURL=particle_scene.d.ts.map

package/src/shade/playground/particle_system/particle_scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAwEA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH;IAJqC,YAAY;IACrB,QAAQ,GAAzB,MAAM;IACJ,MAAM,CA8OlB;AA3QD;;;;GAIG;AACH,0CAA2C;AAE3C,wGAAwG;AACxG,sCAAuC;;;;;WAOzB,MAAM;;;;UACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM,EAAE;;;;UACR,MAAM,EAAE"}