@woosh/meep-engine 3.11.3 → 3.13.0

package/src/shade/device/timing/GPUTimerArray.js

@@ -1,290 +1,262 @@
-import { assert } from "../../../core/assert.js";
-import IdPool from "../../../core/IdPool.js";
-
-export class GPUTimerArray {
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-    #size = 0;
-
-    /**
-     * @type {GPUQuerySet}
-     */
-    #query_set;
-
-    /**
-     * @type {GPUBuffer}
-     */
-    #resolve_buffer;
-    /**
-     * @type {GPUBuffer}
-     */
-    #results_buffer;
-
-    /**
-     * @type {BigInt64Array}
-     */
-    #results
-
-    #slots = new IdPool();
-
-    /**
-     *
-     * @type {{type: string, label: string}[]}
-     */
-    #slot_metadata = [];
-
-    /**
-     * Passes that asked for a slot after the array ran out.
-     *
-     * Reported rather than swallowed. A profile capture instruments far more passes than a one-off
-     * debug frame does, and a silent shortfall reads downstream as "those passes were free".
-     *
-     * @type {number}
-     */
-    #dropped_count = 0;
-
-    /**
-     * How many passes went untimed because {@link size} was too small for the frame.
-     *
-     * @returns {number}
-     */
-    get dropped_count() {
-        return this.#dropped_count;
-    }
-
-    /**
-     * Claim a slot, or report that there is none.
-     *
-     * The bound check is the point. `IdPool` hands out ids indefinitely, and an id at or past
-     * {@link size} addresses a query index the query set does not have — which WebGPU rejects at
-     * the `beginRenderPass` that used it, blaming a pass that did nothing wrong and saying nothing
-     * about the one that exhausted the array.
-     *
-     * @param {string} label
-     * @param {string} type
-     * @return {number} slot id, or -1 when the array is full
-     */
-    #bind_slot(label, type) {
-
-        if (this.#slots.peek() >= this.#size) {
-            this.#dropped_count++;
-
-            return -1;
-        }
-
-        const id = this.#slots.get();
-
-        this.#slot_metadata[id] = {
-            label,
-            type
-        };
-
-        return id;
-    }
-
-    /**
-     * @param {string} label
-     * @param {string} type one of 'compute', 'render'
-     * @returns {GPUComputePassTimestampWrites|GPURenderPassTimestampWrites|undefined} undefined when
-     * there is no slot left, in which case the caller must leave `timestampWrites` off its
-     * descriptor — an untimed pass is the correct degradation, an invalid one is not
-     */
-    #get_writes(label, type) {
-
-        const querySet = this.#query_set;
-
-        if (querySet === undefined) {
-            // same guard as `resolve` and `download_results`: with the feature withheld the timers
-            // go quiet rather than taking the frame down
-            return undefined;
-        }
-
-        const id = this.#bind_slot(label, type);
-
-        if (id === -1) {
-            return undefined;
-        }
-
-        const index0 = id * 2;
-
-        return {
-            querySet,
-            beginningOfPassWriteIndex: index0,
-            endOfPassWriteIndex: index0 + 1,
-        };
-    }
-
-    /**
-     *
-     * @param {string} label
-     * @returns {GPUComputePassTimestampWrites|undefined} undefined when the array is full
-     */
-    getComputeWrites(label) {
-        return this.#get_writes(label, 'compute');
-    }
-
-    /**
-     *
-     * @param {string} label
-     * @returns {GPURenderPassTimestampWrites|undefined} undefined when the array is full
-     */
-    getRenderWrites(label) {
-        return this.#get_writes(label, 'render');
-    }
-
-    /**
-     * Visit every slot that was claimed this frame, in slot order, with its raw timestamps.
-     *
-     * Raw: nanoseconds as the device reported them, `BigInt`, unscaled. {@link
-     * results_to_console_table} is the same data rounded for a human to read at a glance; a
-     * recording needs the values themselves, and the difference matters once quantization is in
-     * play — see the profiler's treatment of `timestamp_period_ns`.
-     *
-     * @param {(slot_id: number, label: string, type: string, t_begin: bigint, t_end: bigint) => void} visitor
-     * @returns {void}
-     */
-    traverse_results(visitor) {
-        assert.isFunction(visitor, 'visitor');
-
-        const results = this.#results;
-
-        if (results === undefined) {
-            return;
-        }
-
-        this.#slots.traverseUsed(slot_id => {
-            const meta = this.#slot_metadata[slot_id];
-
-            visitor(
-                slot_id,
-                meta.label,
-                meta.type,
-                results[slot_id * 2],
-                results[slot_id * 2 + 1]
-            );
-        });
-    }
-
-    /**
-     *
-     * @param {GPUDevice} device
-     * @param {number} [size] number of query slots
-     */
-    constructor(
-        device,
-        size = 1024
-    ) {
-        assert.defined(device, 'device');
-        assert.isNonNegativeInteger(size, 'size');
-
-        this.#device = device;
-
-        this.#size = size;
-
-        // see GPUTimer: a withheld profiling feature makes the timers quiet, not fatal
-        if (!device.features.has('timestamp-query')) {
-            return;
-        }
-
-        this.#query_set = device.createQuerySet({
-            type: 'timestamp',
-            count: size * 2
-        });
-
-        this.#resolve_buffer = device.createBuffer({
-            label: 'GPUTimerArray',
-            size: this.#size * 2 * 8, // start + end, 64bit uint
-            usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC
-        });
-
-        this.#results_buffer = this.#device.createBuffer({
-            label: 'GPUTimerArray/results',
-            size: this.#size * 2 * 8,
-            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
-        });
-
-        this.#results = new BigInt64Array(size * 2);
-    }
-
-    destroy() {
-        if (this.#query_set === undefined) {
-            return;
-        }
-
-        this.#query_set.destroy();
-        this.#resolve_buffer.destroy();
-        this.#results_buffer.destroy();
-    }
-
-    /**
-     *
-     * @param {GPUCommandEncoder} encoder
-     */
-    resolve(encoder) {
-
-        if (this.#query_set === undefined) {
-            return;
-        }
-
-        encoder.resolveQuerySet(this.#query_set, 0, this.#query_set.count, this.#resolve_buffer, 0);
-        encoder.copyBufferToBuffer(this.#resolve_buffer, 0, this.#results_buffer, 0);
-    }
-
-    async download_results() {
-
-        const results_buffer = this.#results_buffer;
-
-        if (results_buffer === undefined) {
-            // Same guard as `resolve` and `destroy`: with the profiling feature withheld there is no
-            // query set and no buffers, and the timers are supposed to go quiet rather than take the
-            // frame down with them. Without it, `enable_debug_timers` on such a device raises an
-            // unhandled rejection out of `ShadeGPUCommandContext.finish`, which calls this
-            // unconditionally — `results_to_console_table` then reports an empty table, which is
-            // what "quiet" means.
-            return;
-        }
-
-        await results_buffer.mapAsync(GPUMapMode.READ)
-
-        const mapped = results_buffer.getMappedRange(
-            0, results_buffer.size,
-        );
-
-        this.#results.set(new BigInt64Array(mapped));
-
-        results_buffer.unmap();
-
-    }
-
-    /**
-     * prepare tabular formatting for console output
-     * @returns {Object}
-     */
-    results_to_console_table() {
-        const result = [];
-
-        this.#slots.traverseUsed(slot_id => {
-            const meta = this.#slot_metadata[slot_id];
-            const t_start = this.#results[slot_id * 2];
-            const t_end = this.#results[slot_id * 2 + 1];
-
-            const duration_ns = Number(t_end - t_start);
-            const duration_ms = duration_ns * 1e-6;
-
-            result.push({
-                label: meta.label,
-                type: meta.type,
-                duration_ms: duration_ms,
-                start: t_start,
-                end: t_end,
-            });
-        });
-
-        return result;
-    }
-
+import { assert } from "../../../core/assert.js";
+import IdPool from "../../../core/IdPool.js";
+
+export class GPUTimerArray {
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    #size = 0;
+
+    /**
+     * @type {GPUQuerySet}
+     */
+    #query_set;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #resolve_buffer;
+    /**
+     * @type {GPUBuffer}
+     */
+    #results_buffer;
+
+    /**
+     * @type {BigInt64Array}
+     */
+    #results
+
+    #slots = new IdPool();
+
+    /**
+     *
+     * @type {{type: string, label: string}[]}
+     */
+    #slot_metadata = [];
+
+    /**
+     * Passes that asked for a slot after the array ran out.
+     *
+     * Reported rather than swallowed. A profile capture instruments far more passes than a one-off
+     * debug frame does, and a silent shortfall reads downstream as "those passes were free".
+     *
+     * @type {number}
+     */
+    #dropped_count = 0;
+
+    /**
+     * How many passes went untimed because {@link size} was too small for the frame.
+     *
+     * @returns {number}
+     */
+    get dropped_count() {
+        return this.#dropped_count;
+    }
+
+    /**
+     * Claim a slot, or report that there is none.
+     *
+     * The bound check is the point. `IdPool` hands out ids indefinitely, and an id at or past
+     * {@link size} addresses a query index the query set does not have — which WebGPU rejects at
+     * the `beginRenderPass` that used it, blaming a pass that did nothing wrong and saying nothing
+     * about the one that exhausted the array.
+     *
+     * @param {string} label
+     * @param {string} type
+     * @return {number} slot id, or -1 when the array is full
+     */
+    #bind_slot(label, type) {
+
+        if (this.#slots.peek() >= this.#size) {
+            this.#dropped_count++;
+
+            return -1;
+        }
+
+        const id = this.#slots.get();
+
+        this.#slot_metadata[id] = {
+            label,
+            type
+        };
+
+        return id;
+    }
+
+    /**
+     * @param {string} label
+     * @param {string} type one of 'compute', 'render'
+     * @returns {GPUComputePassTimestampWrites|GPURenderPassTimestampWrites|undefined} undefined when
+     * there is no slot left, in which case the caller must leave `timestampWrites` off its
+     * descriptor — an untimed pass is the correct degradation, an invalid one is not
+     */
+    #get_writes(label, type) {
+
+        const querySet = this.#query_set;
+
+        if (querySet === undefined) {
+            // same guard as `resolve` and `download_results`: with the feature withheld the timers
+            // go quiet rather than taking the frame down
+            return undefined;
+        }
+
+        const id = this.#bind_slot(label, type);
+
+        if (id === -1) {
+            return undefined;
+        }
+
+        const index0 = id * 2;
+
+        return {
+            querySet,
+            beginningOfPassWriteIndex: index0,
+            endOfPassWriteIndex: index0 + 1,
+        };
+    }
+
+    /**
+     *
+     * @param {string} label
+     * @returns {GPUComputePassTimestampWrites|undefined} undefined when the array is full
+     */
+    getComputeWrites(label) {
+        return this.#get_writes(label, 'compute');
+    }
+
+    /**
+     *
+     * @param {string} label
+     * @returns {GPURenderPassTimestampWrites|undefined} undefined when the array is full
+     */
+    getRenderWrites(label) {
+        return this.#get_writes(label, 'render');
+    }
+
+    /**
+     * Visit every slot that was claimed this frame, in slot order, with its raw timestamps.
+     *
+     * Raw: nanoseconds as the device reported them, `BigInt`, unscaled. Rounding belongs to
+     * whoever is displaying them; a recording needs the values themselves, and the difference
+     * matters once quantization is in play — see the profiler's treatment of
+     * `timestamp_period_ns`.
+     *
+     * @param {(slot_id: number, label: string, type: string, t_begin: bigint, t_end: bigint) => void} visitor
+     * @returns {void}
+     */
+    traverse_results(visitor) {
+        assert.isFunction(visitor, 'visitor');
+
+        const results = this.#results;
+
+        if (results === undefined) {
+            return;
+        }
+
+        this.#slots.traverseUsed(slot_id => {
+            const meta = this.#slot_metadata[slot_id];
+
+            visitor(
+                slot_id,
+                meta.label,
+                meta.type,
+                results[slot_id * 2],
+                results[slot_id * 2 + 1]
+            );
+        });
+    }
+
+    /**
+     *
+     * @param {GPUDevice} device
+     * @param {number} [size] number of query slots
+     */
+    constructor(
+        device,
+        size = 1024
+    ) {
+        assert.defined(device, 'device');
+        assert.isNonNegativeInteger(size, 'size');
+
+        this.#device = device;
+
+        this.#size = size;
+
+        // see GPUTimer: a withheld profiling feature makes the timers quiet, not fatal
+        if (!device.features.has('timestamp-query')) {
+            return;
+        }
+
+        this.#query_set = device.createQuerySet({
+            type: 'timestamp',
+            count: size * 2
+        });
+
+        this.#resolve_buffer = device.createBuffer({
+            label: 'GPUTimerArray',
+            size: this.#size * 2 * 8, // start + end, 64bit uint
+            usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC
+        });
+
+        this.#results_buffer = this.#device.createBuffer({
+            label: 'GPUTimerArray/results',
+            size: this.#size * 2 * 8,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+        });
+
+        this.#results = new BigInt64Array(size * 2);
+    }
+
+    destroy() {
+        if (this.#query_set === undefined) {
+            return;
+        }
+
+        this.#query_set.destroy();
+        this.#resolve_buffer.destroy();
+        this.#results_buffer.destroy();
+    }
+
+    /**
+     *
+     * @param {GPUCommandEncoder} encoder
+     */
+    resolve(encoder) {
+
+        if (this.#query_set === undefined) {
+            return;
+        }
+
+        encoder.resolveQuerySet(this.#query_set, 0, this.#query_set.count, this.#resolve_buffer, 0);
+        encoder.copyBufferToBuffer(this.#resolve_buffer, 0, this.#results_buffer, 0);
+    }
+
+    async download_results() {
+
+        const results_buffer = this.#results_buffer;
+
+        if (results_buffer === undefined) {
+            // Same guard as `resolve` and `destroy`: with the profiling feature withheld there is no
+            // query set and no buffers, and the timers are supposed to go quiet rather than take the
+            // frame down with them. Without it, profiling on such a device raises an unhandled
+            // rejection out of `ShadeGPUContextProfiler.absorb`, which calls this unconditionally.
+            // `traverse_results` then visits nothing, which is what "quiet" means.
+            return;
+        }
+
+        await results_buffer.mapAsync(GPUMapMode.READ)
+
+        const mapped = results_buffer.getMappedRange(
+            0, results_buffer.size,
+        );
+
+        this.#results.set(new BigInt64Array(mapped));
+
+        results_buffer.unmap();
+
+    }
+
 }

package/src/shade/device/timing/GPU_PROFILER_PROPOSAL_2026_08_28.md

@@ -2,6 +2,12 @@
 
 Proposal, 2026-08-28. Decisions folded in 2026-08-29. Alex Goldring / Company Named Limited.
 
+> **Partly superseded, 2026-08-31**, by
+> [PASS_ENCODER_PROPOSAL_2026_08_31.md](../PASS_ENCODER_PROPOSAL_2026_08_31.md). The recording
+> proxy of §6.2 hook 3 and M4 is now a pair of decorator classes; `enable_debug_timers`,
+> `Renderer.add_debug_frame` and `Renderer.onFrameDebug` — which §6.1 kept — are gone, leaving the
+> profiler as the only path. §§1–5 remain a record of the state this design was written against.
+
 Scope: a **recording** side that ships with the engine, a **binary container** that carries a
 capture, and an **inspector** web application under `packages/gpu-inspector-tool/` that reads the
 container and nothing else.
@@ -628,8 +634,13 @@ Three things fall out of the caller owning it, and all three are why this is the
 `frame_limit` reaching zero stops the session exactly as `stop()` does. Both resolve the same
 promise, so a caller that wants "500 frames or until I say" writes one `await`.
 
-`add_debug_frame` and `onFrameDebug` stay exactly as they are — cheap, synchronous, console-shaped,
-and a different tool for a different question.
+~~`add_debug_frame` and `onFrameDebug` stay exactly as they are — cheap, synchronous, console-shaped,
+and a different tool for a different question.~~
+
+> **Reversed 2026-08-31.** They were not a different tool, they were a worse view of the same one
+> reached through a second API — no graph-pass attribution, no workload, no pipeline identity — and
+> `onFrameDebug` never acquired a subscriber. Removed; the profiler is the only path. "Profile the
+> next N frames" is `new GPUProfileSession({ frame_limit: N })`.
 
 ### 6.2 The five hooks
 
@@ -809,6 +820,13 @@ renderer only while profiling. Dispatch and draw counts, pipeline identity, and
 parsed from WGSL where it is a literal — an override expression records as *unknown*, which is not
 the same as zero.
 
+> **Reversed 2026-08-31.** The argument holds only while the wrapper is *conditional*; that is what
+> makes a missing method silent. `ShadeGPUComputePassEncoder` / `ShadeGPURenderPassEncoder` wrap
+> every pass, so a gap throws on the first frame of every build. The workgroup size now comes off
+> `ComputePipelineDescriptor`, which reads it as its code is set, with the parser that resolves
+> `const` references — a size it cannot read refuses to build the descriptor rather than recording
+> as unknown.
+
 No `PIPE` table in the end: a pass's pipeline label and workgroup size ride in its own workload
 block, which costs a symbol reference and avoids a second id space.
 

package/src/shade/device/timing/ShadeGPUContextProfiler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Everything one {@link ShadeGPUCommandContext} needs in order to be profiled: its timer array, the
+ * recorder its timings go to, and which query set it is within the frame.
+ *
+ * **It opens the passes itself.** Two values are needed at two different instants — the
+ * `timestampWrites` before the encoder exists, the {@link GPUProfileWork} after — and any shape that
+ * hands both back to the caller has to carry them across that gap. The predecessor carried them in a
+ * private field on the command context, consumed by whatever ran next, which is the kind of coupling
+ * that breaks the moment a line is inserted between the two halves. Handing the profiler the encoder
+ * collapses the gap: both values are produced and consumed inside one method and there is nothing to
+ * carry.
+ *
+ * Off by default and constructed only by `enable_profiling`, so a context that is not being profiled
+ * holds one null field and allocates no query set.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ShadeGPUContextProfiler {
+    /**
+     * @param {GPUDevice} device
+     * @param {GPUFrameRecorder} recorder
+     * @param {number} query_set_id this context's index within the frame
+     */
+    constructor(device: GPUDevice, recorder: GPUFrameRecorder, query_set_id: number);
+    /**
+     * Resolves after this context's timings have been read back and handed to the recorder.
+     *
+     * @returns {Promise<void>}
+     */
+    get absorbed(): Promise<void>;
+    /**
+     * @param {GPUCommandEncoder} encoder
+     * @param {GPUComputePassDescriptor} [descriptor]
+     * @returns {ShadeGPUComputePassEncoder}
+     */
+    begin_compute_pass(encoder: GPUCommandEncoder, descriptor?: GPUComputePassDescriptor): ShadeGPUComputePassEncoder;
+    /**
+     * @param {GPUCommandEncoder} encoder
+     * @param {GPURenderPassDescriptor} descriptor
+     * @returns {ShadeGPURenderPassEncoder}
+     */
+    begin_render_pass(encoder: GPUCommandEncoder, descriptor: GPURenderPassDescriptor): ShadeGPURenderPassEncoder;
+    /**
+     * @param {GPUCommandEncoder} encoder
+     * @returns {void}
+     */
+    resolve(encoder: GPUCommandEncoder): void;
+    /**
+     * Read the timings back and hand them to the recorder. Resolves {@link absorbed} either way.
+     *
+     * @returns {void}
+     */
+    absorb(): void;
+    #private;
+}
+import { ShadeGPUComputePassEncoder } from "../pass/ShadeGPUComputePassEncoder.js";
+import { ShadeGPURenderPassEncoder } from "../pass/ShadeGPURenderPassEncoder.js";
+//# sourceMappingURL=ShadeGPUContextProfiler.d.ts.map

package/src/shade/device/timing/ShadeGPUContextProfiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadeGPUContextProfiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/ShadeGPUContextProfiler.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH;IA+BI;;;;OAIG;IACH,yEAFW,MAAM,EAchB;IAED;;;;OAIG;IACH,8BAEC;IAED;;;;OAIG;IACH,uFAFa,0BAA0B,CAYtC;IAED;;;;OAIG;IACH,oFAFa,yBAAyB,CAYrC;IAmCD;;;OAGG;IACH,qCAFa,IAAI,CAIhB;IAED;;;;OAIG;IACH,UAFa,IAAI,CAoBhB;;CACJ;2CApL0C,uCAAuC;0CACxC,sCAAsC"}