@woosh/meep-engine 3.56.0 → 3.57.0

package/src/shade/renderer/buffer/table/single/GPUSingleTypeTable.js

@@ -1,401 +1,403 @@
-import { assert } from "../../../../../core/assert.js";
-import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
-import { BitSet } from "../../../../../core/binary/BitSet.js";
-import { platform_compute_endianness } from "../../../../../core/binary/platform_compute_endianness.js";
-import {
-    u32_index_clear,
-    u32_index_count,
-    u32_index_get,
-    u32_index_set,
-} from "../../../../../core/collection/map/u32_index.js";
-import { round_up } from "../../../../../core/math/round_up.js";
-import { KILOBYTE } from "../../../../../core/science/units/memory/KILOBYTE.js";
-import { write_wgsl_type_value } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
-import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
-import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
-import { inspect_gpu_buffer_typed } from "../../inspect_gpu_buffer_typed.js";
-import { GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE } from "../GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE.js";
-
-/**
- * @typedef {import("../../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
- * @typedef {import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
- * @typedef {import("../../../shader/type/WebGPUType.js").WebGPUType} WebGPUType
- */
-
-const UPLOAD_BUFFER_LIMIT = 64 * KILOBYTE;
-const INITIAL_BUFFER_SIZE = 4 * KILOBYTE;
-
-const UPDATE_SETTINGS_STRUCT = WebGPUStruct.from({
-    count: u32,
-    record_size: u32,
-});
-
-const resources = new ShaderResourceSetDescriptor();
-
-// per-dispatch, eight bytes, read-only: immediate data rather than a uniform buffer, which cost a
-// transient buffer, a mapped staging buffer and a copyBufferToBuffer to carry two integers already
-// known on the CPU
-resources.setImmediate('settings', UPDATE_SETTINGS_STRUCT);
-
-resources.createGroup()
-    .addStorageBuffer('upload_buffer', WebGPUArray.from(u32), false)
-    .addStorageBuffer('destination', WebGPUArray.from(u32), true);
-
-const update_shader = ComputeShader.from({
-    label: 'GPUSingleTypeTable.update',
-    body: CodeChunk.from(
-        //language=WGSL
-        `
-@compute @workgroup_size(${GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE},1,1)
-fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
-    let buffer_index = global_id.x;
-    
-    if(buffer_index >= settings.count){
-        return;
-    }
-    
-    let upload_record_offset = buffer_index * ( settings.record_size + 1u );
-    
-    let element_id = upload_buffer[upload_record_offset];
-    
-    let read_offset = upload_record_offset + 1u;
-    let write_offset = element_id * settings.record_size;
-    
-    // copy data
-    for(var i = 0u; i < settings.record_size; i++){
-        // TODO these is a race condition, if the buffer is updated while we are copying, we will overwrite the data
-        destination[write_offset + i] = upload_buffer[read_offset + i];
-    }
-}
-       `
-    ),
-    resources
-});
-
-/**
- * Fully GPU-resident key-value dictionary. The keys are 32-bit unsigned integers.
- * @see {GPUDatabase}
- */
-export class GPUSingleTypeTable {
-
-    /**
-     * Offer the pipeline {@link update} uploads records with, one for every table — see
-     * {@link PipelineEnquiry}.
-     *
-     * @param {PipelineEnquiry} enquiry
-     */
-    static enquirePipelines(enquiry) {
-        enquiry.compute.push(update_shader.pipeline);
-    }
-
-    /**
-     * @type {WebGPUType}
-     * @readonly
-     */
-    type;
-
-    /**
-     * @type {GPUBuffer}
-     * @readonly
-     */
-    buffer
-
-    /**
-     * @private
-     * @type {BinaryBuffer}
-     */
-    upload_buffer = BinaryBuffer.fromEndianness(platform_compute_endianness());
-
-    /**
-     * @private
-     * @type {BitSet}
-     */
-    occupancy = new BitSet();
-
-    /**
-     * Byte offset in {@link upload_buffer} of the record pending for an id, for every id that has
-     * one.
-     *
-     * Every record is consumed by its own thread of a single {@link update} dispatch, so two
-     * records aimed at one id are last-writer-wins across workgroups that have no ordering between
-     * them — the buffer must therefore hold at most one record per id. This was a backwards scan
-     * over the last 256 records, and a window is not a guarantee: a record further back than the
-     * scan reached stayed queued alongside the one that replaced it. The sibling
-     * {@link GPUTypedTable} was found doing exactly that, through a downstream report of corrupted
-     * animation bindings.
-     *
-     * No consumer of this table has reached it — each writes an id once per frame — which is the
-     * only reason it was latent rather than live here.
-     *
-     * `null` until the table takes its first write.
-     *
-     * @private
-     * @type {Uint32Array|null}
-     */
-    #pending_records = null;
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device
-
-    /**
-     *
-     * @return {number} in bytes
-     */
-    get gpu_memory_usage() {
-        return this.buffer.size;
-    }
-
-    /**
-     *
-     * @param {Object} options
-     * @param {GPUDevice} options.device
-     * @param {WebGPUType} options.type
-     * @param {number} [options.initial_size] in bytes
-     */
-    constructor({
-                    device,
-                    type,
-                    initial_size = INITIAL_BUFFER_SIZE
-                }) {
-        assert.defined(device, 'device');
-        assert.defined(type, 'type');
-        assert.isNonNegativeInteger(initial_size, 'initial_size');
-
-        this.#device = device;
-        this.type = type;
-
-        this.buffer = device.createBuffer({
-            size: round_up(Math.max(1, initial_size), this.type.aligned_size),
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
-            mappedAtCreation: false
-        });
-
-    }
-
-    /**
-     *
-     * @param {number} id
-     */
-    remove(id) {
-        assert.isNonNegativeInteger(id, 'id');
-
-        this.occupancy.set(id, false);
-
-        // TODO zero out the slot?
-    }
-
-    /**
-     * Get the next empty slot. Not reserved, use {@link set} to reserve.
-     * @return {number}
-     */
-    next() {
-        return this.occupancy.nextClearBit(0);
-    }
-
-    /**
-     * @template T
-     * @param {number} id
-     * @param {T} value
-     */
-    set(id, value) {
-        assert.isNonNegativeInteger(id, 'id');
-
-        this.occupancy.set(id, true);
-
-        const upload_buffer = this.upload_buffer;
-
-        // records are laid out at fixed strides: [u32 id, value], rounded up
-        const stride = this.type.aligned_size + u32.size;
-        const tail = upload_buffer.position;
-
-        // Dedupe against everything queued, not a window of it: each record is consumed by its own
-        // thread in a single update dispatch, so two records for the same id would race
-        // (last-writer-wins, non-deterministic). Overwrite the previous value in place.
-        const pending_record = this.#pending_record_offset(id);
-
-        if (pending_record >= 0) {
-            upload_buffer.position = pending_record + u32.size;
-
-            write_wgsl_type_value(value, upload_buffer, this.type);
-
-            upload_buffer.position = tail;
-
-            return;
-        }
-
-        // Reserve the whole stride up front. The writes below only reach the last field,
-        // so on a type that pads out to `aligned_size` they would leave the buffer short
-        // of the tail rounded up to below — and that tail is what `update` copies out to,
-        // past the end of `data`.
-        upload_buffer.ensureCapacity(tail + stride);
-
-        upload_buffer.writeUint32(id);
-        write_wgsl_type_value(value, upload_buffer, this.type);
-
-        upload_buffer.position = round_up(upload_buffer.position, stride);
-
-        this.#pending_records = u32_index_set(this.#pending_records, id, tail);
-    }
-
-    /**
-     * Byte offset of the record already pending for an id, or -1. One record per id is the
-     * invariant that keeps the update dispatch race-free — see {@link #pending_records}.
-     *
-     * Also where a stream dispatched since the last write gets noticed: {@link update} rewinds
-     * {@link upload_buffer} by moving its position back to zero and tells nobody, so the index can
-     * outlive the records it points at. {@link set} consults this before appending, which is what
-     * the staleness check rests on.
-     *
-     * @private
-     * @param {number} id
-     * @returns {number} byte offset of the pending record, or -1
-     */
-    #pending_record_offset(id) {
-        const pending = this.#pending_records;
-
-        if (pending === null || u32_index_count(pending) === 0) {
-            return -1;
-        }
-
-        if (this.upload_buffer.position === 0) {
-            // the stream was dispatched and rewound since these were recorded
-            u32_index_clear(pending);
-
-            return -1;
-        }
-
-        return u32_index_get(pending, id);
-    }
-
-    /**
-     * @template T
-     * @param {number} id
-     * @returns {T}
-     */
-    async get(id) {
-        assert.isNonNegativeInteger(id, 'id');
-
-        const type = this.type;
-
-        const values = await inspect_gpu_buffer_typed({
-            buffer: this.buffer,
-            device: this.#device,
-            type,
-            offset: id * type.aligned_size,
-            count: 1
-        });
-
-        return values[0];
-    }
-
-    /**
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {number} count
-     */
-    #update_capacity(encoder, count) {
-        const existing_buffer = this.buffer;
-        const alignment = this.type.aligned_size;
-        const needed_size_bytes = count * alignment;
-
-        if (existing_buffer.size >= needed_size_bytes) {
-            // TODO shrink buffer when too small
-            return;
-        }
-
-        const GROW_FACTOR = 1.25;
-
-        const new_size = Math.max(
-            needed_size_bytes,
-            round_up(existing_buffer.size * GROW_FACTOR, alignment)
-        );
-
-        const new_buffer = this.#device.createBuffer({
-            size: new_size,
-            usage: existing_buffer.usage,
-            mappedAtCreation: false
-        });
-
-        encoder.copyBufferToBuffer(existing_buffer, 0, new_buffer, 0, existing_buffer.size);
-
-        encoder.onFinished.add(() => {
-            existing_buffer.destroy();
-        });
-
-        this.buffer = new_buffer;
-    }
-
-    /**
-     *
-     * @param {ShadeGPUCommandContext} command_ctx
-     */
-    update(command_ctx) {
-        assert.defined(command_ctx, 'command_ctx');
-        assert.equal(command_ctx.isGPUCommandContext, true, 'command_ctx.isGPUCommandContext !== true');
-
-
-        if (this.upload_buffer.position === 0) {
-            // nothing to do
-            return;
-        }
-
-        // resize the buffer if necessary.
-        const min_capacity = this.occupancy.size();
-        this.#update_capacity(command_ctx, min_capacity);
-
-        // execute copy shader.
-        const count = this.upload_buffer.position / (this.type.aligned_size + u32.size);
-
-        assert.isNonNegativeInteger(count, 'count');
-
-        // immediate data — a plain value written straight into the pass, not a buffer
-        const settings = {
-            count,
-            record_size: this.type.aligned_size / u32.size,
-        };
-
-        const upload_buffer = command_ctx.allocateTransientBufferAndLoad(
-            this.upload_buffer.data,
-            GPUBufferUsage.STORAGE,
-            0,
-            this.upload_buffer.position
-        );
-
-        update_shader.dispatchThreads({
-            encoder: command_ctx,
-            thread_count_x: count,
-            bindings: {
-                settings,
-                upload_buffer,
-                destination: this.buffer,
-            }
-        })
-
-        // drop upload buffer
-        this.upload_buffer.position = 0;
-        if (this.upload_buffer.capacity > UPLOAD_BUFFER_LIMIT) {
-            // release memory held by upload buffer
-            this.upload_buffer.setCapacity(UPLOAD_BUFFER_LIMIT);
-        }
-    }
-
-    async debug_dump() {
-        return inspect_gpu_buffer_typed({
-            buffer: this.buffer,
-            device: this.#device,
-            type: this.type,
-            offset: 0,
-            count: this.occupancy.size(),
-        });
-    }
-
-    destroy() {
-        this.buffer.destroy();
-    }
-}
+import { assert } from "../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { BitSet } from "../../../../../core/binary/BitSet.js";
+import { platform_compute_endianness } from "../../../../../core/binary/platform_compute_endianness.js";
+import {
+    u32_index_clear,
+    u32_index_count,
+    u32_index_get,
+    u32_index_set,
+} from "../../../../../core/collection/map/u32_index.js";
+import { round_up } from "../../../../../core/math/round_up.js";
+import { KILOBYTE } from "../../../../../core/science/units/memory/KILOBYTE.js";
+import { write_wgsl_type_value } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { inspect_gpu_buffer_typed } from "../../inspect_gpu_buffer_typed.js";
+import { GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE } from "../GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE.js";
+
+/**
+ * @typedef {import("../../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ * @typedef {import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("../../../shader/type/WebGPUType.js").WebGPUType} WebGPUType
+ */
+
+const UPLOAD_BUFFER_LIMIT = 64 * KILOBYTE;
+const INITIAL_BUFFER_SIZE = 4 * KILOBYTE;
+
+const UPDATE_SETTINGS_STRUCT = WebGPUStruct.from({
+    count: u32,
+    record_size: u32,
+});
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, eight bytes, read-only: immediate data rather than a uniform buffer, which cost a
+// transient buffer, a mapped staging buffer and a copyBufferToBuffer to carry two integers already
+// known on the CPU
+resources.setImmediate('settings', UPDATE_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer('upload_buffer', WebGPUArray.from(u32), false)
+    .addStorageBuffer('destination', WebGPUArray.from(u32), true);
+
+const update_shader = ComputeShader.from({
+    label: 'GPUSingleTypeTable.update',
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE},1,1)
+fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
+    let buffer_index = global_id.x;
+    
+    if(buffer_index >= settings.count){
+        return;
+    }
+    
+    let upload_record_offset = buffer_index * ( settings.record_size + 1u );
+    
+    let element_id = upload_buffer[upload_record_offset];
+    
+    let read_offset = upload_record_offset + 1u;
+    let write_offset = element_id * settings.record_size;
+    
+    // copy data
+    for(var i = 0u; i < settings.record_size; i++){
+        // TODO these is a race condition, if the buffer is updated while we are copying, we will overwrite the data
+        destination[write_offset + i] = upload_buffer[read_offset + i];
+    }
+}
+       `
+    ),
+    resources
+});
+
+/**
+ * Fully GPU-resident key-value dictionary. The keys are 32-bit unsigned integers.
+ * @see {GPUDatabase}
+ */
+export class GPUSingleTypeTable {
+
+    /**
+     * Offer the pipeline {@link update} uploads records with, one for every table — see
+     * {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        enquiry.compute.push(update_shader.pipeline);
+    }
+
+    /**
+     * @type {WebGPUType}
+     * @readonly
+     */
+    type;
+
+    /**
+     * @type {GPUBuffer}
+     * @readonly
+     */
+    buffer
+
+    /**
+     * @private
+     * @type {BinaryBuffer}
+     */
+    upload_buffer = BinaryBuffer.fromEndianness(platform_compute_endianness());
+
+    /**
+     * @private
+     * @type {BitSet}
+     */
+    occupancy = new BitSet();
+
+    /**
+     * Byte offset in {@link upload_buffer} of the record pending for an id, for every id that has
+     * one.
+     *
+     * Every record is consumed by its own thread of a single {@link update} dispatch, so two
+     * records aimed at one id are last-writer-wins across workgroups that have no ordering between
+     * them — the buffer must therefore hold at most one record per id. This was a backwards scan
+     * over the last 256 records, and a window is not a guarantee: a record further back than the
+     * scan reached stayed queued alongside the one that replaced it. The sibling
+     * {@link GPUTypedTable} was found doing exactly that, through a downstream report of corrupted
+     * animation bindings.
+     *
+     * No consumer of this table has reached it — each writes an id once per frame — which is the
+     * only reason it was latent rather than live here.
+     *
+     * `null` until the table takes its first write.
+     *
+     * @private
+     * @type {Uint32Array|null}
+     */
+    #pending_records = null;
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device
+
+    /**
+     *
+     * @return {number} in bytes
+     */
+    get gpu_memory_usage() {
+        return this.buffer.size;
+    }
+
+    /**
+     *
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {WebGPUType} options.type
+     * @param {number} [options.initial_size] in bytes
+     */
+    constructor({
+                    device,
+                    type,
+                    initial_size = INITIAL_BUFFER_SIZE
+                }) {
+        assert.defined(device, 'device');
+        assert.defined(type, 'type');
+        assert.isNonNegativeInteger(initial_size, 'initial_size');
+
+        this.#device = device;
+        this.type = type;
+
+        this.buffer = device.createBuffer({
+            size: round_up(Math.max(1, initial_size), this.type.aligned_size),
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+            mappedAtCreation: false
+        });
+
+    }
+
+    /**
+     *
+     * @param {number} id
+     */
+    remove(id) {
+        assert.isNonNegativeInteger(id, 'id');
+
+        this.occupancy.set(id, false);
+
+        // TODO zero out the slot?
+    }
+
+    /**
+     * Get the next empty slot. Not reserved, use {@link set} to reserve.
+     * @return {number}
+     */
+    next() {
+        return this.occupancy.nextClearBit(0);
+    }
+
+    /**
+     * @template T
+     * @param {number} id
+     * @param {T} value
+     */
+    set(id, value) {
+        assert.isNonNegativeInteger(id, 'id');
+
+        this.occupancy.set(id, true);
+
+        const upload_buffer = this.upload_buffer;
+
+        // records are laid out at fixed strides: [u32 id, value], rounded up
+        const stride = this.type.aligned_size + u32.size;
+        const tail = upload_buffer.position;
+
+        // Dedupe against everything queued, not a window of it: each record is consumed by its own
+        // thread in a single update dispatch, so two records for the same id would race
+        // (last-writer-wins, non-deterministic). Overwrite the previous value in place.
+        const pending_record = this.#pending_record_offset(id);
+
+        if (pending_record >= 0) {
+            upload_buffer.position = pending_record + u32.size;
+            new Uint8Array(upload_buffer.data, pending_record + u32.size, this.type.aligned_size).fill(0);
+
+            write_wgsl_type_value(value, upload_buffer, this.type);
+
+            upload_buffer.position = tail;
+
+            return;
+        }
+
+        // Reserve the whole stride up front. The writes below only reach the last field,
+        // so on a type that pads out to `aligned_size` they would leave the buffer short
+        // of the tail rounded up to below — and that tail is what `update` copies out to,
+        // past the end of `data`.
+        upload_buffer.ensureCapacity(tail + stride);
+
+        upload_buffer.writeUint32(id);
+        new Uint8Array(upload_buffer.data, tail + u32.size, this.type.aligned_size).fill(0);
+        write_wgsl_type_value(value, upload_buffer, this.type);
+
+        upload_buffer.position = tail + stride;
+
+        this.#pending_records = u32_index_set(this.#pending_records, id, tail);
+    }
+
+    /**
+     * Byte offset of the record already pending for an id, or -1. One record per id is the
+     * invariant that keeps the update dispatch race-free — see {@link #pending_records}.
+     *
+     * Also where a stream dispatched since the last write gets noticed: {@link update} rewinds
+     * {@link upload_buffer} by moving its position back to zero and tells nobody, so the index can
+     * outlive the records it points at. {@link set} consults this before appending, which is what
+     * the staleness check rests on.
+     *
+     * @private
+     * @param {number} id
+     * @returns {number} byte offset of the pending record, or -1
+     */
+    #pending_record_offset(id) {
+        const pending = this.#pending_records;
+
+        if (pending === null || u32_index_count(pending) === 0) {
+            return -1;
+        }
+
+        if (this.upload_buffer.position === 0) {
+            // the stream was dispatched and rewound since these were recorded
+            u32_index_clear(pending);
+
+            return -1;
+        }
+
+        return u32_index_get(pending, id);
+    }
+
+    /**
+     * @template T
+     * @param {number} id
+     * @returns {T}
+     */
+    async get(id) {
+        assert.isNonNegativeInteger(id, 'id');
+
+        const type = this.type;
+
+        const values = await inspect_gpu_buffer_typed({
+            buffer: this.buffer,
+            device: this.#device,
+            type,
+            offset: id * type.aligned_size,
+            count: 1
+        });
+
+        return values[0];
+    }
+
+    /**
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {number} count
+     */
+    #update_capacity(encoder, count) {
+        const existing_buffer = this.buffer;
+        const alignment = this.type.aligned_size;
+        const needed_size_bytes = count * alignment;
+
+        if (existing_buffer.size >= needed_size_bytes) {
+            // TODO shrink buffer when too small
+            return;
+        }
+
+        const GROW_FACTOR = 1.25;
+
+        const new_size = Math.max(
+            needed_size_bytes,
+            round_up(existing_buffer.size * GROW_FACTOR, alignment)
+        );
+
+        const new_buffer = this.#device.createBuffer({
+            size: new_size,
+            usage: existing_buffer.usage,
+            mappedAtCreation: false
+        });
+
+        encoder.copyBufferToBuffer(existing_buffer, 0, new_buffer, 0, existing_buffer.size);
+
+        encoder.onFinished.add(() => {
+            existing_buffer.destroy();
+        });
+
+        this.buffer = new_buffer;
+    }
+
+    /**
+     *
+     * @param {ShadeGPUCommandContext} command_ctx
+     */
+    update(command_ctx) {
+        assert.defined(command_ctx, 'command_ctx');
+        assert.equal(command_ctx.isGPUCommandContext, true, 'command_ctx.isGPUCommandContext !== true');
+
+
+        if (this.upload_buffer.position === 0) {
+            // nothing to do
+            return;
+        }
+
+        // resize the buffer if necessary.
+        const min_capacity = this.occupancy.size();
+        this.#update_capacity(command_ctx, min_capacity);
+
+        // execute copy shader.
+        const count = this.upload_buffer.position / (this.type.aligned_size + u32.size);
+
+        assert.isNonNegativeInteger(count, 'count');
+
+        // immediate data — a plain value written straight into the pass, not a buffer
+        const settings = {
+            count,
+            record_size: this.type.aligned_size / u32.size,
+        };
+
+        const upload_buffer = command_ctx.allocateTransientBufferAndLoad(
+            this.upload_buffer.data,
+            GPUBufferUsage.STORAGE,
+            0,
+            this.upload_buffer.position
+        );
+
+        update_shader.dispatchThreads({
+            encoder: command_ctx,
+            thread_count_x: count,
+            bindings: {
+                settings,
+                upload_buffer,
+                destination: this.buffer,
+            }
+        })
+
+        // drop upload buffer
+        this.upload_buffer.position = 0;
+        if (this.upload_buffer.capacity > UPLOAD_BUFFER_LIMIT) {
+            // release memory held by upload buffer
+            this.upload_buffer.setCapacity(UPLOAD_BUFFER_LIMIT);
+        }
+    }
+
+    async debug_dump() {
+        return inspect_gpu_buffer_typed({
+            buffer: this.buffer,
+            device: this.#device,
+            type: this.type,
+            offset: 0,
+            count: this.occupancy.size(),
+        });
+    }
+
+    destroy() {
+        this.buffer.destroy();
+    }
+}