npm - @woosh/meep-engine - Versions diffs - 3.14.3 → 3.14.4 - Mend

@woosh/meep-engine 3.14.3 → 3.14.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

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

@@ -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 ADDED Viewed

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

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

	@@ -0,0 +1 @@
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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

	@@ -0,0 +1 @@
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"}