npm - @woosh/meep-engine - Versions diffs - 3.9.0 → 3.11.0 - Mend

@woosh/meep-engine 3.9.0 → 3.11.0

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 (832) hide show

package/src/shade/device/ShadeGPUCommandContext.js CHANGED Viewed

@@ -1,750 +1,941 @@
-import { assert } from "../../core/assert.js";
-import { array_push_if_unique } from "../../core/collection/array/array_push_if_unique.js";
-import { array_remove_first } from "../../core/collection/array/array_remove_first.js";
-import { array_buffer_copy } from "../../core/collection/array/typed/array_buffer_copy.js";
-import Signal from "../../core/events/signal/Signal.js";
-import { noop } from "../../core/function/noop.js";
-import { GPUTimerArray } from "./timing/GPUTimerArray.js";
-import { warn_limited } from "../util/warn_limited.js";
-import { write_gpu_typed_buffer } from "../renderer/shader/type/serde/write_gpu_typed_buffer.js";
-import { BufferResourceDescriptor } from "./graph/BufferResourceDescriptor.js";
-import { GraphicsExecutionContext } from "./graph/GraphicsExecutionContext.js";
-/**
- * Keep track of how many contexts are currently open (unfinished)
- * Important because contexts can have transient resources allocated, and those are not cleaned up until the context is `finished`
- * @type {number}
- */
-let debug_open_context_count = 0;
-/**
- *
- * @type {ShadeGPUCommandContext[]}
- */
-const debug_open_contexts = [];
-const scratch_buffer_descriptor = new BufferResourceDescriptor();
-let id_counter = 0;
-/**
- * Abstraction on top of {@link GPUCommandEncoder}.
- *
- * Inspired by Intel's "MiniEngine" CommandContext
- * @see https://github.com/GameTechDev/TAA/blob/39786709cf70a1e0906196c600f6079571a33ceb/MiniEngine/Core/CommandContext.h
- * @see https://www.w3.org/TR/webgpu/#gpucommandencoder
- */
-export class ShadeGPUCommandContext {
-    #id = id_counter++;
-    /**
-     * Unique identifier for this context, useful for debugging
-     *
-     * @return {number}
-     */
-    get id() {
-        return this.#id;
-    }
-    /**
-     *
-     * @returns {boolean}
-     */
-    get isGPUCommandContext() {
-        return true;
-    }
-    /**
-     * Actual underlying encoder
-     * @type {GPUCommandEncoder}
-     */
-    #gpu_encoder
-    /**
-     * Don't circumvent {@link ShadeGPUCommandContext} unless you know what you're doing.
-     * {@link ShadeGPUCommandContext} is a wrapper around {@link GPUCommandEncoder} that provides additional spec-compliance asserts to help find errors sooner.
-     * @returns {GPUCommandEncoder}
-     */
-    get gpu_encoder() {
-        return this.#gpu_encoder;
-    }
-    /**
-     * @type {GPUTimerArray|undefined}
-     */
-    #debug_timers;
-    /**
-     *
-     * @type {function}
-     */
-    #debug_timers_callback = noop;
-    /**
-     *
-     * @param {function} debug_timers_callback
-     */
-    enable_debug_timers(debug_timers_callback) {
-        if (this.#debug_timers !== undefined) {
-            // already enabled
-            return;
-        }
-        this.#debug_timers = new GPUTimerArray(this.device);
-        this.#debug_timers_callback = debug_timers_callback;
-    }
-    /**
-     * @type {GraphicsContext}
-     */
-    #graphics
-    /**
-     *
-     * @return {GPUDevice}
-     */
-    get device() {
-        return this.#graphics.device;
-    }
-    /**
-     *
-     * @return {TextureManager}
-     */
-    get textures() {
-        return this.#graphics.textures;
-    }
-    /**
-     * These are to be destroyed at the end of the context's lifetime.
-     * Need to be released at the end of the lifetime.
-     * @type {GPUBuffer[]}
-     */
-    #transient_buffers = [];
-    /**
-     *
-     * @type {GPUBuffer[]}
-     */
-    #staging_buffers = [];
-    /**
-     * Once finished, the encoder becomes inactive, we use this flag to track potential misuse and inform the user
-     * @type {boolean}
-     */
-    #finished = false;
-    /**
-     * @readonly
-     * @type {Signal<this>}
-     */
-    onFinished = new Signal();
-    /**
-     * @readonly
-     * @type {Signal<this>}
-     */
-    onBeforeFinish = new Signal();
-    /**
-     *
-     * @return {Promise<void>}
-     */
-    get done() {
-        if (this.#finished) {
-            return Promise.resolve();
-        }
-        return new Promise(resolve => {
-            this.onFinished.addOne(resolve);
-            if (this.#finished) {
-                // special case, double-checking to avoid race conditions
-                resolve();
-            }
-        });
-    }
-    /**
-     * Do not call directly, always use {@link create}
-     * @private
-     */
-    constructor() {
-        // private, do not call from the outside
-    }
-    /**
-     *
-     * @param {GraphicsContext} graphics
-     * @param {string} [label]
-     * @returns {ShadeGPUCommandContext}
-     */
-    static create(
-        graphics,
-        label = ""
-    ) {
-        assert.defined(graphics, 'graphics');
-        assert.equal(graphics.isGraphicsContext, true, "graphics.isGraphicsContext !== true");
-        assert.isString(label, 'label');
-        const r = new ShadeGPUCommandContext();
-        r.#graphics = graphics;
-        r.#gpu_encoder = graphics.device.createCommandEncoder({
-            label
-        });
-        // track how many we have open
-        debug_open_context_count++;
-        array_push_if_unique(debug_open_contexts, r);
-        if (debug_open_context_count > 1024) {
-            warn_limited(`Too many open GPU contexts`, 20);
-        }
-        return r;
-    }
-    /**
-     *
-     * @returns {GraphicsExecutionContext}
-     */
-    createFrameGraphContext() {
-        return new GraphicsExecutionContext(this.#graphics, this);
-    }
-    /**
-     *
-     * @param {FrameGraph} graph
-     */
-    encodeGraph(graph) {
-        assert.defined(graph, 'graph');
-        assert.isObject(graph, 'graph');
-        assert.equal(graph.isFrameGraph, true, "graph.isFrameGraph !== true");
-        // TODO check if the graph is empty, if so, we can skip the whole thing
-        const ctx = this.createFrameGraphContext();
-        graph.compile();
-        graph.execute(ctx);
-    }
-    /**
-     * @see https://www.w3.org/TR/webgpu/#dom-gpucommandencoder-clearbuffer
-     * @param {GPUBuffer} buffer
-     * @param {number} [offset=0]
-     * @param {number} [size]
-     */
-    clearBuffer(buffer, offset = 0, size) {
-        assert.defined(buffer, 'buffer');
-        assert.equal(buffer.usage & GPUBufferUsage.COPY_DST, GPUBufferUsage.COPY_DST, 'buffer must include COPY_DST usage flag');
-        assert.isNonNegativeInteger(offset, 'offset');
-        assert.equal(offset % 4, 0, 'offset must be a multiple of 4');
-        // console.log(`cmd.clearBuffer(${buffer.label}, ${offset}, ${size})`);
-        this.#gpu_encoder.clearBuffer(buffer, offset, size);
-    }
-    /**
-     * Not supported, only here to offer documentation hint
-     * see {@link texture_fill_rectangle}
-     * @throws {Error} Always, documentation hint only
-     */
-    clearTexture() {
-        throw new Error(`Documentation hint only, use texture_fill_rectangle instead`);
-    }
-    /**
-     * NOTE: only the explicit verbose form of the API is supported, shorthand such as `copyBufferToBuffer(source, destination, size)` are not supported.
-     * see https://www.w3.org/TR/webgpu/#gpucommandencoder-copybuffertobuffer
-     * @see GPUCommandEncoder.copyBufferToBuffer
-     * @param {GPUBuffer} source The GPUBuffer to copy from.
-     * @param {number} sourceOffset Offset in bytes into the source to begin copying from.
-     * @param {GPUBuffer} destination The GPUBuffer to copy to.
-     * @param {number} destinationOffset Offset in bytes into destination to place the copied data.
-     * @param {number} [size] Bytes to copy. In not specified, defaults to `source.size - sourceOffset`
-     */
-    copyBufferToBuffer(
-        source,
-        sourceOffset,
-        destination,
-        destinationOffset,
-        size
-    ) {
-        assert.notEqual(source.usage & GPUBufferUsage.COPY_SRC, 0, 'source must include COPY_SRC usage flag');
-        assert.isNonNegativeInteger(sourceOffset, 'sourceOffset');
-        assert.equal(sourceOffset % 4, 0, 'sourceOffset must be a multiple of 4');
-        assert.notEqual(destination.usage & GPUBufferUsage.COPY_DST, 0, 'destination must include COPY_DST usage flag');
-        assert.isNonNegativeInteger(destinationOffset, 'destinationOffset');
-        assert.equal(destinationOffset % 4, 0, 'destinationOffset must be a multiple of 4');
-        if (size !== undefined) {
-            assert.isNonNegativeInteger(size, 'size');
-            assert.equal(size % 4, 0, 'size must be a multiple of 4');
-            assert.greaterThanOrEqual(source.size, sourceOffset + size, 'source underflow');
-            assert.greaterThanOrEqual(destination.size, destinationOffset + size, 'destination underflow');
-        }
-        assert.notEqual(source, destination, 'source and destination must be different');
-        // console.log(`cmd.copyBufferToBuffer("${source.label}", ${sourceOffset}, "${destination.label}", ${destinationOffset}, ${size})`);
-        this.#gpu_encoder.copyBufferToBuffer(
-            source,
-            sourceOffset,
-            destination,
-            destinationOffset,
-            size
-        );
-    }
-    /**
-     *
-     * @param {GPUImageCopyTexture} source
-     * @param {GPUImageCopyTexture} destination
-     * @param {GPUExtent3DStrict} copySize
-     */
-    copyTextureToTexture(source,
-                         destination,
-                         copySize
-    ) {
-        this.#gpu_encoder.copyTextureToTexture(source, destination, copySize);
-    }
-    /**
-     *
-     * @param {GPUComputePassDescriptor} [descriptor]
-     * @returns {GPUComputePassEncoder}
-     */
-    beginComputePass(descriptor) {
-        const encoder = this.#gpu_encoder;
-        let _descriptor = descriptor;
-        const timers = this.#debug_timers;
-        const graphics = this.#graphics;
-        if (
-            timers !== undefined
-            && graphics.device.features.has('timestamp-query')
-        ) {
-            _descriptor.timestampWrites = timers.getComputeWrites(descriptor.label);
-        }
-        // console.log(`cmd.beginComputePass(${descriptor.label})`);
-        return encoder.beginComputePass(_descriptor)
-    }
-    /**
-     *
-     * @param {ComputePipelineDescriptor} pipeline
-     * @param {string} [label]
-     * @param {GPUBindingResource[][]} [bindings]
-     * @returns {GPUComputePassEncoder}
-     */
-    constructComputePass({
-                             pipeline,
-                             label,
-                             bindings = []
-                         }) {
-        const pass_descriptor = {
-            label
-        };
-        if (label === undefined) {
-            pass_descriptor.label = pipeline.label;
-        }
-        const graphics = this.#graphics;
-        const pass = this.beginComputePass(pass_descriptor);
-        const gpu_pipeline = graphics.compute_pipelines.obtain(pipeline);
-        pass.setPipeline(gpu_pipeline);
-        graphics.setPipelineBindings(pass, pipeline, bindings);
-        // console.warn(`cmd.constructComputePass(${pass_descriptor.label})`)
-        return pass;
-    }
-    /**
-     * Begins a labeled debug group containing subsequent commands.
-     * @see https://gpuweb.github.io/gpuweb/#debug-markers
-     * @param {string} label
-     */
-    pushDebugGroup(label) {
-        assert.isString(label, 'label');
-        this.#gpu_encoder.pushDebugGroup(label);
-        // console.group("cmd/debug_group=" + label)
-    }
-    /**
-     * Ends the labeled debug group most recently started by pushDebugGroup().
-     * @see https://gpuweb.github.io/gpuweb/#debug-markers
-     */
-    popDebugGroup() {
-        this.#gpu_encoder.popDebugGroup();
-        // console.groupEnd();
-    }
-    /**
-     * Marks a point in a stream of commands with a label.
-     * @see https://gpuweb.github.io/gpuweb/#debug-markers
-     * @param {string} label
-     */
-    insertDebugMarker(label) {
-        assert.isString(label, 'label');
-        this.#gpu_encoder.insertDebugMarker(label);
-    }
-    /**
-     *
-     * @param {string} [label]
-     * @param {RenderPipelineDescriptor} pipeline
-     * @param {GPUBindingResource[][]} [bindings]
-     * @param {GPURenderPassColorAttachment[]} colorAttachments
-     * @param {GPURenderPassDepthStencilAttachment} [depthStencilAttachment]
-     * @returns {GPURenderPassEncoder}
-     */
-    constructRenderPass({
-                            label,
-                            pipeline,
-                            bindings,
-                            colorAttachments,
-                            depthStencilAttachment,
-                        }) {
-        assert.defined(pipeline, 'pipeline');
-        assert.equal(pipeline.isRenderPipelineDescriptor, true, "pipeline.isRenderPipelineDescriptor !== true");
-        const pass_descriptor = {
-            label,
-            colorAttachments,
-            depthStencilAttachment
-        };
-        if (label === undefined) {
-            pass_descriptor.label = pipeline.label;
-        }
-        const graphics = this.#graphics;
-        // TODO rewrite the pipeline if necessary to achieve compatibility with colorAttachment formats
-        const gpu_pipeline = graphics.render_pipelines.obtain(pipeline);
-        const pass = this.beginRenderPass(pass_descriptor);
-        pass.setPipeline(gpu_pipeline);
-        graphics.setPipelineBindings(pass, pipeline, bindings);
-        // console.warn(`cmd.constructRenderPass(${pass_descriptor.label})`)
-        return pass;
-    }
-    /**
-     *
-     * @param {GPURenderPassDescriptor} descriptor
-     * @returns {GPURenderPassEncoder}
-     */
-    beginRenderPass(descriptor) {
-        let _descriptor = descriptor;
-        const timers = this.#debug_timers;
-        const graphics = this.#graphics;
-        if (
-            timers !== undefined
-            && graphics.device.features.has('timestamp-query')
-        ) {
-            _descriptor.timestampWrites = timers.getRenderWrites(descriptor.label);
-        }
-        // console.log(`cmd.beginRenderPass(${descriptor.label})`);
-        return this.#gpu_encoder.beginRenderPass(_descriptor)
-    }
-    /**
-     *
-     * @param {GPUQuerySet} querySet
-     * @param {number} firstQuery
-     * @param {number} queryCount
-     * @param {GPUBuffer} destination
-     * @param {number} destinationOffset
-     */
-    resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset) {
-        this.#gpu_encoder.resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset);
-    }
-    /**
-     * Transient buffers are automatically released at the end of the context's lifetime;
-     * however, we can explicitly release it earlier to allow for reuse.
-     *
-     * @param {GPUBuffer} buffer
-     * @return {boolean} true if buffer was released, false if it was not found
-     */
-    releaseTransientBuffer(buffer) {
-        assert.defined(buffer, 'buffer');
-        if (!array_remove_first(this.#transient_buffers, buffer)) {
-            return false;
-        }
-        const allocator = this.#transient_allocator;
-        return allocator.release(buffer);
-    }
-    /**
-     *
-     * @return {GPUBufferAllocator}
-     */
-    get #transient_allocator() {
-        return this.#graphics.buffer_allocator_main;
-    }
-    /**
-     * Allocated buffer will only be valid until the context is finished.
-     *
-     * @param {number|GPUBufferUsage} usage
-     * @param {number} size
-     * @returns {GPUBuffer} managed buffer
-     */
-    allocateTransientBuffer(
-        usage = GPUBufferUsage.UNIFORM,
-        size
-    ) {
-        assert.isNonNegativeInteger(size, 'size');
-        assert.isInteger(usage, 'usage');
-        assert.notOk(this.#finished, 'already finished');
-        scratch_buffer_descriptor.size = size;
-        // COPY_DST is needed to write the data
-        scratch_buffer_descriptor.usage = usage | GPUBufferUsage.COPY_DST;
-        const allocator = this.#transient_allocator;
-        const buffer = allocator.get(scratch_buffer_descriptor, this);
-        // remember so we can clean up at the end
-        this.#transient_buffers.push(buffer);
-        return buffer;
-    }
-    /**
-     *
-     * @param {ArrayBuffer} data CPU-side data to place into the GPU buffer
-     * @param {number|GPUBufferUsage} [usage=GPUBufferUsage.UNIFORM]
-     * @param {number} [offset] offset into source data where to start copying from
-     * @param {number} [size] in bytes
-     * @returns {GPUBuffer} managed buffer, will be automatically destroyed when context is finished
-     */
-    allocateTransientBufferAndLoad(
-        data,
-        usage = GPUBufferUsage.UNIFORM,
-        offset = 0,
-        size = data.byteLength
-    ) {
-        assert.isInstanceOf(data, ArrayBuffer, 'data');
-        assert.isInteger(usage, 'usage');
-        assert.isNonNegativeInteger(offset, 'offset');
-        assert.isNonNegativeInteger(size, 'size');
-        assert.notOk(this.#finished, 'already finished');
-        const buffer = this.allocateTransientBuffer(
-            usage,
-            size
-        );
-        this.writeBuffer(buffer, 0, data, offset, size);
-        return buffer;
-    }
-    /**
-     * @template T
-     * @param {WebGPUType} type
-     * @param {T} value
-     * @param {number|GPUBufferUsage} [usage]
-     * @return {GPUBuffer}
-     */
-    allocateTransientValueBuffer(
-        type,
-        value,
-        usage
-    ) {
-        assert.defined(type, 'type');
-        assert.notNull(type, 'type');
-        const buffer = this.allocateTransientBuffer(usage, type.aligned_size);
-        this.writeValueBuffer(buffer, 0, type, value);
-        return buffer;
-    }
-    /**
-     * @template T
-     * @param {GPUBuffer} buffer
-     * @param {number} buffer_offset
-     * @param {WebGPUType} type
-     * @param {T} value
-     */
-    writeValueBuffer(buffer, buffer_offset, type, value) {
-        assert.notOk(this.#finished, 'already finished');
-        const gfx = this.#graphics;
-        const size = type.aligned_size;
-        const stage = gfx.buffer_allocator_staging.get(size);
-        const mapped = stage.getMappedRange(0, size);
-        write_gpu_typed_buffer(value, type, mapped, 0);
-        stage.unmap();
-        this.#staging_buffers.push(stage);
-        this.copyBufferToBuffer(stage, 0, buffer, buffer_offset, size);
-    }
-    /**
-     * Very similar to {@link GPUQueue.writeBuffer}, but instead of doing the operation direction on the queue - uses a staging buffer under the hood and performs the actual write operation as part of the commmand buffer
-     * @param {GPUBuffer} buffer
-     * @param {number} buffer_offset
-     * @param {ArrayBuffer} data
-     * @param {number} data_offset
-     * @param {number} size
-     */
-    writeBuffer(buffer, buffer_offset, data, data_offset, size) {
-        assert.defined(buffer, 'buffer');
-        assert.isNonNegativeInteger(buffer_offset, 'buffer_offset');
-        assert.defined(data, 'data');
-        assert.isNonNegativeInteger(data_offset, 'data_offset');
-        assert.isNonNegativeInteger(size, 'size');
-        const gfx = this.#graphics;
-        const stage = gfx.buffer_allocator_staging.get(size);
-        const mapped = stage.getMappedRange(0, size);
-        array_buffer_copy(data, data_offset, mapped, 0, size);
-        stage.unmap();
-        this.#staging_buffers.push(stage);
-        this.copyBufferToBuffer(stage, 0, buffer, buffer_offset, size);
-    }
-    #cleanup() {
-        // console.warn('cmd.cleanup()');
-        const transient_buffers = this.#transient_buffers;
-        const transient_buffer_count = transient_buffers.length;
-        const buffer_allocator_transient = this.#transient_allocator;
-        // release in reverse order to make it more likely that we'd end up in the same acquisition order next time, which is desirable for caching
-        for (let i = transient_buffer_count - 1; i >= 0; i--) {
-            const buffer = transient_buffers[i];
-            buffer_allocator_transient.release(buffer);
-        }
-        // staging buffers
-        const buffer_allocator_staging = this.#graphics.buffer_allocator_staging;
-        for (const staging of this.#staging_buffers) {
-            buffer_allocator_staging.release(staging);
-        }
-    }
-    /**
-     * Performs both {@link GPUCommandEncoder.finish} and flushed command buffer
-     */
-    finish() {
-        if (this.#finished) {
-            console.warn('Context already finished');
-            return;
-        }
-        this.onBeforeFinish.send1(this);
-        debug_open_context_count--;
-        array_remove_first(debug_open_contexts, this);
-        const encoder = this.#gpu_encoder;
-        const debug_timers = this.#debug_timers;
-        if (debug_timers !== undefined) {
-            debug_timers.resolve(encoder);
-        }
-        this.#finished = true;
-        // release encoder reference
-        this.#gpu_encoder = undefined;
-        const command_buffer = encoder.finish();
-        const graphics = this.#graphics;
-        const queue = graphics.device.queue;
-        queue.submit([command_buffer]);
-        // cleanup allocated memory
-        this.#cleanup();
-        if (debug_timers !== undefined) {
-            debug_timers
-                .download_results()
-                .then(() => {
-                    const table = debug_timers.results_to_console_table();
-                    this.#debug_timers_callback(table);
-                })
-                .finally(() => {
-                    debug_timers.destroy();
-                });
-            this.#debug_timers = undefined;
-        }
-        this.onFinished.send1(this);
-    }
+import { assert } from "../../core/assert.js";
+import { array_push_if_unique } from "../../core/collection/array/array_push_if_unique.js";
+import { array_remove_first } from "../../core/collection/array/array_remove_first.js";
+import { array_buffer_copy } from "../../core/collection/array/typed/array_buffer_copy.js";
+import Signal from "../../core/events/signal/Signal.js";
+import { noop } from "../../core/function/noop.js";
+import { GPUTimerArray } from "./timing/GPUTimerArray.js";
+import { make_profiling_pass_encoder } from "./timing/profile/make_profiling_pass_encoder.js";
+import { parse_workgroup_size } from "./timing/profile/parse_workgroup_size.js";
+import { warn_limited } from "../util/warn_limited.js";
+import { write_gpu_typed_buffer } from "../renderer/shader/type/serde/write_gpu_typed_buffer.js";
+import { BufferResourceDescriptor } from "./graph/BufferResourceDescriptor.js";
+import { GraphicsExecutionContext } from "./graph/GraphicsExecutionContext.js";
+/**
+ * Keep track of how many contexts are currently open (unfinished)
+ * Important because contexts can have transient resources allocated, and those are not cleaned up until the context is `finished`
+ * @type {number}
+ */
+let debug_open_context_count = 0;
+/**
+ *
+ * @type {ShadeGPUCommandContext[]}
+ */
+const debug_open_contexts = [];
+const scratch_buffer_descriptor = new BufferResourceDescriptor();
+let id_counter = 0;
+/**
+ * Abstraction on top of {@link GPUCommandEncoder}.
+ *
+ * Inspired by Intel's "MiniEngine" CommandContext
+ * @see https://github.com/GameTechDev/TAA/blob/39786709cf70a1e0906196c600f6079571a33ceb/MiniEngine/Core/CommandContext.h
+ * @see https://www.w3.org/TR/webgpu/#gpucommandencoder
+ */
+export class ShadeGPUCommandContext {
+    #id = id_counter++;
+    /**
+     * Unique identifier for this context, useful for debugging
+     *
+     * @return {number}
+     */
+    get id() {
+        return this.#id;
+    }
+    /**
+     *
+     * @returns {boolean}
+     */
+    get isGPUCommandContext() {
+        return true;
+    }
+    /**
+     * Actual underlying encoder
+     * @type {GPUCommandEncoder}
+     */
+    #gpu_encoder
+    /**
+     * Don't circumvent {@link ShadeGPUCommandContext} unless you know what you're doing.
+     * {@link ShadeGPUCommandContext} is a wrapper around {@link GPUCommandEncoder} that provides additional spec-compliance asserts to help find errors sooner.
+     * @returns {GPUCommandEncoder}
+     */
+    get gpu_encoder() {
+        return this.#gpu_encoder;
+    }
+    /**
+     * @type {GPUTimerArray|undefined}
+     */
+    #debug_timers;
+    /**
+     *
+     * @type {function}
+     */
+    #debug_timers_callback = noop;
+    /**
+     *
+     * @param {function} debug_timers_callback
+     */
+    enable_debug_timers(debug_timers_callback) {
+        if (this.#debug_timers !== undefined) {
+            // already enabled
+            return;
+        }
+        this.#debug_timers = new GPUTimerArray(this.device);
+        this.#debug_timers_callback = debug_timers_callback;
+    }
+    /**
+     * The frame recorder collecting this context's spans, or null.
+     *
+     * @type {GPUFrameRecorder|null}
+     */
+    #profile_recorder = null;
+    /**
+     * Which query set this context is, within its frame. Carried into every span it records —
+     * timestamps from two query sets are not specified to share a clock domain, and a frame has
+     * one set per context.
+     *
+     * @type {number}
+     */
+    #profile_query_set_id = 0;
+    /**
+     * The work record for the pass currently being opened.
+     *
+     * Set by {@link #with_timestamp_writes} and consumed immediately by the `begin*Pass` that asked
+     * for it — the two are one operation, split only because the descriptor has to be built before
+     * the encoder exists.
+     *
+     * @type {GPUProfileWork|null}
+     */
+    #pending_work = null;
+    /**
+     * Wrap `encoder` so its dispatches and draws are recorded, when a capture asked for them.
+     *
+     * @param {GPUComputePassEncoder|GPURenderPassEncoder} encoder
+     * @returns {GPUComputePassEncoder|GPURenderPassEncoder}
+     */
+    #instrument_pass(encoder) {
+        const work = this.#pending_work;
+        if (work === null) {
+            this.#last_work = null;
+            return encoder;
+        }
+        this.#pending_work = null;
+        this.#last_work = work;
+        return make_profiling_pass_encoder(encoder, work);
+    }
+    /**
+     * Resolves once this context's timings have reached its recorder.
+     *
+     * @type {Promise<void>}
+     */
+    #profiling_absorbed = Promise.resolve();
+    /**
+     * @type {function}
+     */
+    #profiling_absorbed_resolve = noop;
+    /**
+     * Resolves after this context's timings have been read back and handed to its recorder.
+     *
+     * **Not the same moment as {@link done}.** `done` resolves from `onFinished`, which fires
+     * synchronously at submit — before any timestamp has been read. A caller that closes its frame
+     * on `done` commits an empty one, every time. Already-resolved when nothing is profiling.
+     *
+     * @returns {Promise<void>}
+     */
+    get profiling_absorbed() {
+        return this.#profiling_absorbed;
+    }
+    /**
+     * Record this context's pass timings into `recorder`.
+     *
+     * Independent of {@link enable_debug_timers}, which is the console-shaped one-off; both share
+     * the underlying {@link GPUTimerArray} and either may enable it.
+     *
+     * @param {GPUFrameRecorder} recorder
+     * @param {number} query_set_id this context's index within the frame
+     * @returns {void}
+     */
+    enable_profiling(recorder, query_set_id) {
+        assert.defined(recorder, 'recorder');
+        assert.isNonNegativeInteger(query_set_id, 'query_set_id');
+        assert.notOk(this.#finished, 'already finished');
+        if (this.#debug_timers === undefined) {
+            this.#debug_timers = new GPUTimerArray(this.device);
+        }
+        this.#profile_recorder = recorder;
+        this.#profile_query_set_id = query_set_id;
+        this.#profiling_absorbed = new Promise(resolve => {
+            this.#profiling_absorbed_resolve = resolve;
+        });
+    }
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics
+    /**
+     *
+     * @return {GPUDevice}
+     */
+    get device() {
+        return this.#graphics.device;
+    }
+    /**
+     *
+     * @return {TextureManager}
+     */
+    get textures() {
+        return this.#graphics.textures;
+    }
+    /**
+     * These are to be destroyed at the end of the context's lifetime.
+     * Need to be released at the end of the lifetime.
+     * @type {GPUBuffer[]}
+     */
+    #transient_buffers = [];
+    /**
+     *
+     * @type {GPUBuffer[]}
+     */
+    #staging_buffers = [];
+    /**
+     * Once finished, the encoder becomes inactive, we use this flag to track potential misuse and inform the user
+     * @type {boolean}
+     */
+    #finished = false;
+    /**
+     * @readonly
+     * @type {Signal<this>}
+     */
+    onFinished = new Signal();
+    /**
+     * @readonly
+     * @type {Signal<this>}
+     */
+    onBeforeFinish = new Signal();
+    /**
+     *
+     * @return {Promise<void>}
+     */
+    get done() {
+        if (this.#finished) {
+            return Promise.resolve();
+        }
+        return new Promise(resolve => {
+            this.onFinished.addOne(resolve);
+            if (this.#finished) {
+                // special case, double-checking to avoid race conditions
+                resolve();
+            }
+        });
+    }
+    /**
+     * Do not call directly, always use {@link create}
+     * @private
+     */
+    constructor() {
+        // private, do not call from the outside
+    }
+    /**
+     *
+     * @param {GraphicsContext} graphics
+     * @param {string} [label]
+     * @returns {ShadeGPUCommandContext}
+     */
+    static create(
+        graphics,
+        label = ""
+    ) {
+        assert.defined(graphics, 'graphics');
+        assert.equal(graphics.isGraphicsContext, true, "graphics.isGraphicsContext !== true");
+        assert.isString(label, 'label');
+        const r = new ShadeGPUCommandContext();
+        r.#graphics = graphics;
+        r.#gpu_encoder = graphics.device.createCommandEncoder({
+            label
+        });
+        // track how many we have open
+        debug_open_context_count++;
+        array_push_if_unique(debug_open_contexts, r);
+        if (debug_open_context_count > 1024) {
+            warn_limited(`Too many open GPU contexts`, 20);
+        }
+        return r;
+    }
+    /**
+     *
+     * @returns {GraphicsExecutionContext}
+     */
+    createFrameGraphContext() {
+        return new GraphicsExecutionContext(this.#graphics, this);
+    }
+    /**
+     *
+     * @param {FrameGraph} graph
+     */
+    encodeGraph(graph) {
+        assert.defined(graph, 'graph');
+        assert.isObject(graph, 'graph');
+        assert.equal(graph.isFrameGraph, true, "graph.isFrameGraph !== true");
+        // TODO check if the graph is empty, if so, we can skip the whole thing
+        const ctx = this.createFrameGraphContext();
+        graph.compile();
+        graph.execute(ctx);
+    }
+    /**
+     * @see https://www.w3.org/TR/webgpu/#dom-gpucommandencoder-clearbuffer
+     * @param {GPUBuffer} buffer
+     * @param {number} [offset=0]
+     * @param {number} [size]
+     */
+    clearBuffer(buffer, offset = 0, size) {
+        assert.defined(buffer, 'buffer');
+        assert.equal(buffer.usage & GPUBufferUsage.COPY_DST, GPUBufferUsage.COPY_DST, 'buffer must include COPY_DST usage flag');
+        assert.isNonNegativeInteger(offset, 'offset');
+        assert.equal(offset % 4, 0, 'offset must be a multiple of 4');
+        // console.log(`cmd.clearBuffer(${buffer.label}, ${offset}, ${size})`);
+        this.#gpu_encoder.clearBuffer(buffer, offset, size);
+    }
+    /**
+     * Not supported, only here to offer documentation hint
+     * see {@link texture_fill_rectangle}
+     * @throws {Error} Always, documentation hint only
+     */
+    clearTexture() {
+        throw new Error(`Documentation hint only, use texture_fill_rectangle instead`);
+    }
+    /**
+     * NOTE: only the explicit verbose form of the API is supported, shorthand such as `copyBufferToBuffer(source, destination, size)` are not supported.
+     * see https://www.w3.org/TR/webgpu/#gpucommandencoder-copybuffertobuffer
+     * @see GPUCommandEncoder.copyBufferToBuffer
+     * @param {GPUBuffer} source The GPUBuffer to copy from.
+     * @param {number} sourceOffset Offset in bytes into the source to begin copying from.
+     * @param {GPUBuffer} destination The GPUBuffer to copy to.
+     * @param {number} destinationOffset Offset in bytes into destination to place the copied data.
+     * @param {number} [size] Bytes to copy. In not specified, defaults to `source.size - sourceOffset`
+     */
+    copyBufferToBuffer(
+        source,
+        sourceOffset,
+        destination,
+        destinationOffset,
+        size
+    ) {
+        assert.notEqual(source.usage & GPUBufferUsage.COPY_SRC, 0, 'source must include COPY_SRC usage flag');
+        assert.isNonNegativeInteger(sourceOffset, 'sourceOffset');
+        assert.equal(sourceOffset % 4, 0, 'sourceOffset must be a multiple of 4');
+        assert.notEqual(destination.usage & GPUBufferUsage.COPY_DST, 0, 'destination must include COPY_DST usage flag');
+        assert.isNonNegativeInteger(destinationOffset, 'destinationOffset');
+        assert.equal(destinationOffset % 4, 0, 'destinationOffset must be a multiple of 4');
+        if (size !== undefined) {
+            assert.isNonNegativeInteger(size, 'size');
+            assert.equal(size % 4, 0, 'size must be a multiple of 4');
+            assert.greaterThanOrEqual(source.size, sourceOffset + size, 'source underflow');
+            assert.greaterThanOrEqual(destination.size, destinationOffset + size, 'destination underflow');
+        }
+        assert.notEqual(source, destination, 'source and destination must be different');
+        // console.log(`cmd.copyBufferToBuffer("${source.label}", ${sourceOffset}, "${destination.label}", ${destinationOffset}, ${size})`);
+        this.#gpu_encoder.copyBufferToBuffer(
+            source,
+            sourceOffset,
+            destination,
+            destinationOffset,
+            size
+        );
+    }
+    /**
+     *
+     * @param {GPUImageCopyTexture} source
+     * @param {GPUImageCopyTexture} destination
+     * @param {GPUExtent3DStrict} copySize
+     */
+    copyTextureToTexture(source,
+                         destination,
+                         copySize
+    ) {
+        this.#gpu_encoder.copyTextureToTexture(source, destination, copySize);
+    }
+    /**
+     *
+     * @param {GPUComputePassDescriptor} [descriptor]
+     * @returns {GPUComputePassEncoder}
+     */
+    beginComputePass(descriptor) {
+        const encoder = this.#gpu_encoder;
+        const _descriptor = this.#with_timestamp_writes(descriptor, 'compute');
+        // console.log(`cmd.beginComputePass(${descriptor.label})`);
+        return this.#instrument_pass(encoder.beginComputePass(_descriptor))
+    }
+    /**
+     * The descriptor a pass should actually be begun with, once timing has had its say.
+     *
+     * Copies rather than writing through. Several call sites hand in a descriptor they reuse across
+     * passes, and stamping `timestampWrites` onto it left the next pass carrying the previous
+     * pass's query indices. The copy is one shallow spread per pass and only when timers are on.
+     *
+     * Returns the descriptor unchanged when timing is off, when the device withheld the feature, or
+     * when the timer array has no slot left ({@link GPUTimerArray#dropped_count}). An untimed pass
+     * is the correct outcome in all three; a pass carrying indices the query set does not have is a
+     * validation error.
+     *
+     * @param {GPUComputePassDescriptor|GPURenderPassDescriptor} [descriptor]
+     * @param {string} kind one of 'compute', 'render'
+     * @returns {GPUComputePassDescriptor|GPURenderPassDescriptor}
+     */
+    #with_timestamp_writes(descriptor, kind) {
+        const timers = this.#debug_timers;
+        if (timers === undefined) {
+            return descriptor;
+        }
+        if (!this.#graphics.device.features.has('timestamp-query')) {
+            return descriptor;
+        }
+        // `beginComputePass()` is legal with no descriptor at all; reading `.label` off nothing is
+        // not, and used to throw here the moment timers were switched on
+        const source = descriptor !== undefined ? descriptor : {};
+        const writes = kind === 'compute'
+            ? timers.getComputeWrites(source.label)
+            : timers.getRenderWrites(source.label);
+        if (writes === undefined) {
+            return descriptor;
+        }
+        const recorder = this.#profile_recorder;
+        if (recorder !== null) {
+            /*
+             The one moment the join can be made. The recorder knows which frame graph pass is
+             executing right now; the slot is what the timings will come back keyed by. Neither
+             fact is recoverable later — see GPUFrameRecorder.
+            */
+            this.#pending_work = recorder.note_pass_slot(
+                this.#profile_query_set_id,
+                writes.beginningOfPassWriteIndex / 2
+            );
+        } else {
+            this.#pending_work = null;
+        }
+        return {
+            ...source,
+            timestampWrites: writes
+        };
+    }
+    /**
+     *
+     * @param {ComputePipelineDescriptor} pipeline
+     * @param {string} [label]
+     * @param {GPUBindingResource[][]} [bindings]
+     * @returns {GPUComputePassEncoder}
+     */
+    constructComputePass({
+                             pipeline,
+                             label,
+                             bindings = []
+                         }) {
+        const pass_descriptor = {
+            label
+        };
+        if (label === undefined) {
+            pass_descriptor.label = pipeline.label;
+        }
+        const graphics = this.#graphics;
+        const pass = this.beginComputePass(pass_descriptor);
+        const gpu_pipeline = graphics.compute_pipelines.obtain(pipeline);
+        pass.setPipeline(gpu_pipeline);
+        this.#note_pipeline(pipeline, true);
+        graphics.setPipelineBindings(pass, pipeline, bindings);
+        // console.warn(`cmd.constructComputePass(${pass_descriptor.label})`)
+        return pass;
+    }
+    /**
+     * Record which pipeline a pass ran, and for a compute pipeline its workgroup size.
+     *
+     * Only reachable from `constructComputePass` / `constructRenderPass`, which is the only place a
+     * *descriptor* is in hand. `setPipeline` receives the compiled `GPUComputePipeline`, and the
+     * WGSL that carries `@workgroup_size` is not on it — so a pass begun the long way records its
+     * counts but not what ran them, which the model represents as an unknown rather than a zero.
+     *
+     * @param {ComputePipelineDescriptor|RenderPipelineDescriptor} pipeline
+     * @param {boolean} is_compute
+     * @returns {void}
+     */
+    #note_pipeline(pipeline, is_compute) {
+        const work = this.#last_work;
+        if (work === null) {
+            return;
+        }
+        work.pipeline = pipeline.label ?? "";
+        if (is_compute) {
+            work.workgroup_size = parse_workgroup_size(pipeline.compute?.module?.code);
+        }
+    }
+    /**
+     * The work record of the most recently opened pass, so `construct*Pass` can annotate it after
+     * the encoder has been made.
+     *
+     * @type {GPUProfileWork|null}
+     */
+    #last_work = null;
+    /**
+     * Begins a labeled debug group containing subsequent commands.
+     * @see https://gpuweb.github.io/gpuweb/#debug-markers
+     * @param {string} label
+     */
+    pushDebugGroup(label) {
+        assert.isString(label, 'label');
+        this.#gpu_encoder.pushDebugGroup(label);
+        // console.group("cmd/debug_group=" + label)
+    }
+    /**
+     * Ends the labeled debug group most recently started by pushDebugGroup().
+     * @see https://gpuweb.github.io/gpuweb/#debug-markers
+     */
+    popDebugGroup() {
+        this.#gpu_encoder.popDebugGroup();
+        // console.groupEnd();
+    }
+    /**
+     * Marks a point in a stream of commands with a label.
+     * @see https://gpuweb.github.io/gpuweb/#debug-markers
+     * @param {string} label
+     */
+    insertDebugMarker(label) {
+        assert.isString(label, 'label');
+        this.#gpu_encoder.insertDebugMarker(label);
+    }
+    /**
+     *
+     * @param {string} [label]
+     * @param {RenderPipelineDescriptor} pipeline
+     * @param {GPUBindingResource[][]} [bindings]
+     * @param {GPURenderPassColorAttachment[]} colorAttachments
+     * @param {GPURenderPassDepthStencilAttachment} [depthStencilAttachment]
+     * @returns {GPURenderPassEncoder}
+     */
+    constructRenderPass({
+                            label,
+                            pipeline,
+                            bindings,
+                            colorAttachments,
+                            depthStencilAttachment,
+                        }) {
+        assert.defined(pipeline, 'pipeline');
+        assert.equal(pipeline.isRenderPipelineDescriptor, true, "pipeline.isRenderPipelineDescriptor !== true");
+        const pass_descriptor = {
+            label,
+            colorAttachments,
+            depthStencilAttachment
+        };
+        if (label === undefined) {
+            pass_descriptor.label = pipeline.label;
+        }
+        const graphics = this.#graphics;
+        // TODO rewrite the pipeline if necessary to achieve compatibility with colorAttachment formats
+        const gpu_pipeline = graphics.render_pipelines.obtain(pipeline);
+        const pass = this.beginRenderPass(pass_descriptor);
+        pass.setPipeline(gpu_pipeline);
+        this.#note_pipeline(pipeline, false);
+        graphics.setPipelineBindings(pass, pipeline, bindings);
+        // console.warn(`cmd.constructRenderPass(${pass_descriptor.label})`)
+        return pass;
+    }
+    /**
+     *
+     * @param {GPURenderPassDescriptor} descriptor
+     * @returns {GPURenderPassEncoder}
+     */
+    beginRenderPass(descriptor) {
+        const _descriptor = this.#with_timestamp_writes(descriptor, 'render');
+        // console.log(`cmd.beginRenderPass(${descriptor.label})`);
+        return this.#instrument_pass(this.#gpu_encoder.beginRenderPass(_descriptor))
+    }
+    /**
+     *
+     * @param {GPUQuerySet} querySet
+     * @param {number} firstQuery
+     * @param {number} queryCount
+     * @param {GPUBuffer} destination
+     * @param {number} destinationOffset
+     */
+    resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset) {
+        this.#gpu_encoder.resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset);
+    }
+    /**
+     * Transient buffers are automatically released at the end of the context's lifetime;
+     * however, we can explicitly release it earlier to allow for reuse.
+     *
+     * @param {GPUBuffer} buffer
+     * @return {boolean} true if buffer was released, false if it was not found
+     */
+    releaseTransientBuffer(buffer) {
+        assert.defined(buffer, 'buffer');
+        if (!array_remove_first(this.#transient_buffers, buffer)) {
+            return false;
+        }
+        const allocator = this.#transient_allocator;
+        return allocator.release(buffer);
+    }
+    /**
+     *
+     * @return {GPUBufferAllocator}
+     */
+    get #transient_allocator() {
+        return this.#graphics.buffer_allocator_main;
+    }
+    /**
+     * Allocated buffer will only be valid until the context is finished.
+     *
+     * @param {number|GPUBufferUsage} usage
+     * @param {number} size
+     * @returns {GPUBuffer} managed buffer
+     */
+    allocateTransientBuffer(
+        usage = GPUBufferUsage.UNIFORM,
+        size
+    ) {
+        assert.isNonNegativeInteger(size, 'size');
+        assert.isInteger(usage, 'usage');
+        assert.notOk(this.#finished, 'already finished');
+        scratch_buffer_descriptor.size = size;
+        // COPY_DST is needed to write the data
+        scratch_buffer_descriptor.usage = usage | GPUBufferUsage.COPY_DST;
+        const allocator = this.#transient_allocator;
+        const buffer = allocator.get(scratch_buffer_descriptor, this);
+        // remember so we can clean up at the end
+        this.#transient_buffers.push(buffer);
+        return buffer;
+    }
+    /**
+     *
+     * @param {ArrayBuffer} data CPU-side data to place into the GPU buffer
+     * @param {number|GPUBufferUsage} [usage=GPUBufferUsage.UNIFORM]
+     * @param {number} [offset] offset into source data where to start copying from
+     * @param {number} [size] in bytes
+     * @returns {GPUBuffer} managed buffer, will be automatically destroyed when context is finished
+     */
+    allocateTransientBufferAndLoad(
+        data,
+        usage = GPUBufferUsage.UNIFORM,
+        offset = 0,
+        size = data.byteLength
+    ) {
+        assert.isInstanceOf(data, ArrayBuffer, 'data');
+        assert.isInteger(usage, 'usage');
+        assert.isNonNegativeInteger(offset, 'offset');
+        assert.isNonNegativeInteger(size, 'size');
+        assert.notOk(this.#finished, 'already finished');
+        const buffer = this.allocateTransientBuffer(
+            usage,
+            size
+        );
+        this.writeBuffer(buffer, 0, data, offset, size);
+        return buffer;
+    }
+    /**
+     * @template T
+     * @param {WebGPUType} type
+     * @param {T} value
+     * @param {number|GPUBufferUsage} [usage]
+     * @return {GPUBuffer}
+     */
+    allocateTransientValueBuffer(
+        type,
+        value,
+        usage
+    ) {
+        assert.defined(type, 'type');
+        assert.notNull(type, 'type');
+        const buffer = this.allocateTransientBuffer(usage, type.aligned_size);
+        this.writeValueBuffer(buffer, 0, type, value);
+        return buffer;
+    }
+    /**
+     * @template T
+     * @param {GPUBuffer} buffer
+     * @param {number} buffer_offset
+     * @param {WebGPUType} type
+     * @param {T} value
+     */
+    writeValueBuffer(buffer, buffer_offset, type, value) {
+        assert.notOk(this.#finished, 'already finished');
+        const gfx = this.#graphics;
+        const size = type.aligned_size;
+        const stage = gfx.buffer_allocator_staging.get(size);
+        const mapped = stage.getMappedRange(0, size);
+        write_gpu_typed_buffer(value, type, mapped, 0);
+        stage.unmap();
+        this.#staging_buffers.push(stage);
+        this.copyBufferToBuffer(stage, 0, buffer, buffer_offset, size);
+    }
+    /**
+     * Very similar to {@link GPUQueue.writeBuffer}, but instead of doing the operation direction on the queue - uses a staging buffer under the hood and performs the actual write operation as part of the commmand buffer
+     * @param {GPUBuffer} buffer
+     * @param {number} buffer_offset
+     * @param {ArrayBuffer} data
+     * @param {number} data_offset
+     * @param {number} size
+     */
+    writeBuffer(buffer, buffer_offset, data, data_offset, size) {
+        assert.defined(buffer, 'buffer');
+        assert.isNonNegativeInteger(buffer_offset, 'buffer_offset');
+        assert.defined(data, 'data');
+        assert.isNonNegativeInteger(data_offset, 'data_offset');
+        assert.isNonNegativeInteger(size, 'size');
+        const gfx = this.#graphics;
+        const stage = gfx.buffer_allocator_staging.get(size);
+        const mapped = stage.getMappedRange(0, size);
+        array_buffer_copy(data, data_offset, mapped, 0, size);
+        stage.unmap();
+        this.#staging_buffers.push(stage);
+        this.copyBufferToBuffer(stage, 0, buffer, buffer_offset, size);
+    }
+    #cleanup() {
+        // console.warn('cmd.cleanup()');
+        const transient_buffers = this.#transient_buffers;
+        const transient_buffer_count = transient_buffers.length;
+        const buffer_allocator_transient = this.#transient_allocator;
+        // release in reverse order to make it more likely that we'd end up in the same acquisition order next time, which is desirable for caching
+        for (let i = transient_buffer_count - 1; i >= 0; i--) {
+            const buffer = transient_buffers[i];
+            buffer_allocator_transient.release(buffer);
+        }
+        // staging buffers
+        const buffer_allocator_staging = this.#graphics.buffer_allocator_staging;
+        for (const staging of this.#staging_buffers) {
+            buffer_allocator_staging.release(staging);
+        }
+    }
+    /**
+     * Performs both {@link GPUCommandEncoder.finish} and flushed command buffer
+     */
+    finish() {
+        if (this.#finished) {
+            console.warn('Context already finished');
+            return;
+        }
+        this.onBeforeFinish.send1(this);
+        debug_open_context_count--;
+        array_remove_first(debug_open_contexts, this);
+        const encoder = this.#gpu_encoder;
+        const debug_timers = this.#debug_timers;
+        if (debug_timers !== undefined) {
+            debug_timers.resolve(encoder);
+        }
+        this.#finished = true;
+        // release encoder reference
+        this.#gpu_encoder = undefined;
+        const command_buffer = encoder.finish();
+        const graphics = this.#graphics;
+        const queue = graphics.device.queue;
+        queue.submit([command_buffer]);
+        // cleanup allocated memory
+        this.#cleanup();
+        if (debug_timers !== undefined) {
+            const recorder = this.#profile_recorder;
+            const query_set_id = this.#profile_query_set_id;
+            debug_timers
+                .download_results()
+                .then(() => {
+                    if (recorder !== null) {
+                        recorder.absorb(debug_timers, query_set_id);
+                    }
+                    // The console-shaped path stays exactly as it was; a context can be doing both.
+                    const table = debug_timers.results_to_console_table();
+                    this.#debug_timers_callback(table);
+                })
+                .finally(() => {
+                    debug_timers.destroy();
+                    // In `finally` so a failed readback still releases whoever is waiting on the
+                    // frame. A profile session that hangs because one download rejected is worse
+                    // than one missing a frame.
+                    this.#profiling_absorbed_resolve();
+                });
+            this.#debug_timers = undefined;
+            this.#profile_recorder = null;
+        }
+        this.onFinished.send1(this);
+    }
 }