@woosh/meep-engine 3.10.0 → 3.11.1

package/src/shade/device/timing/profile/GPUProfileSession.js

@@ -0,0 +1,470 @@
+import { assert } from "../../../../core/assert.js";
+import { Signal } from "../../../../core/events/signal/Signal.js";
+import { GPUFrameRecorder } from "./GPUFrameRecorder.js";
+import { GPUProfileLevel, gpu_profile_level_name } from "./GPUProfileLevel.js";
+import { GPUProfileMeta } from "./GPUProfileMeta.js";
+import { SGPT_RECORD_TYPE } from "./SGPT_RECORD_TYPE.js";
+import { SGPTWriteStream } from "./SGPTWriteStream.js";
+import { sgpt_write_frame } from "./sgpt_frame_codec.js";
+import { sgpt_write_meta } from "./sgpt_meta_codec.js";
+import {
+    sgpt_intern_topology_symbols,
+    sgpt_topology_hash,
+    sgpt_write_topology
+} from "./sgpt_topology_codec.js";
+
+/**
+ * Default point at which an uncapped session starts saying how much it has accumulated. Does not
+ * stop anything — see {@link GPUProfileSession#byte_budget}.
+ *
+ * @type {number}
+ */
+const DEFAULT_BYTE_BUDGET = 512 * 1024 * 1024;
+
+/**
+ * A GPU profile recording, from `start` to `stop`.
+ *
+ * **The engine never constructs one of these.** The caller builds it and hands it over:
+ *
+ * ```js
+ * const session = new GPUProfileSession({ level: GPUProfileLevel.TIMING });
+ *
+ * renderer.profile_session = session;
+ *
+ * await session.start(graphics);
+ * // ... frames run, for as long as you like ...
+ * const bytes = await session.stop();
+ *
+ * renderer.profile_session = null;
+ * ```
+ *
+ * That ownership is the point rather than a style choice. **Nothing in the engine imports this file
+ * or anything it reaches** — the write stream, the format codecs, the topology extractor — so an
+ * application that never mentions the profiler does not carry any of it. The feature ships without
+ * a build flag, a strip-plugin interaction, or a dead branch anyone has to keep honest.
+ *
+ * Two leaf helpers under this directory *are* linked unconditionally, because
+ * {@link ShadeGPUCommandContext} needs them while encoding: `make_profiling_pass_encoder` and
+ * `parse_workgroup_size`. They import `assert` and nothing else, and neither knows what a capture
+ * is. What remains in the engine beyond those is a nullable field and the null checks around it.
+ *
+ * Recording is an **open-ended forward stream**: `frame_limit` defaults to `Infinity` and
+ * everything captured is kept. There is no ring buffer. Uncapped means a per-frame cost is also a
+ * per-second one, so the session reports what it is accumulating rather than letting an
+ * application find out when the tab dies.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileSession {
+
+    /**
+     * @type {number}
+     */
+    #level = GPUProfileLevel.TIMING;
+
+    /**
+     * @type {number}
+     */
+    #frame_limit = Infinity;
+
+    /**
+     * @type {string}
+     */
+    #note = "";
+
+    /**
+     * @type {SGPTWriteStream|null}
+     */
+    #stream = null;
+
+    /**
+     * @type {GPUProfileMeta}
+     */
+    #meta = new GPUProfileMeta();
+
+    /**
+     * @type {number}
+     */
+    #frames_recorded = 0;
+
+    /**
+     * @type {boolean}
+     */
+    #running = false;
+
+    /**
+     * @type {boolean}
+     */
+    #stopped = false;
+
+    /**
+     * @type {boolean}
+     */
+    #budget_warned = false;
+
+    /**
+     * Content hash of every topology already written, to the id it was given.
+     *
+     * The whole of the deduplication. A Shade frame graph is nearly identical frame to frame, so
+     * this map stays tiny and hundreds of frames share one entry — the difference between a capture
+     * of tens of megabytes and one of a couple.
+     *
+     * @type {Map<number, number>}
+     */
+    #topology_ids = new Map();
+
+    /**
+     * @type {number}
+     */
+    #topology_count = 0;
+
+    /**
+     * How many distinct frame graph structures this capture has needed.
+     *
+     * Worth watching: if this climbs with the frame count, the graph is changing shape every frame
+     * and the size estimates for a long capture do not hold.
+     *
+     * @returns {number}
+     */
+    get topology_count() {
+        return this.#topology_count;
+    }
+
+    /**
+     * Bytes at which the session warns — once — that it is getting large. It does **not** stop:
+     * full uncapped history is the behaviour that was asked for, and silently truncating a capture
+     * is worse than a large one.
+     *
+     * @type {number}
+     */
+    byte_budget = DEFAULT_BYTE_BUDGET;
+
+    /**
+     * Fires per frame with the running byte total.
+     *
+     * @readonly
+     * @type {Signal<number>}
+     */
+    onBytesWritten = new Signal();
+
+    /**
+     * Fires once, with the finished capture, however the session ended — `stop()` or the frame
+     * limit running out. Both paths land here so a caller can await one thing.
+     *
+     * @readonly
+     * @type {Signal<ArrayBuffer>}
+     */
+    onComplete = new Signal();
+
+    /**
+     * @param {object} [options]
+     * @param {number} [options.level] one of {@link GPUProfileLevel}
+     * @param {number} [options.frame_limit] frames to record before stopping on its own. `Infinity`
+     * by default — a session runs until `stop()`.
+     * @param {string} [options.note] whatever you want the capture to say about itself
+     */
+    constructor({
+                    level = GPUProfileLevel.TIMING,
+                    frame_limit = Infinity,
+                    note = ""
+                } = {}) {
+
+        assert.isInteger(level, 'level');
+        assert.isString(note, 'note');
+        assert.ok(
+            frame_limit === Infinity || (Number.isInteger(frame_limit) && frame_limit > 0),
+            `frame_limit must be a positive integer or Infinity, was ${frame_limit}`
+        );
+
+        this.#level = level;
+        this.#frame_limit = frame_limit;
+        this.#note = note;
+    }
+
+    /**
+     * @returns {number} one of {@link GPUProfileLevel}
+     */
+    get level() {
+        return this.#level;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    get is_running() {
+        return this.#running;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get frames_recorded() {
+        return this.#frames_recorded;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get bytes_written() {
+        return this.#stream === null ? 0 : this.#stream.bytes_written;
+    }
+
+    /**
+     * The metadata this capture will carry. Populate before {@link start}; it is written into the
+     * stream at that point and not read again.
+     *
+     * @returns {GPUProfileMeta}
+     */
+    get meta() {
+        return this.#meta;
+    }
+
+    /**
+     * Begin recording.
+     *
+     * {@link meta} is written into the stream here and not read again, so populate it first.
+     *
+     * @returns {void}
+     */
+    start() {
+        assert.notOk(this.#running, 'session already started');
+        assert.notOk(this.#stopped, 'a stopped session cannot be restarted; construct a new one');
+
+        const meta = this.#meta;
+
+        meta.level = this.#level;
+        meta.note = this.#note;
+
+        if (meta.wall_clock_start_ms === 0) {
+            meta.wall_clock_start_ms = Date.now();
+        }
+
+        const stream = new SGPTWriteStream();
+
+        stream.write_record(SGPT_RECORD_TYPE.META, sgpt_write_meta, meta);
+
+        this.#stream = stream;
+        this.#running = true;
+    }
+
+    /**
+     * Open a recorder for a frame about to be encoded, or null when nothing should be recorded.
+     *
+     * **This is why the renderer imports nothing from the profiler.** It holds a nullable session
+     * and calls methods on it; the recorder type never appears in its module graph, so the whole
+     * profiler stays unreachable from any engine entry point and drops out of a bundle that does
+     * not ask for it. A `new GPUFrameRecorder(...)` in the renderer would have quietly undone that.
+     *
+     * @param {number} frame_index the renderer's own frame counter
+     * @param {number} cpu_begin_ms
+     * @returns {GPUFrameRecorder|null}
+     */
+    begin_frame(frame_index, cpu_begin_ms) {
+        if (!this.#running) {
+            return null;
+        }
+
+        const recorder = new GPUFrameRecorder(frame_index, cpu_begin_ms);
+
+        if (this.#level >= GPUProfileLevel.STRUCTURE) {
+            recorder.enable_structure_capture();
+        }
+
+        if (this.#level >= GPUProfileLevel.WORKLOAD) {
+            recorder.enable_work_capture();
+        }
+
+        return recorder;
+    }
+
+    /**
+     * Close a recorder opened by {@link begin_frame} and commit what it collected.
+     *
+     * @param {GPUFrameRecorder} recorder
+     * @param {number} cpu_submit_ms
+     * @returns {void}
+     */
+    end_frame(recorder, cpu_submit_ms) {
+        assert.defined(recorder, 'recorder');
+
+        this.record_frame(recorder.close(cpu_submit_ms));
+    }
+
+    /**
+     * Write a topology if this shape has not been seen, and return the id either way.
+     *
+     * @param {GPUProfileTopology} topology
+     * @returns {number}
+     */
+    #write_topology(topology) {
+        const hash = sgpt_topology_hash(topology);
+
+        const existing = this.#topology_ids.get(hash);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const id = this.#topology_count++;
+
+        topology.id = id;
+
+        this.#topology_ids.set(hash, id);
+
+        const stream = this.#stream;
+
+        // Ahead of the record, for the same reason frame span labels are — a `SYMS` block must
+        // precede whatever references it, or a capture truncated in between resolves no names.
+        sgpt_intern_topology_symbols(topology, value => stream.intern(value));
+
+        stream.write_record(
+            SGPT_RECORD_TYPE.TOPO,
+            (buffer, t) => sgpt_write_topology(buffer, t, value => stream.intern(value)),
+            topology
+        );
+
+        return id;
+    }
+
+    /**
+     * Commit one frame.
+     *
+     * Ignored when the session is not running, so a frame that lands after `stop()` — the readback
+     * for a frame already submitted, which is the ordinary case — is dropped rather than throwing
+     * inside somebody's render loop.
+     *
+     * @param {GPUProfileFrame} frame
+     * @returns {void}
+     */
+    record_frame(frame) {
+        assert.defined(frame, 'frame');
+
+        if (!this.#running) {
+            return;
+        }
+
+        const stream = this.#stream;
+
+        // Reserve before writing, so the buffer's growth — an allocation and a copy — happens here
+        // at the boundary rather than part-way through encoding a frame.
+        stream.reserve_frame();
+
+        if (frame.topology !== null && frame.topology !== undefined) {
+            frame.topology_id = this.#write_topology(frame.topology);
+        }
+
+        /*
+         Intern every name this frame uses *before* the record is opened.
+
+         `write_record` flushes pending symbols ahead of the record it is about to write, and
+         interning from inside the payload writer is too late for that — the symbols would land in
+         the *next* flush, behind the record referencing them. A reader of a capture truncated in
+         between then resolves none of them, which is the failure this format exists to avoid.
+
+         Doing it here rather than inside the stream keeps the stream ignorant of the frame model.
+        */
+        for (const span of frame.spans) {
+            stream.intern(span.label);
+
+            if (span.work !== null && span.work !== undefined) {
+                stream.intern(span.work.pipeline);
+            }
+        }
+
+        stream.write_record(
+            SGPT_RECORD_TYPE.FRAM,
+            (buffer, f) => sgpt_write_frame(buffer, f, value => stream.intern(value)),
+            frame
+        );
+
+        this.#frames_recorded++;
+
+        const bytes = stream.bytes_written;
+
+        if (this.onBytesWritten.hasHandlers()) {
+            this.onBytesWritten.send1(bytes);
+        }
+
+        if (!this.#budget_warned && bytes >= this.byte_budget) {
+            this.#budget_warned = true;
+
+            const per_frame = Math.round(bytes / this.#frames_recorded);
+
+            console.warn(
+                `GPUProfileSession: ${(bytes / (1024 * 1024)).toFixed(0)} MiB after `
+                + `${this.#frames_recorded} frames at level ${gpu_profile_level_name(this.#level)} `
+                + `(~${per_frame} bytes/frame). Recording continues — call stop() when you have enough.`
+            );
+        }
+
+        if (this.#frames_recorded >= this.#frame_limit) {
+            this.stop();
+        }
+    }
+
+    /**
+     * The capture as it stands, without ending the session.
+     *
+     * Reads back as a capture that was cut short — no directory, not marked closed — because that
+     * is precisely what it is. Recording continues afterwards.
+     *
+     * @returns {ArrayBuffer}
+     */
+    snapshot() {
+        assert.ok(this.#running, 'session is not running');
+
+        return this.#stream.snapshot();
+    }
+
+    /**
+     * End the recording and hand back the capture.
+     *
+     * Calling it twice returns the same bytes rather than complaining; a session that hit its
+     * frame limit has already stopped itself, and the caller awaiting `stop()` should still get
+     * the capture.
+     *
+     * @returns {ArrayBuffer}
+     */
+    stop() {
+        if (this.#stopped) {
+            return this.#result;
+        }
+
+        assert.ok(this.#running, 'session was never started');
+
+        this.#running = false;
+        this.#stopped = true;
+
+        this.#result = this.#stream.finish();
+
+        this.onComplete.send1(this.#result);
+
+        return this.#result;
+    }
+
+    /**
+     * @type {ArrayBuffer|null}
+     */
+    #result = null;
+
+    /**
+     * Resolves with the capture when the session ends, whichever way it ends.
+     *
+     * @returns {Promise<ArrayBuffer>}
+     */
+    get done() {
+        if (this.#stopped) {
+            return Promise.resolve(this.#result);
+        }
+
+        return new Promise(resolve => {
+            this.onComplete.addOne(resolve);
+
+            if (this.#stopped) {
+                // guard against the session ending between the check above and the subscription
+                resolve(this.#result);
+            }
+        });
+    }
+}

package/src/shade/device/timing/profile/GPUProfileSpan.d.ts

@@ -0,0 +1,60 @@
+/**
+ * One GPU pass, as the device timed it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileSpan {
+    /**
+     * The pass label, as it was given to `beginComputePass` / `beginRenderPass`.
+     *
+     * **Not a key.** Labels are neither unique nor stable, and one frame graph pass routinely opens
+     * several GPU passes with labels of their own — see {@link FrameGraph#onPassBegin}. At
+     * {@link GPUProfileLevel.STRUCTURE} and above, {@link graph_pass_id} is what identifies who
+     * recorded this.
+     *
+     * @type {string}
+     */
+    label: string;
+    /**
+     * 'compute' or 'render'.
+     * @type {string}
+     */
+    kind: string;
+    /**
+     * Nanoseconds from the frame's GPU epoch.
+     * @type {number}
+     */
+    t_begin_ns: number;
+    /**
+     * Nanoseconds. Never negative — see {@link sgpt_write_frame} for what a device reporting an end
+     * before its begin is taken to mean.
+     * @type {number}
+     */
+    duration_ns: number;
+    /**
+     * Which query set produced this. Timestamps from two different sets are not specified to share
+     * a clock domain, and a frame already spans several — one per command context. Carried so an
+     * anomaly that follows a set boundary is visible rather than unfalsifiable.
+     * @type {number}
+     */
+    query_set_id: number;
+    /**
+     * Id of the frame graph pass that was executing when this pass was opened, or -1 when nothing
+     * was — work encoded outside the graph, or a capture below
+     * {@link GPUProfileLevel.STRUCTURE}.
+     * @type {number}
+     */
+    graph_pass_id: number;
+    /**
+     * What this pass was asked to do — dispatch and draw counts, the pipeline, the workgroup size.
+     *
+     * Null below {@link GPUProfileLevel.WORKLOAD}, which is not the same as a pass that did
+     * nothing. A duration on its own says a pass is slow; this is what says whether it is slow
+     * because it is doing too much or because it is doing it badly.
+     *
+     * @type {GPUProfileWork|null}
+     */
+    work: GPUProfileWork | null;
+}
+//# sourceMappingURL=GPUProfileSpan.d.ts.map

package/src/shade/device/timing/profile/GPUProfileSpan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileSpan.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileSpan.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;;;;;;;;OASG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,eAFU,MAAM,CAEG;IAEnB;;;;;;;;OAQG;IACH,MAFU,iBAAe,IAAI,CAEjB;CACf"}

package/src/shade/device/timing/profile/GPUProfileSpan.js

@@ -0,0 +1,65 @@
+/**
+ * One GPU pass, as the device timed it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileSpan {
+    /**
+     * The pass label, as it was given to `beginComputePass` / `beginRenderPass`.
+     *
+     * **Not a key.** Labels are neither unique nor stable, and one frame graph pass routinely opens
+     * several GPU passes with labels of their own — see {@link FrameGraph#onPassBegin}. At
+     * {@link GPUProfileLevel.STRUCTURE} and above, {@link graph_pass_id} is what identifies who
+     * recorded this.
+     *
+     * @type {string}
+     */
+    label = "";
+
+    /**
+     * 'compute' or 'render'.
+     * @type {string}
+     */
+    kind = "compute";
+
+    /**
+     * Nanoseconds from the frame's GPU epoch.
+     * @type {number}
+     */
+    t_begin_ns = 0;
+
+    /**
+     * Nanoseconds. Never negative — see {@link sgpt_write_frame} for what a device reporting an end
+     * before its begin is taken to mean.
+     * @type {number}
+     */
+    duration_ns = 0;
+
+    /**
+     * Which query set produced this. Timestamps from two different sets are not specified to share
+     * a clock domain, and a frame already spans several — one per command context. Carried so an
+     * anomaly that follows a set boundary is visible rather than unfalsifiable.
+     * @type {number}
+     */
+    query_set_id = 0;
+
+    /**
+     * Id of the frame graph pass that was executing when this pass was opened, or -1 when nothing
+     * was — work encoded outside the graph, or a capture below
+     * {@link GPUProfileLevel.STRUCTURE}.
+     * @type {number}
+     */
+    graph_pass_id = -1;
+
+    /**
+     * What this pass was asked to do — dispatch and draw counts, the pipeline, the workgroup size.
+     *
+     * Null below {@link GPUProfileLevel.WORKLOAD}, which is not the same as a pass that did
+     * nothing. A duration on its own says a pass is slow; this is what says whether it is slow
+     * because it is doing too much or because it is doing it badly.
+     *
+     * @type {GPUProfileWork|null}
+     */
+    work = null;
+}

package/src/shade/device/timing/profile/GPUProfileSpanKind.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @param {string} name 'compute' or 'render'
+ * @returns {number} one of {@link GPUProfileSpanKind}
+ */
+export function gpu_profile_span_kind_from_name(name: string): number;
+/**
+ * @param {number} kind one of {@link GPUProfileSpanKind}
+ * @returns {string}
+ */
+export function gpu_profile_span_kind_name(kind: number): string;
+/**
+ * How a pass kind is written on the wire. One byte; the strings live in the model.
+ */
+export type GPUProfileSpanKind = number;
+export namespace GPUProfileSpanKind {
+    let COMPUTE: number;
+    let RENDER: number;
+}
+//# sourceMappingURL=GPUProfileSpanKind.d.ts.map

package/src/shade/device/timing/profile/GPUProfileSpanKind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileSpanKind.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileSpanKind.js"],"names":[],"mappings":"AAUA;;;GAGG;AACH,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;GAGG;AACH,iDAHW,MAAM,GACJ,MAAM,CAIlB;;;;iCArBS,MAAM"}

package/src/shade/device/timing/profile/GPUProfileSpanKind.js

@@ -0,0 +1,25 @@
+/**
+ * How a pass kind is written on the wire. One byte; the strings live in the model.
+ *
+ * @enum {number}
+ */
+export const GPUProfileSpanKind = {
+    COMPUTE: 0,
+    RENDER: 1
+};
+
+/**
+ * @param {string} name 'compute' or 'render'
+ * @returns {number} one of {@link GPUProfileSpanKind}
+ */
+export function gpu_profile_span_kind_from_name(name) {
+    return name === 'render' ? GPUProfileSpanKind.RENDER : GPUProfileSpanKind.COMPUTE;
+}
+
+/**
+ * @param {number} kind one of {@link GPUProfileSpanKind}
+ * @returns {string}
+ */
+export function gpu_profile_span_kind_name(kind) {
+    return kind === GPUProfileSpanKind.RENDER ? 'render' : 'compute';
+}