@woosh/meep-engine 3.10.0 → 3.11.0

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

@@ -0,0 +1,93 @@
+/**
+ * Assembles one frame's worth of profile data, and holds the join that nothing else can supply.
+ *
+ * **The join.** A GPU pass is timed by slot, and a slot knows only the label the pass was opened
+ * with. Labels are not keys: one frame graph node routinely opens several GPU passes under labels
+ * of their own choosing, so which node produced a given span cannot be worked out after the fact.
+ * What can be known is *when* — a pass opened while a node was executing belongs to that node. This
+ * class listens to {@link FrameGraph#onPassBegin} for the node, takes slot ids from the command
+ * context as passes open, and pairs them. Attribution is recorded, never inferred.
+ *
+ * One recorder per frame. It accumulates across every command context in that frame, because a
+ * frame has several and their spans belong to the same picture.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUFrameRecorder {
+    /**
+     * @param {number} frame_index the renderer's own frame counter
+     * @param {number} cpu_begin_ms
+     */
+    constructor(frame_index: number, cpu_begin_ms: number);
+    /**
+     * Record dispatch and draw counts as well as timings.
+     *
+     * @returns {void}
+     */
+    enable_work_capture(): void;
+    /**
+     * Record structure as well as timings when this recorder closes.
+     *
+     * @returns {void}
+     */
+    enable_structure_capture(): void;
+    /**
+     * @returns {GPUProfileFrame}
+     */
+    get frame(): GPUProfileFrame;
+    /**
+     * Follow a graph's pass boundaries for as long as it is executing.
+     *
+     * @param {FrameGraph} graph
+     * @returns {void}
+     */
+    attach_graph(graph: FrameGraph): void;
+    /**
+     * Stop following every graph attached to this recorder.
+     *
+     * A frame graph is single-use and discarded at the end of the frame, so this is belt and
+     * braces rather than a leak fix — but a recorder outliving its frame while still holding
+     * handlers would attribute the *next* frame's passes to this one's nodes.
+     *
+     * @returns {void}
+     */
+    detach_graphs(): void;
+    /**
+     * A pass has just claimed a timer slot. Called by {@link ShadeGPUCommandContext} at the moment
+     * the pass is opened, which is the only moment at which the owning graph pass is known.
+     *
+     * @param {number} query_set_id
+     * @param {number} slot_id
+     * @returns {GPUProfileWork|null} to accumulate this pass's encoded work into, or null when the
+     * capture level does not ask for it
+     */
+    note_pass_slot(query_set_id: number, slot_id: number): GPUProfileWork | null;
+    /**
+     * Take the timings from one command context's timer array.
+     *
+     * Called after the results have been downloaded, so once per context per frame and always
+     * asynchronously with respect to the frame that produced them.
+     *
+     * @param {GPUTimerArray} timers
+     * @param {number} query_set_id which context this was, within the frame
+     * @returns {void}
+     */
+    absorb(timers: GPUTimerArray, query_set_id: number): void;
+    /**
+     * Finish the frame: rebase every span onto the frame's own epoch and hand it over.
+     *
+     * Rebasing happens here rather than per span because the epoch is the earliest timestamp in
+     * the frame, and that is not known until the last command context has reported. Absolute
+     * timestamps carry a large arbitrary origin; frame-relative ones fit a u32 with three orders
+     * of magnitude to spare.
+     *
+     * @param {number} cpu_submit_ms
+     * @returns {GPUProfileFrame}
+     */
+    close(cpu_submit_ms: number): GPUProfileFrame;
+    #private;
+}
+import { GPUProfileFrame } from "./GPUProfileFrame.js";
+import { GPUProfileWork } from "./GPUProfileWork.js";
+//# sourceMappingURL=GPUFrameRecorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUFrameRecorder.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUFrameRecorder.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH;IAkFI;;;OAGG;IACH,yBAHW,MAAM,gBACN,MAAM,EAQhB;IAtDD;;;;OAIG;IACH,uBAFa,IAAI,CAIhB;IAqBD;;;;OAIG;IACH,4BAFa,IAAI,CAIhB;IAED;;OAEG;IACH,6BAEC;IAcD;;;;;OAKG;IACH,iCAFa,IAAI,CAiBhB;IAED;;;;;;;;OAQG;IACH,iBAFa,IAAI,CAShB;IAWD;;;;;;;;OAQG;IACH,6BALW,MAAM,WACN,MAAM,GACJ,cAAc,GAAC,IAAI,CAiB/B;IAED;;;;;;;;;OASG;IACH,4CAHW,MAAM,GACJ,IAAI,CAqChB;IAED;;;;;;;;;;OAUG;IACH,qBAHW,MAAM,GACJ,eAAe,CAgD3B;;CACJ;gCAvS+B,sBAAsB;+BAEvB,qBAAqB"}

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

