@woosh/meep-engine 3.12.0 → 3.13.1

package/src/shade/device/ShadeGPUCommandContext.js

@@ -1,995 +1,802 @@
-import { assert } from "../../core/assert.js";
-import { BinaryBuffer } from "../../core/binary/BinaryBuffer.js";
-import { platform_compute_endianness } from "../../core/binary/platform_compute_endianness.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 = [],
-                             immediate
-                         }) {
-
-        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, immediate);
-
-        // 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,
-                            immediate,
-                        }) {
-        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, immediate);
-
-        // 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;
-    }
-
-    /**
-     * Scratch for immediate data, created on first use and reused for the life of the context.
-     *
-     * One buffer is enough, and `position` returns to 0 for every write, because `setImmediates`
-     * copies the bytes it is given at the point of the call — the region is free again the moment
-     * the pass encoder has taken it. Nothing here ever grows: the default capacity is far above the
-     * 64-byte ceiling {@link ShaderResourceSetDescriptor#setImmediate} enforces, so the backing
-     * `ArrayBuffer` is allocated once and never reallocated.
-     *
-     * @type {BinaryBuffer|null}
-     */
-    #immediate_buffer = null;
-
-    /**
-     * Serialise a shader's immediate data ready for `setImmediates`, or return undefined when the
-     * shader declares none.
-     *
-     * Allocates nothing after the first call.
-     *
-     * @param {ShaderResourceSetDescriptor} resources
-     * @param {Object} map the shader's binding map
-     * @returns {{buffer: BinaryBuffer, offset: number, size: number}|undefined}
-     */
-    writeImmediate(resources, map) {
-        if (resources.immediateSize === 0) {
-            return undefined;
-        }
-
-        let buffer = this.#immediate_buffer;
-
-        if (buffer === null) {
-            buffer = new BinaryBuffer();
-
-            // GPU buffer contents must match the host, and BinaryBuffer's own default is
-            // little-endian regardless of platform. Getting this wrong produces bytes that are
-            // correct on every machine anyone is likely to test on and wrong on the rest.
-            buffer.endianness = platform_compute_endianness();
-
-            this.#immediate_buffer = buffer;
-        }
-
-        buffer.position = 0;
-
-        if (!resources.writeImmediate(map, buffer)) {
-            return undefined;
-        }
-
-        return { buffer, offset: 0, size: buffer.position };
-    }
-
-    /**
-     * @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);
-
-    }
+import { assert } from "../../core/assert.js";
+import { BinaryBuffer } from "../../core/binary/BinaryBuffer.js";
+import { platform_compute_endianness } from "../../core/binary/platform_compute_endianness.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 { ShadeGPUComputePassEncoder } from "./pass/ShadeGPUComputePassEncoder.js";
+import { ShadeGPURenderPassEncoder } from "./pass/ShadeGPURenderPassEncoder.js";
+import { ShadeGPUContextProfiler } from "./timing/ShadeGPUContextProfiler.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;
+    }
+
+    /**
+     * This context's profiling attachment, or null when nothing is profiling — which is the
+     * ordinary case and costs one null check per pass.
+     *
+     * **Never cleared.** `finish()` is followed by a read of {@link profiling_absorbed}, and a null
+     * here reports an already-resolved promise, which closes the frame before a single timestamp has
+     * come back. It holds no GPU resources after `absorb()` destroys the timer array, so keeping the
+     * reference costs nothing.
+     *
+     * @type {ShadeGPUContextProfiler|null}
+     */
+    #profiler = null;
+
+    /**
+     * 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() {
+        const profiler = this.#profiler;
+
+        return profiler === null ? Promise.resolve() : profiler.absorbed;
+    }
+
+    /**
+     * Record this context's pass timings into `recorder`.
+     *
+     * @param {GPUFrameRecorder} recorder
+     * @param {number} query_set_id this context's index within the frame
+     * @returns {void}
+     */
+    enable_profiling(recorder, query_set_id) {
+        assert.notOk(this.#finished, 'already finished');
+        assert.isNull(this.#profiler, 'already profiling');
+
+        this.#profiler = new ShadeGPUContextProfiler(this.device, recorder, query_set_id);
+    }
+
+    /**
+     * @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 {ShadeGPUComputePassEncoder}
+     */
+    beginComputePass(descriptor) {
+        const encoder = this.#gpu_encoder;
+        const profiler = this.#profiler;
+
+        // console.log(`cmd.beginComputePass(${descriptor.label})`);
+
+        if (profiler === null) {
+            return new ShadeGPUComputePassEncoder(encoder.beginComputePass(descriptor), null);
+        }
+
+        return profiler.begin_compute_pass(encoder, descriptor);
+    }
+
+
+    /**
+     *
+     * @param {ComputePipelineDescriptor} pipeline
+     * @param {string} [label]
+     * @param {GPUBindingResource[][]} [bindings]
+     * @returns {ShadeGPUComputePassEncoder}
+     */
+    constructComputePass({
+                             pipeline,
+                             label,
+                             bindings = [],
+                             immediate
+                         }) {
+
+        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);
+
+        pass.record_pipeline(pipeline);
+
+        graphics.setPipelineBindings(pass, pipeline, bindings, immediate);
+
+        // 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 {ShadeGPURenderPassEncoder}
+     */
+    constructRenderPass({
+                            label,
+                            pipeline,
+                            bindings,
+                            colorAttachments,
+                            depthStencilAttachment,
+                            immediate,
+                        }) {
+        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);
+
+        pass.record_pipeline(pipeline);
+
+        graphics.setPipelineBindings(pass, pipeline, bindings, immediate);
+
+        // console.warn(`cmd.constructRenderPass(${pass_descriptor.label})`)
+
+        return pass;
+    }
+
+    /**
+     *
+     * @param {GPURenderPassDescriptor} descriptor
+     * @returns {ShadeGPURenderPassEncoder}
+     */
+    beginRenderPass(descriptor) {
+        const encoder = this.#gpu_encoder;
+        const profiler = this.#profiler;
+
+        // console.log(`cmd.beginRenderPass(${descriptor.label})`);
+
+        if (profiler === null) {
+            return new ShadeGPURenderPassEncoder(encoder.beginRenderPass(descriptor), null);
+        }
+
+        return profiler.begin_render_pass(encoder, 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;
+    }
+
+    /**
+     * Scratch for immediate data, created on first use and reused for the life of the context.
+     *
+     * One buffer is enough, and `position` returns to 0 for every write, because `setImmediates`
+     * copies the bytes it is given at the point of the call — the region is free again the moment
+     * the pass encoder has taken it. Nothing here ever grows: the default capacity is far above the
+     * 64-byte ceiling {@link ShaderResourceSetDescriptor#setImmediate} enforces, so the backing
+     * `ArrayBuffer` is allocated once and never reallocated.
+     *
+     * @type {BinaryBuffer|null}
+     */
+    #immediate_buffer = null;
+
+    /**
+     * Serialise a shader's immediate data ready for `setImmediates`, or return undefined when the
+     * shader declares none.
+     *
+     * Allocates nothing after the first call.
+     *
+     * @param {ShaderResourceSetDescriptor} resources
+     * @param {Object} map the shader's binding map
+     * @returns {{buffer: BinaryBuffer, offset: number, size: number}|undefined}
+     */
+    writeImmediate(resources, map) {
+        if (resources.immediateSize === 0) {
+            return undefined;
+        }
+
+        let buffer = this.#immediate_buffer;
+
+        if (buffer === null) {
+            buffer = new BinaryBuffer();
+
+            // GPU buffer contents must match the host, and BinaryBuffer's own default is
+            // little-endian regardless of platform. Getting this wrong produces bytes that are
+            // correct on every machine anyone is likely to test on and wrong on the rest.
+            buffer.endianness = platform_compute_endianness();
+
+            this.#immediate_buffer = buffer;
+        }
+
+        buffer.position = 0;
+
+        if (!resources.writeImmediate(map, buffer)) {
+            return undefined;
+        }
+
+        return { buffer, offset: 0, size: buffer.position };
+    }
+
+    /**
+     * @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 profiler = this.#profiler;
+
+        if (profiler !== null) {
+            profiler.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 (profiler !== null) {
+            // Kept, not cleared — `profiling_absorbed` is read after `finish()` and a null here
+            // would report an already-resolved promise. See the field.
+            profiler.absorb();
+        }
+
+        this.onFinished.send1(this);
+
+    }
 }