@woosh/meep-engine 3.30.0 → 3.32.0

package/src/shade/device/ShadeGPUCommandContext.js

@@ -1,858 +1,1004 @@
-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";
-
-/**
- * @typedef {import("../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
- */
-
-/**
- * @typedef {import("../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
- * @typedef {import("../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
- * @typedef {import("../renderer/GraphicsContext.js").GraphicsContext} GraphicsContext
- * @typedef {import("../renderer/shader/resource/ShaderResourceSetDescriptor.js").ShaderResourceSetDescriptor} ShaderResourceSetDescriptor
- * @typedef {import("../renderer/shader/type/WebGPUType.js").WebGPUType} WebGPUType
- * @typedef {import("../renderer/texture/TextureManager.js").TextureManager} TextureManager
- * @typedef {import("./timing/profile/GPUFrameRecorder.js").GPUFrameRecorder} GPUFrameRecorder
- */
-
-/**
- * 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;
-    }
-
-    /**
-     * The graphics context this was created against, whose allocators the commands recorded here
-     * draw on.
-     *
-     * @returns {GraphicsContext}
-     */
-    get graphics() {
-        return this.#graphics;
-    }
-
-    /**
-     * Whether {@link finish} has run — which is the moment the commands recorded here were
-     * submitted. Anything that must not happen before submission, such as mapping a buffer one of
-     * those commands copies into, checks this rather than counting frames.
-     *
-     * @returns {boolean}
-     */
-    get finished() {
-        return this.#finished;
-    }
-
-    /**
-     * 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);
-    }
-
-    /**
-     * Texels out of a texture into a buffer — what a readback of a rendered image starts with.
-     *
-     * @param {GPUImageCopyTexture} source
-     * @param {GPUImageCopyBuffer} destination
-     * @param {GPUExtent3DStrict} copySize
-     */
-    copyTextureToBuffer(source, destination, copySize) {
-        assert.defined(source, 'source');
-        assert.defined(destination, 'destination');
-        assert.notEqual(destination.buffer.usage & GPUBufferUsage.COPY_DST, 0, 'destination must include COPY_DST usage flag');
-
-        this.#gpu_encoder.copyTextureToBuffer(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 {Object} options
-     * @param {ComputePipelineDescriptor} options.pipeline
-     * @param {string} [options.label]
-     * @param {GPUBindingResource[][]} [options.bindings]
-     * @param {{buffer: BinaryBuffer, offset: number, size: number}} [options.immediate] bytes to hand
-     *        the pass through `setImmediates`, when the pipeline declares immediate data
-     * @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 {Object} options
-     * @param {string} [options.label]
-     * @param {RenderPipelineDescriptor} options.pipeline
-     * @param {GPUBindingResource[][]} [options.bindings]
-     * @param {GPURenderPassColorAttachment[]} options.colorAttachments
-     * @param {GPURenderPassDepthStencilAttachment} [options.depthStencilAttachment]
-     * @param {{buffer: BinaryBuffer, offset: number, size: number}} [options.immediate] bytes to hand
-     *        the pass through `setImmediates`, when the pipeline declares immediate data
-     * @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);
-
-    }
+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 { MAPPED_UPLOAD_THRESHOLD } from "../renderer/buffer/GPUBufferUploadAllocator.js";
+import { BufferResourceDescriptor } from "./graph/BufferResourceDescriptor.js";
+import { GraphicsExecutionContext } from "./graph/GraphicsExecutionContext.js";
+
+/**
+ * @typedef {import("../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ */
+
+/**
+ * @typedef {import("../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
+ * @typedef {import("../renderer/GraphicsContext.js").GraphicsContext} GraphicsContext
+ * @typedef {import("../renderer/shader/resource/ShaderResourceSetDescriptor.js").ShaderResourceSetDescriptor} ShaderResourceSetDescriptor
+ * @typedef {import("../renderer/shader/type/WebGPUType.js").WebGPUType} WebGPUType
+ * @typedef {import("../renderer/texture/TextureManager.js").TextureManager} TextureManager
+ * @typedef {import("../renderer/buffer/GPUUploadBlock.js").GPUUploadBlock} GPUUploadBlock
+ * @typedef {import("./timing/profile/GPUFrameRecorder.js").GPUFrameRecorder} GPUFrameRecorder
+ */
+
+/**
+ * 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;
+    }
+
+    /**
+     * The graphics context this was created against, whose allocators the commands recorded here
+     * draw on.
+     *
+     * @returns {GraphicsContext}
+     */
+    get graphics() {
+        return this.#graphics;
+    }
+
+    /**
+     * Whether {@link finish} has run — which is the moment the commands recorded here were
+     * submitted. Anything that must not happen before submission, such as mapping a buffer one of
+     * those commands copies into, checks this rather than counting frames.
+     *
+     * @returns {boolean}
+     */
+    get finished() {
+        return this.#finished;
+    }
+
+    /**
+     * 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 = [];
+
+    /**
+     * Upload blocks this context has written its small uploads into, the one being filled last. Sent
+     * to the GPU just before the submit, one queue write per block, and given back when the context
+     * finishes.
+     *
+     * @type {GPUUploadBlock[]}
+     */
+    #upload_blocks = [];
+
+    /**
+     * Mapped staging buffers this context's large uploads went through, one each. Given back when the
+     * context finishes, and mapped again by their pool before it hands them out anew.
+     *
+     * @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);
+    }
+
+    /**
+     * Texels out of a texture into a buffer — what a readback of a rendered image starts with.
+     *
+     * @param {GPUImageCopyTexture} source
+     * @param {GPUImageCopyBuffer} destination
+     * @param {GPUExtent3DStrict} copySize
+     */
+    copyTextureToBuffer(source, destination, copySize) {
+        assert.defined(source, 'source');
+        assert.defined(destination, 'destination');
+        assert.notEqual(destination.buffer.usage & GPUBufferUsage.COPY_DST, 0, 'destination must include COPY_DST usage flag');
+
+        this.#gpu_encoder.copyTextureToBuffer(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 {Object} options
+     * @param {ComputePipelineDescriptor} options.pipeline
+     * @param {string} [options.label]
+     * @param {GPUBindingResource[][]} [options.bindings]
+     * @param {{buffer: BinaryBuffer, offset: number, size: number}} [options.immediate] bytes to hand
+     *        the pass through `setImmediates`, when the pipeline declares immediate data
+     * @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 {Object} options
+     * @param {string} [options.label]
+     * @param {RenderPipelineDescriptor} options.pipeline
+     * @param {GPUBindingResource[][]} [options.bindings]
+     * @param {GPURenderPassColorAttachment[]} options.colorAttachments
+     * @param {GPURenderPassDepthStencilAttachment} [options.depthStencilAttachment]
+     * @param {{buffer: BinaryBuffer, offset: number, size: number}} [options.immediate] bytes to hand
+     *        the pass through `setImmediates`, when the pipeline declares immediate data
+     * @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;
+    }
+
+    /**
+     * Like {@link writeBuffer}, with the bytes serialised from `value` as `type` lays them out.
+     *
+     * @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 size = type.aligned_size;
+
+        if (size >= MAPPED_UPLOAD_THRESHOLD) {
+            const stage = this.#graphics.buffer_allocator_staging.get(size);
+
+            // recorded before it is filled, so a fill that throws still gives it back
+            this.#staging_buffers.push(stage);
+
+            write_gpu_typed_buffer(value, type, stage.getMappedRange(0, size), 0);
+
+            stage.unmap();
+
+            this.copyBufferToBuffer(stage, 0, buffer, buffer_offset, size);
+
+            return;
+        }
+
+        const block = this.#upload_block_with_room(size);
+        const offset = block.allocate(size);
+
+        write_gpu_typed_buffer(value, type, block.data, offset);
+
+        this.copyBufferToBuffer(block.buffer, offset, buffer, buffer_offset, size);
+    }
+
+    /**
+     * Write bytes into `buffer` at this point in the command stream: after everything recorded
+     * before this call, and before everything recorded after it.
+     *
+     * That is the difference from {@link GPUQueue#writeBuffer}, which lands ahead of the whole
+     * submission — ahead of passes recorded earlier in it that may still need the old contents. Here
+     * the bytes are staged, and a copy out of the staging is recorded in their place. Small writes
+     * are staged in this context's upload blocks, which reach the GPU with one queue write each when
+     * the context finishes, so a frame of thousands of them costs no mapping at all; writes of
+     * {@link MAPPED_UPLOAD_THRESHOLD} bytes or more go through a mapped staging buffer each, which is
+     * the faster road for bytes.
+     *
+     * @param {GPUBuffer} buffer
+     * @param {number} buffer_offset
+     * @param {ArrayBuffer} data
+     * @param {number} data_offset
+     * @param {number} size a multiple of 4, as for any buffer copy
+     */
+    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');
+
+        assert.notOk(this.#finished, 'already finished');
+
+        if (size % 4 !== 0) {
+            // Refused here rather than left to the copy, as a mapped staging buffer of this size
+            // always was: a copy moves whole 4-byte words, and one that cannot takes the context's
+            // whole submission down with it, later, without naming the write that did it.
+            throw new RangeError(`writeBuffer: size ${size} is not a multiple of 4`);
+        }
+
+        if (size === 0) {
+            // a copy of nothing changes nothing
+            return;
+        }
+
+        if (size >= MAPPED_UPLOAD_THRESHOLD) {
+            const stage = this.#graphics.buffer_allocator_staging.get(size);
+
+            // recorded before it is filled, so a fill that throws still gives it back
+            this.#staging_buffers.push(stage);
+
+            array_buffer_copy(data, data_offset, stage.getMappedRange(0, size), 0, size);
+
+            stage.unmap();
+
+            this.copyBufferToBuffer(stage, 0, buffer, buffer_offset, size);
+
+            return;
+        }
+
+        const block = this.#upload_block_with_room(size);
+        const offset = block.allocate(size);
+
+        array_buffer_copy(data, data_offset, block.data, offset, size);
+
+        this.copyBufferToBuffer(block.buffer, offset, buffer, buffer_offset, size);
+    }
+
+    /**
+     * The block to take the next `size` bytes of upload from: the one being filled, or a fresh one
+     * when that is full. Every write that comes here is smaller than
+     * {@link MAPPED_UPLOAD_THRESHOLD}, so any empty block holds it.
+     *
+     * A block that cannot take the next write is not revisited: what is left in it is wasted until
+     * the context finishes, which bounds the waste at one block's tail per block and keeps every
+     * write a single contiguous copy.
+     *
+     * @param {number} size
+     * @returns {GPUUploadBlock}
+     */
+    #upload_block_with_room(size) {
+        const blocks = this.#upload_blocks;
+        const last = blocks.length - 1;
+
+        if (last >= 0 && blocks[last].fits(size)) {
+            return blocks[last];
+        }
+
+        const block = this.#graphics.buffer_allocator_upload.get();
+
+        blocks.push(block);
+
+        return block;
+    }
+
+    /**
+     * Put this context's upload blocks on the GPU: one queue write per block, of the part written.
+     *
+     * Must come immediately before the submit, and this is the whole of why a block can go back to
+     * its pool the moment its context finishes rather than when the GPU is done with it. The queue
+     * runs its operations in order, so a write issued here lands after everything submitted before
+     * this context — including the copies of any earlier context that held the same block — and
+     * before this context's own copies read it. Nothing is mapped, so nothing is waited for.
+     *
+     * A queue write lands ahead of its whole submission, which is why it goes only into a block and
+     * never into a destination: blocks come from a pool of their own that nothing aliases, while
+     * the frame graph's buffers are aliased within a submission, and a queue write into one of those
+     * would overwrite what an earlier pass in it still needs.
+     *
+     * @param {GPUQueue} queue
+     */
+    #send_uploads(queue) {
+        const blocks = this.#upload_blocks;
+        const count = blocks.length;
+
+        for (let i = 0; i < count; i++) {
+            const block = blocks[i];
+
+            queue.writeBuffer(block.buffer, 0, block.data, 0, block.used);
+        }
+    }
+
+    #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);
+
+        }
+
+        // Blocks go back now rather than when the GPU is done with them — see #send_uploads.
+        const buffer_allocator_upload = this.#graphics.buffer_allocator_upload;
+
+        for (const block of this.#upload_blocks) {
+            buffer_allocator_upload.release(block);
+        }
+
+        this.#upload_blocks.length = 0;
+
+        // staging buffers are mapped again by their pool, which is when they are free again
+        const buffer_allocator_staging = this.#graphics.buffer_allocator_staging;
+
+        for (const staging of this.#staging_buffers) {
+            if (staging.mapState === "mapped") {
+                // a write that threw while filling it, so no copy out of it was recorded; unmapped
+                // here so its pool maps it afresh rather than handing out a range already given out
+                staging.unmap();
+            }
+
+            buffer_allocator_staging.release(staging);
+        }
+
+        this.#staging_buffers.length = 0;
+    }
+
+    /**
+     * 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 graphics = this.#graphics;
+        const queue = graphics.device.queue;
+
+        /*
+         The buffers come back and the waiters are told WHATEVER happens in here.
+
+         GPUCommandEncoder.finish() throws when the encoder is locked — any pass left un-end()ed
+         anywhere in the frame graph — and queue.submit throws on a malformed argument. This used
+         to be a bare sequence, so either throw skipped #cleanup() and every buffer the context held
+         stayed checked out of its allocator for good — then, a staging buffer per writeBuffer
+         call, which is most of the uniform traffic, every frame, until the process ran out of GPU
+         memory. onFinished never fired either, so a promise already awaiting done never woke and
+         profiling_absorbed hung with it — a recoverable encoding bug turned into an unbounded leak
+         plus a hung frame, with the original error hidden behind the hang.
+
+         The error still propagates: it is the thing that names the misplaced end().
+        */
+        try {
+            const command_buffer = encoder.finish();
+
+            // after finish(), so a command buffer that could not be made sends nothing, and
+            // immediately before the submit, which is what makes the blocks safe to hand back
+            this.#send_uploads(queue);
+
+            queue.submit([command_buffer]);
+        } finally {
+            // 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);
+        }
+
+    }
 }