@@ -0,0 +1,297 @@
+import { assert } from "../../../../core/assert.js";
+import { GPUProfileFrame } from "./GPUProfileFrame.js";
+import { GPUProfileSpan } from "./GPUProfileSpan.js";
+import { GPUProfileWork } from "./GPUProfileWork.js";
+import { frame_graph_extract_topology } from "./frame_graph_extract_topology.js";
+
+/**
+ * Assembles one frame's worth of profile data, and holds the join that nothing else can supply.
+ *
+ * **The join.** A GPU pass is timed by slot, and a slot knows only the label the pass was opened
+ * with. Labels are not keys: one frame graph node routinely opens several GPU passes under labels
+ * of their own choosing, so which node produced a given span cannot be worked out after the fact.
+ * What can be known is *when* — a pass opened while a node was executing belongs to that node. This
+ * class listens to {@link FrameGraph#onPassBegin} for the node, takes slot ids from the command
+ * context as passes open, and pairs them. Attribution is recorded, never inferred.
+ *
+ * One recorder per frame. It accumulates across every command context in that frame, because a
+ * frame has several and their spans belong to the same picture.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUFrameRecorder {
+
+    /**
+     * @type {GPUProfileFrame}
+     */
+    #frame = new GPUProfileFrame();
+
+    /**
+     * The graph pass currently executing, or -1 outside of one. Work encoded outside any graph pass
+     * is real and worth recording; it simply has no node to blame.
+     *
+     * @type {number}
+     */
+    #current_graph_pass_id = -1;
+
+    /**
+     * Which graph pass owned each timer slot, indexed by `query_set_id * SLOT_SPACE + slot_id`.
+     *
+     * A map rather than an array because slot ids restart per command context, and a frame has
+     * several.
+     *
+     * @type {Map<string, number>}
+     */
+    #slot_owner = new Map();
+
+    /**
+     * What each timer slot's pass was asked to do, keyed the same way. Populated only while
+     * recording at {@link GPUProfileLevel.WORKLOAD} or above.
+     *
+     * @type {Map<string, GPUProfileWork>}
+     */
+    #slot_work = new Map();
+
+    /**
+     * @type {boolean}
+     */
+    #capture_work = false;
+
+    /**
+     * Record dispatch and draw counts as well as timings.
+     *
+     * @returns {void}
+     */
+    enable_work_capture() {
+        this.#capture_work = true;
+    }
+
+    /**
+     * Graphs this recorder is subscribed to, so it can unsubscribe.
+     *
+     * @type {{graph: FrameGraph, begin: function, end: function}[]}
+     */
+    #subscriptions = [];
+
+    /**
+     * @type {boolean}
+     */
+    #closed = false;
+
+    /**
+     * Whether to record the frame graph's structure alongside its timings.
+     *
+     * @type {boolean}
+     */
+    #capture_structure = false;
+
+    /**
+     * Record structure as well as timings when this recorder closes.
+     *
+     * @returns {void}
+     */
+    enable_structure_capture() {
+        this.#capture_structure = true;
+    }
+
+    /**
+     * @returns {GPUProfileFrame}
+     */
+    get frame() {
+        return this.#frame;
+    }
+
+    /**
+     * @param {number} frame_index the renderer's own frame counter
+     * @param {number} cpu_begin_ms
+     */
+    constructor(frame_index, cpu_begin_ms) {
+        assert.isNonNegativeInteger(frame_index, 'frame_index');
+        assert.isNumber(cpu_begin_ms, 'cpu_begin_ms');
+
+        this.#frame.frame_index = frame_index;
+        this.#frame.cpu_begin_ms = cpu_begin_ms;
+    }
+
+    /**
+     * Follow a graph's pass boundaries for as long as it is executing.
+     *
+     * @param {FrameGraph} graph
+     * @returns {void}
+     */
+    attach_graph(graph) {
+        assert.defined(graph, 'graph');
+
+        const begin = (node) => {
+            this.#current_graph_pass_id = node.id;
+        };
+
+        const end = () => {
+            this.#current_graph_pass_id = -1;
+        };
+
+        graph.onPassBegin.add(begin);
+        graph.onPassEnd.add(end);
+
+        this.#subscriptions.push({ graph, begin, end });
+    }
+
+    /**
+     * Stop following every graph attached to this recorder.
+     *
+     * A frame graph is single-use and discarded at the end of the frame, so this is belt and
+     * braces rather than a leak fix — but a recorder outliving its frame while still holding
+     * handlers would attribute the *next* frame's passes to this one's nodes.
+     *
+     * @returns {void}
+     */
+    detach_graphs() {
+        for (const { graph, begin, end } of this.#subscriptions) {
+            graph.onPassBegin.remove(begin);
+            graph.onPassEnd.remove(end);
+        }
+
+        this.#subscriptions.length = 0;
+    }
+
+    /**
+     * @param {number} query_set_id
+     * @param {number} slot_id
+     * @returns {string}
+     */
+    #slot_key(query_set_id, slot_id) {
+        return `${query_set_id}:${slot_id}`;
+    }
+
+    /**
+     * A pass has just claimed a timer slot. Called by {@link ShadeGPUCommandContext} at the moment
+     * the pass is opened, which is the only moment at which the owning graph pass is known.
+     *
+     * @param {number} query_set_id
+     * @param {number} slot_id
+     * @returns {GPUProfileWork|null} to accumulate this pass's encoded work into, or null when the
+     * capture level does not ask for it
+     */
+    note_pass_slot(query_set_id, slot_id) {
+        const key = this.#slot_key(query_set_id, slot_id);
+
+        this.#slot_owner.set(key, this.#current_graph_pass_id);
+
+        if (!this.#capture_work) {
+            return null;
+        }
+
+        const work = new GPUProfileWork();
+
+        this.#slot_work.set(key, work);
+
+        return work;
+    }
+
+    /**
+     * Take the timings from one command context's timer array.
+     *
+     * Called after the results have been downloaded, so once per context per frame and always
+     * asynchronously with respect to the frame that produced them.
+     *
+     * @param {GPUTimerArray} timers
+     * @param {number} query_set_id which context this was, within the frame
+     * @returns {void}
+     */
+    absorb(timers, query_set_id) {
+        assert.defined(timers, 'timers');
+        assert.isNonNegativeInteger(query_set_id, 'query_set_id');
+
+        if (this.#closed) {
+            // The frame was committed before this context's readback landed. Dropping it is
+            // correct — the alternative is mutating a frame already written to the stream.
+            return;
+        }
+
+        const frame = this.#frame;
+
+        timers.traverse_results((slot_id, label, type, t_begin, t_end) => {
+            const span = new GPUProfileSpan();
+
+            span.label = label;
+            span.kind = type;
+            span.query_set_id = query_set_id;
+
+            const key = this.#slot_key(query_set_id, slot_id);
+
+            const owner = this.#slot_owner.get(key);
+
+            span.graph_pass_id = owner === undefined ? -1 : owner;
+
+            span.work = this.#slot_work.get(key) ?? null;
+
+            // stored absolutely for now; `close` rebases the whole frame once every context is in
+            span.t_begin_ns = t_begin;
+            span.duration_ns = t_end > t_begin ? Number(t_end - t_begin) : 0;
+
+            frame.spans.push(span);
+        });
+
+        frame.dropped_pass_count += timers.dropped_count;
+    }
+
+    /**
+     * Finish the frame: rebase every span onto the frame's own epoch and hand it over.
+     *
+     * Rebasing happens here rather than per span because the epoch is the earliest timestamp in
+     * the frame, and that is not known until the last command context has reported. Absolute
+     * timestamps carry a large arbitrary origin; frame-relative ones fit a u32 with three orders
+     * of magnitude to spare.
+     *
+     * @param {number} cpu_submit_ms
+     * @returns {GPUProfileFrame}
+     */
+    close(cpu_submit_ms) {
+        assert.notOk(this.#closed, 'frame recorder already closed');
+
+        this.#closed = true;
+
+        const frame = this.#frame;
+
+        /*
+         Extracted here rather than at `attach_graph`, because reference counts and cull decisions
+         are what `compile` derives and the graph has not been compiled yet when it is attached.
+         Reading it before then records a frame in which every pass was culled.
+
+         Only the first graph is taken. A frame runs one — the shading graph — and anything else
+         attached is a subgraph whose passes are already in it.
+        */
+        if (this.#capture_structure && this.#subscriptions.length > 0) {
+            frame.topology = frame_graph_extract_topology(this.#subscriptions[0].graph);
+        }
+
+        this.detach_graphs();
+
+        frame.cpu_submit_ms = cpu_submit_ms;
+
+        const spans = frame.spans;
+
+        if (spans.length === 0) {
+            return frame;
+        }
+
+        let epoch = spans[0].t_begin_ns;
+
+        for (const span of spans) {
+            if (span.t_begin_ns < epoch) {
+                epoch = span.t_begin_ns;
+            }
+        }
+
+        frame.gpu_epoch_ns = epoch;
+
+        for (const span of spans) {
+            span.t_begin_ns = Number(span.t_begin_ns - epoch);
+        }
+
+        spans.sort((a, b) => a.t_begin_ns - b.t_begin_ns);
+
+        return frame;
+    }
+}

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

@@ -0,0 +1,62 @@
+/**
+ * A decoded `.sgpt` capture.
+ *
+ * Returned whole even when damaged. {@link defects} is not an error channel to check before
+ * trusting the rest — a capture of a GPU falling over ends mid-record by definition, and the
+ * records before the cut are the evidence. The inspector's job is to show what is here and say
+ * plainly what is not.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileCapture {
+    /**
+     * @type {SGPTHeader|null}
+     */
+    header: SGPTHeader | null;
+    /**
+     * @type {GPUProfileMeta}
+     */
+    meta: GPUProfileMeta;
+    /**
+     * @type {GPUProfileFrame[]}
+     */
+    frames: GPUProfileFrame[];
+    /**
+     * Frame graph structures, indexed by `GPUProfileFrame.topology_id`. Empty for a capture
+     * recorded below {@link GPUProfileLevel.STRUCTURE}.
+     *
+     * Far fewer than there are frames: the graph is nearly identical frame to frame, so a long
+     * capture typically holds a handful — the steady state, plus whatever varies with it.
+     *
+     * @type {GPUProfileTopology[]}
+     */
+    topologies: GPUProfileTopology[];
+    /**
+     * Record types present in the stream that this build does not understand, and how many of each.
+     *
+     * Skipping them is correct — that is what the framing is for — but staying quiet about it is
+     * not. A newer recorder produced something here, and the reader should be able to say so.
+     *
+     * @type {Map<number, number>}
+     */
+    unknown_record_counts: Map<number, number>;
+    /**
+     * @type {SGPTDefect[]}
+     */
+    defects: SGPTDefect[];
+    /**
+     * The structure of `frame`, or null when the capture carries none.
+     *
+     * @param {GPUProfileFrame} frame
+     * @returns {GPUProfileTopology|null}
+     */
+    topology_of(frame: GPUProfileFrame): GPUProfileTopology | null;
+    /**
+     * Whether the writer reached `stop()`.
+     * @returns {boolean}
+     */
+    get is_complete(): boolean;
+}
+import { GPUProfileMeta } from "./GPUProfileMeta.js";
+//# sourceMappingURL=GPUProfileCapture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileCapture.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileCapture.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH;IACI;;OAEG;IACH,QAFU,aAAW,IAAI,CAEX;IAEd;;OAEG;IACH,MAFU,cAAc,CAEI;IAE5B;;OAEG;IACH,QAFU,iBAAiB,CAEf;IAEZ;;;;;;;;OAQG;IACH,YAFU,oBAAoB,CAEd;IAEhB;;;;;;;OAOG;IACH,uBAFU,IAAI,MAAM,EAAE,MAAM,CAAC,CAEK;IAElC;;OAEG;IACH,SAFU,YAAY,CAET;IAEb;;;;;OAKG;IACH,qCAFa,qBAAmB,IAAI,CAQnC;IAED;;;OAGG;IACH,2BAEC;CACJ;+BA5E8B,qBAAqB"}

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

@@ -0,0 +1,77 @@
+import { GPUProfileMeta } from "./GPUProfileMeta.js";
+
+/**
+ * A decoded `.sgpt` capture.
+ *
+ * Returned whole even when damaged. {@link defects} is not an error channel to check before
+ * trusting the rest — a capture of a GPU falling over ends mid-record by definition, and the
+ * records before the cut are the evidence. The inspector's job is to show what is here and say
+ * plainly what is not.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileCapture {
+    /**
+     * @type {SGPTHeader|null}
+     */
+    header = null;
+
+    /**
+     * @type {GPUProfileMeta}
+     */
+    meta = new GPUProfileMeta();
+
+    /**
+     * @type {GPUProfileFrame[]}
+     */
+    frames = [];
+
+    /**
+     * Frame graph structures, indexed by `GPUProfileFrame.topology_id`. Empty for a capture
+     * recorded below {@link GPUProfileLevel.STRUCTURE}.
+     *
+     * Far fewer than there are frames: the graph is nearly identical frame to frame, so a long
+     * capture typically holds a handful — the steady state, plus whatever varies with it.
+     *
+     * @type {GPUProfileTopology[]}
+     */
+    topologies = [];
+
+    /**
+     * Record types present in the stream that this build does not understand, and how many of each.
+     *
+     * Skipping them is correct — that is what the framing is for — but staying quiet about it is
+     * not. A newer recorder produced something here, and the reader should be able to say so.
+     *
+     * @type {Map<number, number>}
+     */
+    unknown_record_counts = new Map();
+
+    /**
+     * @type {SGPTDefect[]}
+     */
+    defects = [];
+
+    /**
+     * The structure of `frame`, or null when the capture carries none.
+     *
+     * @param {GPUProfileFrame} frame
+     * @returns {GPUProfileTopology|null}
+     */
+    topology_of(frame) {
+        if (frame.topology_id < 0) {
+            return null;
+        }
+
+        return this.topologies[frame.topology_id] ?? null;
+    }
+
+    /**
+     * Whether the writer reached `stop()`.
+     * @returns {boolean}
+     */
+    get is_complete() {
+        return this.header !== null && this.header.is_closed;
+    }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * One recorded frame.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileFrame {
+    /**
+     * The renderer's own frame counter, not this frame's position in the capture. A capture started
+     * mid-session does not begin at zero, and a frame that dropped its records leaves a gap — both
+     * of which are worth seeing.
+     * @type {number}
+     */
+    frame_index: number;
+    /**
+     * `performance.now()` when the frame began encoding.
+     * @type {number}
+     */
+    cpu_begin_ms: number;
+    /**
+     * `performance.now()` when the command buffer was submitted.
+     * @type {number}
+     */
+    cpu_submit_ms: number;
+    /**
+     * The GPU timestamp all of this frame's spans are relative to — the earliest of them.
+     *
+     * There is no calibration between this clock and `performance.now()`; WebGPU exposes none. The
+     * CPU and GPU tracks are anchored per frame at submission and that anchoring is nominal, which
+     * is a thing to say out loud rather than paper over.
+     *
+     * @type {bigint}
+     */
+    gpu_epoch_ns: bigint;
+    /**
+     * Index into the capture's topology list, or -1 when the capture was recorded below
+     * {@link GPUProfileLevel.STRUCTURE} and has no structure to point at.
+     *
+     * Many frames share one: the graph is nearly identical frame to frame, so the structure is
+     * stored once and referenced.
+     *
+     * @type {number}
+     */
+    topology_id: number;
+    /**
+     * The structure this frame ran, before the session has deduplicated it.
+     *
+     * Transient: the session hashes it, writes it if the shape is new, sets {@link topology_id},
+     * and never looks at this again. A frame decoded from a capture has `null` here and the id
+     * instead — the structure lives once, in the capture, rather than once per frame.
+     *
+     * @type {GPUProfileTopology|null}
+     */
+    topology: GPUProfileTopology | null;
+    /**
+     * @type {GPUProfileSpan[]}
+     */
+    spans: GPUProfileSpan[];
+    /**
+     * Passes that went untimed because the frame had more of them than the timer array had slots.
+     * @see GPUTimerArray#dropped_count
+     * @type {number}
+     */
+    dropped_pass_count: number;
+    /**
+     * Total GPU time across this frame's spans. Spans can overlap on some hardware, so this is a
+     * sum of durations rather than a wall-clock span, and the two are not the same number.
+     *
+     * @returns {number} nanoseconds
+     */
+    get gpu_duration_ns(): number;
+}
+//# sourceMappingURL=GPUProfileFrame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileFrame.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileFrame.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;;;;OAKG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;;;OAQG;IACH,cAFU,MAAM,CAEE;IAElB;;;;;;;;OAQG;IACH,aAFU,MAAM,CAEC;IAEjB;;;;;;;;OAQG;IACH,UAFU,qBAAmB,IAAI,CAEjB;IAEhB;;OAEG;IACH,OAFU,gBAAgB,CAEf;IAEX;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;;;OAKG;IACH,8BAQC;CACJ"}