@woosh/meep-engine 3.56.0 → 3.57.0

package/src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js

@@ -1,675 +1,690 @@
-import { assert } from "../../../../core/assert.js";
-import { round_up } from "../../../../core/math/round_up.js";
-import LineBuilder from "../../../../core/codegen/LineBuilder.js";
-import { array_push_if_unique } from "../../../../core/collection/array/array_push_if_unique.js";
-import { objectKeyByValue } from "../../../../core/model/object/objectKeyByValue.js";
-import { PipelineLayoutDescriptor } from "../../../descriptor/pipeline/PipelineLayoutDescriptor.js";
-import {
-    wgsl_texture_declaration_by_sample_type
-} from "../../texture/format/wgsl_texture_declaration_by_sample_type.js";
-import { CodeChunk } from "../compiler/CodeChunk.js";
-import { parse_wgsl_type } from "../type/parse_wgsl_type.js";
-import { type_has_arrays } from "../type/type_has_arrays.js";
-import { type_has_atomics } from "../type/type_has_atomics.js";
-import { WebGPUStruct } from "../type/WebGPUStruct.js";
-import { write_wgsl_type_value } from "../type/serde/write_gpu_typed_buffer.js";
-import { IMMEDIATE_ADDRESS_SPACE_EXTENSION, IMMEDIATE_SIZE_FLOOR } from "./IMMEDIATE_DATA.js";
-import { ResourceType } from "./ResourceType.js";
-import { ShaderResourceGroupDescriptor } from "./ShaderResourceGroupDescriptor.js";
-
-/**
- * @typedef {import("../../../../core/binary/BinaryBuffer.js").BinaryBuffer} BinaryBuffer
- * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
- * @typedef {import("../type/WebGPUType.js").WebGPUType} WebGPUType
- */
-
-/**
- *
- * @param {TextureBindingLayout} member
- * @returns {string}
- */
-function gen_type_texture(member) {
-    if (member.sampleType === "depth") {
-
-        if (member.viewDimension !== "2d") {
-            throw new Error('Must be 2d');
-        }
-
-        // special case
-        return "texture_depth_2d";
-    }
-
-    /**
-     * @type {string}
-     */
-    let proper_type;
-
-    switch (member.viewDimension) {
-        case "1d":
-            proper_type = "texture_1d";
-            break;
-        case "2d":
-            proper_type = "texture_2d";
-            break;
-        case "3d":
-            proper_type = "texture_3d";
-            break;
-        case "2d-array":
-            proper_type = "texture_2d_array";
-            break;
-        default:
-            throw new Error(`Unsupported viewDimension '${member.viewDimension}'`);
-    }
-
-    proper_type += "<";
-
-    proper_type += wgsl_texture_declaration_by_sample_type(member.sampleType);
-
-    proper_type += ">";
-
-    return proper_type;
-}
-
-/**
- *
- * @param {StorageTextureBindingLayout} member
- * @returns {string}
- */
-function gen_type_storage_texture(member) {
-    /**
-     * @type {string}
-     */
-    let proper_type;
-
-    if (member.viewDimension === "2d") {
-        proper_type = "texture_storage_2d"
-    } else if (member.viewDimension === "2d-array") {
-        proper_type = "texture_storage_2d_array";
-    } else if (member.viewDimension === "3d") {
-        proper_type = "texture_storage_3d";
-    } else {
-        throw new Error(`Unsupported viewDimension '${member.viewDimension}'`);
-    }
-
-    /**
-     *
-     * @param {GPUStorageTextureAccess} access
-     */
-    function gen_access(access) {
-        switch (access) {
-            case "write-only":
-                return "write";
-            case "read-write":
-                // TODO validate
-                return "read_write";
-            case "read-only":
-                // TODO valida
-                return "read";
-            default:
-                throw new Error(`Unsupported access ${access}`);
-        }
-    }
-
-    proper_type += `< ${member.format}, ${gen_access(member.access)} >`
-
-    return proper_type;
-}
-
-/**
- *
- * @param {SamplerBindingLayout} member
- * @returns {string}
- */
-function gen_type_sampler(member) {
-    // see https://www.w3.org/TR/WGSL/#sampler-type
-
-    // WGSL has no "non-filtering" sampler type; filtering is a bind-group-layout property, so
-    // both "filtering" and "non-filtering" declare a plain `sampler`
-    if (member.type === "filtering" || member.type === "non-filtering") {
-        return "sampler";
-    } else if (member.type === "comparison") {
-        return "sampler_comparison";
-    } else {
-        throw new Error(`Unsupported sampler type '${member.type}'`);
-    }
-
-}
-
-export class ShaderResourceSetDescriptor {
-
-    /**
-     *
-     * @type {ShaderResourceGroupDescriptor[]}
-     */
-    #groups = [];
-
-    /**
-     * The shader's immediate data declaration, or undefined when it has none.
-     *
-     * Deliberately not a member of any {@link ShaderResourceGroupDescriptor}: immediate data has no
-     * `@group` and no `@binding`, and WGSL is explicit that it is part of a shader's *interface*
-     * without being part of its *resource interface*. Modelling it as a group member would give it
-     * a binding index that does not exist.
-     *
-     * @type {{name: string, type: WebGPUType}|undefined}
-     */
-    #immediate = undefined;
-
-    /**
-     * @returns {{name: string, type: WebGPUType}|undefined}
-     */
-    get immediate() {
-        return this.#immediate;
-    }
-
-    /**
-     * Bytes of immediate data this shader reads, rounded up to the 4-byte granularity WebGPU
-     * requires of `immediateSize`. Zero when there is no immediate declaration.
-     *
-     * @returns {number}
-     */
-    get immediateSize() {
-        if (this.#immediate === undefined) {
-            return 0;
-        }
-
-        return round_up(this.#immediate.type.size, 4);
-    }
-
-    /**
-     * Declare this shader's immediate data — the WGSL `immediate` address space, which reaches the
-     * GPU through `setImmediates` on the pass encoder rather than through a bind group.
-     *
-     * Every restriction below is checked here rather than left to `createShaderModule`, because the
-     * device-side failure is a shader-creation error whose message names neither this descriptor nor
-     * the shader it belongs to.
-     *
-     * @param {string} name
-     * @param {WebGPUType|string} _type must be host-shareable, constructible, array-free, and fit
-     *        the device's `maxImmediateSize`
-     * @returns {this}
-     */
-    setImmediate(name, _type) {
-        assert.isString(name, 'name');
-        assert.defined(_type, 'type');
-
-        if (this.#immediate !== undefined) {
-            throw new Error(
-                `Immediate data is already declared as '${this.#immediate.name}'. WGSL allows at most one immediate variable per entry point, so '${name}' would have to replace it.`
-            );
-        }
-
-        let type = _type;
-
-        if (typeof type === "string") {
-            type = parse_wgsl_type(type);
-        } else {
-            assert.equal(type.isWebGPUType, true, 'type.isWebGPUType !== true');
-        }
-
-        if (type.runtime_sized) {
-            throw new Error(`Immediate data '${name}' must have a size known ahead of time, and '${type}' is runtime-sized`);
-        }
-
-        if (type_has_arrays(type)) {
-            throw new Error(
-                `Immediate data '${name}' may not contain an array: the immediate address space excludes arrays and structures with array members. Keep the array in a storage buffer and pass an index.`
-            );
-        }
-
-        // https://www.w3.org/TR/WGSL/#atomic-type — an immediate is immutable, so an atomic in one
-        // could never be operated on anyway
-        assert.equal(type_has_atomics(type), false, 'atomics are not allowed in immediate data');
-
-        const size = round_up(type.size, 4);
-
-        if (size > IMMEDIATE_SIZE_FLOOR) {
-            throw new Error(
-                `Immediate data '${name}' is ${size} bytes, over the ${IMMEDIATE_SIZE_FLOOR}-byte maxImmediateSize that every WebGPU device is guaranteed to offer. Move the bulk of it to a uniform buffer.`
-            );
-        }
-
-        // The top-level member names, kept so that `writeImmediate` can tell a value of this type
-        // from something that merely happens to be an object. `undefined` for a scalar, vector or
-        // matrix immediate, which has no members to name.
-        const field_names = type instanceof WebGPUStruct
-            ? type.fields.map(field => field.name)
-            : undefined;
-
-        this.#immediate = { name, type, field_names };
-
-        return this;
-    }
-
-    /**
-     * Do not modify directly
-     * @returns {ShaderResourceGroupDescriptor[]}
-     */
-    get groups() {
-        return this.#groups;
-    }
-
-
-    /**
-     *
-     * @return {boolean}
-     */
-    get isShaderResourceSetDescriptor() {
-        return true;
-    }
-
-    #getEmptySlot() {
-        for (let i = 0; i < 1024; i++) {
-            if (this.#groups[i] === undefined) {
-                return i;
-            }
-        }
-
-        throw new Error(`All slots are used up`);
-    }
-
-
-    /**
-     *
-     * @param {string} name
-     * @returns {ShaderResourceDescriptor}
-     */
-    /**
-     * Whether `name` is this shader's immediate data.
-     *
-     * Immediate data is deliberately absent from {@link getResourceByName}: it is not a bound
-     * resource and has no binding layout, so anything walking the resource interface should not see
-     * it. The graph helpers still need to recognise the name, because an immediate value travels to
-     * the encoder as a plain value rather than as a graph resource — and a `u32` immediate is a
-     * number, which those helpers would otherwise read as a graph resource id.
-     *
-     * @param {string} name
-     * @returns {boolean}
-     */
-    isImmediateName(name) {
-        return this.#immediate !== undefined && this.#immediate.name === name;
-    }
-
-    getResourceByName(name) {
-
-        for (const group of this.#groups) {
-
-            const resource = group.get(name);
-
-            if (resource !== undefined) {
-                return resource;
-            }
-
-        }
-
-    }
-
-    /**
-     *
-     * @param {Object} [options]
-     * @param {number} [options.index]
-     * @param {string} [options.label]
-     * @returns {ShaderResourceGroupDescriptor}
-     */
-    createGroup({
-                    index = this.#getEmptySlot(),
-                    label = "",
-                } = {}) {
-
-        assert.isNonNegativeInteger(index, 'index');
-        assert.lessThan(index, 1024, 'Too high');
-        assert.isString(label, 'label');
-
-        if (this.#groups[index] !== undefined) {
-            throw new Error(`Group ${index} already exists`);
-        }
-
-        const r = new ShaderResourceGroupDescriptor();
-
-        r.label = label;
-
-        this.#groups[index] = r;
-
-        return r;
-    }
-
-    /**
-     *
-     * @param {ShaderResourceGroupDescriptor} group
-     * @returns {boolean}
-     */
-    addGroup(group) {
-        // TODO check for name collisions
-
-        const added = array_push_if_unique(this.#groups, group);
-
-        return added;
-    }
-
-    /**
-     *
-     * @param {GPUShaderStage|number} stage
-     */
-    addVisibility(stage) {
-        const groups = this.#groups;
-        const group_count = groups.length;
-
-        for (let i = 0; i < group_count; i++) {
-            const group = groups[i];
-
-            group.addVisibility(stage);
-        }
-    }
-
-    /**
-     * @returns {PipelineLayoutDescriptor}
-     */
-    generatePipelineLayoutDescriptor() {
-        const r = new PipelineLayoutDescriptor();
-
-        const groups = this.#groups;
-        const group_count = groups.length;
-        for (let i = 0; i < group_count; i++) {
-
-            const group = groups[i];
-
-            r.bindGroupLayouts[i] = group.generateBindGroupLayoutDescriptor();
-        }
-
-        r.immediateSize = this.immediateSize;
-
-        return r;
-    }
-
-    /**
-     *
-     * @return {[][]}
-     */
-    generateBindingsArray() {
-        const binding_groups = [];
-
-        const groups = this.#groups;
-
-        for (let group_index = 0; group_index < groups.length; group_index++) {
-            const group = groups[group_index];
-
-            binding_groups[group_index] = group.resources.map(r => r.member_descriptor);
-        }
-
-        return binding_groups;
-    }
-
-    /**
-     *
-     * @param {GPUShaderStage|number} stage
-     * @returns {PipelineLayoutDescriptor}
-     */
-    generatePipelineLayout(stage) {
-        assert.defined(stage, 'stage');
-
-        return PipelineLayoutDescriptor.forStage(stage, this.generateBindingsArray(), this.immediateSize);
-    }
-
-    /**
-     *
-     * @param {Object} map
-     * @param {ShadeGPUCommandContext} [encoder] optional, allows resolving more defaults
-     * @returns {GPUBindingResource[][]}
-     */
-    generateBindings(map, encoder) {
-
-        const groups = this.#groups;
-        const group_count = groups.length;
-
-        const output = [];
-
-        for (let i = 0; i < group_count; i++) {
-            const group = groups[i];
-
-            output[i] = group.generateBindings(map, encoder);
-        }
-
-        return output;
-    }
-
-    /**
-     * Generates WGSL code declaring bindings
-     * @return {CodeChunk}
-     */
-    generateCodeChunk() {
-        const builder = new LineBuilder();
-
-        /**
-         *
-         * @type {Set<CodeChunk>}
-         */
-        const dependencies = new Set();
-
-        const groups = this.#groups;
-
-        const immediate = this.#immediate;
-
-        if (immediate !== undefined) {
-            const immediate_type = immediate.type;
-
-            if (immediate_type.requires_declaration) {
-                dependencies.add(immediate_type.declaration_chunk);
-            }
-
-            // no @group, no @binding — this is the one module-scope variable that has neither
-            builder.add(`var<immediate> ${immediate.name} : ${immediate_type.wgsl_ref};`);
-        }
-
-        for (let group_index = 0; group_index < groups.length; group_index++) {
-            const group = groups[group_index];
-
-
-            const resources = group.resources;
-            const resource_count = resources.length;
-
-
-            for (let i = 0; i < resource_count; i++) {
-                const resource = resources[i];
-
-                const member = resource.member_descriptor;
-                const resource_type = resource.type;
-
-                let declaration = `@group(${group_index}) @binding(${resource.binding_index}) var`
-
-                let proper_type;
-
-                if (resource_type === ResourceType.Buffer) {
-
-                    const gpu_type = resource.buffer_type;
-
-                    if (gpu_type.requires_declaration) {
-                        dependencies.add(gpu_type.declaration_chunk);
-                    }
-
-                    const layout_type = member.type;
-
-                    if (layout_type === "uniform") {
-                        declaration += "<uniform>"
-                    } else if (layout_type === "storage") {
-                        declaration += "<storage, read_write>"
-                    } else if (layout_type === "read-only-storage") {
-                        declaration += "<storage, read>"
-                    } else {
-                        throw new Error(`Unsupported layout type '${layout_type}'`);
-                    }
-
-                    proper_type = gpu_type.wgsl_ref;
-
-                } else if (resource_type === ResourceType.Texture) {
-                    proper_type = gen_type_texture(member);
-
-                } else if (resource_type === ResourceType.StorageTexture) {
-
-                    proper_type = gen_type_storage_texture(member);
-
-                } else if (resource_type === ResourceType.Sampler) {
-
-                    proper_type = gen_type_sampler(member);
-
-                } else {
-                    throw new Error(`Unsupported type ${objectKeyByValue(ResourceType, resource_type)}(=${resource_type})`)
-                }
-
-                declaration += " ";
-                declaration += resource.name;
-                declaration += " : ";
-
-
-                declaration += proper_type;
-
-                declaration += ";" // terminate the line
-
-                builder.add(declaration);
-            }
-
-        }
-
-        const chunk = CodeChunk.from(builder.build(), Array.from(dependencies));
-
-        if (immediate !== undefined) {
-            // `requires`, not `enable` — see CodeChunk#addLanguageExtension
-            chunk.addLanguageExtension(IMMEDIATE_ADDRESS_SPACE_EXTENSION);
-        }
-
-        return chunk;
-
-    }
-
-    /**
-     * Serialise this shader's immediate data into `buffer` at its current `position`, advancing
-     * `position` past what was written.
-     *
-     * **Allocates nothing.** That is the point of taking a caller-owned {@link BinaryBuffer} rather
-     * than returning bytes: `write_gpu_typed_buffer` would rebind a scratch buffer with a fresh
-     * `DataView` and `Uint8Array` on every call, which is two allocations per dispatch for a value
-     * that is often four bytes. {@link write_wgsl_type_value} takes the buffer directly and does not.
-     *
-     * The caller owns `position` because the caller owns the buffer — this only ever appends at the
-     * cursor it is handed.
-     *
-     * @param {Object} map the same binding map {@link generateBindings} reads
-     * @param {BinaryBuffer} buffer must already be set to the platform's endianness
-     * @returns {boolean} false when this shader declares no immediate data, and nothing was written
-     */
-    writeImmediate(map, buffer) {
-        const immediate = this.#immediate;
-
-        if (immediate === undefined) {
-            return false;
-        }
-
-        const value = map[immediate.name];
-
-        if (value === undefined || value === null) {
-            throw new Error(
-                `Value for immediate data '${immediate.name}' is missing from the input. Unlike a buffer binding it has no default: WebGPU refuses a draw whose immediate slots were never written.`
-            );
-        }
-
-        // Refuse a value of the wrong shape rather than serialise what it does not contain.
-        //
-        // The whole declared range travels every dispatch, and the zeroes this method clears it to are
-        // indistinguishable from deliberate ones: every slot ends up *set*, so WebGPU's immediate
-        // validation — and the software device's copy of it — has nothing to report. A wrong-shaped
-        // value therefore reaches the shader as zeroes, silently, and the only symptom is wrong
-        // output. That is what a call site left behind by the uniform -> immediate migration does: it
-        // keeps handing over the transient GPUBuffer the uniform needed, `generateBindings` ignores
-        // the extra key so the buffer is never bound, and nothing on a GPUBuffer matches the type.
-        //
-        // A value that names *some* of the members is left alone. Structs carry explicit padding
-        // members the CPU side has no value for, and skipping absent fields is load-bearing anyway
-        // (GPUTypedTable#set_range writes one member of a record through the same serialiser). Only a
-        // value that could not have populated the type at all is an unambiguous mistake.
-        const field_names = immediate.field_names;
-
-        if (field_names === undefined) {
-            // Scalar, vector or matrix: the serialiser reads the value as a number or indexes it.
-            const usable = typeof value === "number"
-                || typeof value === "boolean"
-                || typeof value[0] === "number";
-
-            if (!usable) {
-                throw new Error(
-                    `Immediate data '${immediate.name}' of type '${immediate.type}' was given a value the`
-                    + ` serialiser cannot read as a number: '${value}'. An immediate takes the plain value,`
-                    + ` not something bindable — a GPUBuffer is what a *uniform* binding wants, and one`
-                    + ` passed here is ignored by generateBindings and would serialise as zeroes.`
-                );
-            }
-        } else if (!value_names_a_member(value, field_names)) {
-            // Note: no `${immediate.type}` in the message. Interpolating a struct type runs its whole
-            // WGSL declaration through the code generator, and the member list is the actionable half
-            // of that anyway.
-            throw new Error(
-                `Immediate data '${immediate.name}' was given a value naming none of its members`
-                + ` (${field_names.join(', ')}), so the dispatch would have read zeroes. An immediate`
-                + ` takes the plain value — '{ ${field_names[0]}: ... }' — not`
-                + ` something bindable: a GPUBuffer is what a *uniform* binding wants, and one passed`
-                + ` here is ignored by generateBindings and serialises to nothing.`
-            );
-        }
-
-        const start = buffer.position;
-        const size = this.immediateSize;
-
-        buffer.ensureCapacity(start + size);
-
-        // Clear the whole declared range up front, rather than filling in from wherever the
-        // serialiser's cursor stopped.
-        //
-        // Two reasons, and the second is the one that bites. The first: the serialiser stops after the
-        // final member, so a struct with trailing padding — say `{vec4f, u32}`, 20 bytes written of a
-        // 32-byte type — leaves a tail. That tail is padding, WebGPU's AccessibleSlots excludes
-        // padding, and a short write would in fact validate; it would also make the bytes handed to
-        // `setImmediates` shorter than the `immediateSize` the pipeline layout declares, true-but-subtle
-        // in a way that only holds as long as nobody changes how either number is derived.
-        //
-        // The second: this buffer is one scratch region reused by every dispatch of a context, and it
-        // is only ever written over, never cleared. A member the value did not name is skipped, and a
-        // skipped member before the final one is not in the tail — filling from the cursor left it
-        // holding the bytes the *previous* dispatch put at that offset. A partial value is legal (see
-        // above), so that made one dispatch's immediate data a function of the one before it. Clearing
-        // first closes the holes and the tail together, and costs at most 64 bytes of memset.
-        buffer.raw_bytes.fill(0, start, start + size);
-
-        write_wgsl_type_value(value, buffer, immediate.type);
-
-        buffer.position = start + size;
-
-        return true;
-    }
-}
-
-/**
- * Whether `value` carries at least one of `field_names`.
- *
- * A plain loop, and a free function rather than a closure over `value`, because
- * {@link ShaderResourceSetDescriptor#writeImmediate} runs once per dispatch and allocates nothing.
- *
- * @param {Object} value
- * @param {string[]} field_names
- * @returns {boolean}
- */
-function value_names_a_member(value, field_names) {
-    const count = field_names.length;
-
-    for (let i = 0; i < count; i++) {
-        if (value[field_names[i]] !== undefined) {
-            return true;
-        }
-    }
-
-    return false;
-}
-
-/**
- * Special immutable empty set
- * @readonly
- * @type {Readonly<ShaderResourceSetDescriptor>}
- */
-ShaderResourceSetDescriptor.EMPTY = Object.freeze(new ShaderResourceSetDescriptor());
+import { assert } from "../../../../core/assert.js";
+import { round_up } from "../../../../core/math/round_up.js";
+import LineBuilder from "../../../../core/codegen/LineBuilder.js";
+import { array_push_if_unique } from "../../../../core/collection/array/array_push_if_unique.js";
+import { objectKeyByValue } from "../../../../core/model/object/objectKeyByValue.js";
+import { PipelineLayoutDescriptor } from "../../../descriptor/pipeline/PipelineLayoutDescriptor.js";
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import {
+    wgsl_texture_declaration_by_sample_type
+} from "../../texture/format/wgsl_texture_declaration_by_sample_type.js";
+import { CodeChunk } from "../compiler/CodeChunk.js";
+import { parse_wgsl_type } from "../type/parse_wgsl_type.js";
+import { type_has_arrays } from "../type/type_has_arrays.js";
+import { type_has_atomics } from "../type/type_has_atomics.js";
+import { type_has_f16 } from "../type/type_has_f16.js";
+import { WebGPUStruct } from "../type/WebGPUStruct.js";
+import { write_wgsl_type_value } from "../type/serde/write_gpu_typed_buffer.js";
+import { IMMEDIATE_ADDRESS_SPACE_EXTENSION, IMMEDIATE_SIZE_FLOOR } from "./IMMEDIATE_DATA.js";
+import { ResourceType } from "./ResourceType.js";
+import { ShaderResourceGroupDescriptor } from "./ShaderResourceGroupDescriptor.js";
+
+/**
+ * @typedef {import("../../../../core/binary/BinaryBuffer.js").BinaryBuffer} BinaryBuffer
+ * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("../type/WebGPUType.js").WebGPUType} WebGPUType
+ */
+
+/**
+ *
+ * @param {TextureBindingLayout} member
+ * @returns {string}
+ */
+function gen_type_texture(member) {
+    if (member.sampleType === "depth") {
+
+        if (member.viewDimension !== "2d") {
+            throw new Error('Must be 2d');
+        }
+
+        // special case
+        return "texture_depth_2d";
+    }
+
+    /**
+     * @type {string}
+     */
+    let proper_type;
+
+    switch (member.viewDimension) {
+        case "1d":
+            proper_type = "texture_1d";
+            break;
+        case "2d":
+            proper_type = "texture_2d";
+            break;
+        case "3d":
+            proper_type = "texture_3d";
+            break;
+        case "2d-array":
+            proper_type = "texture_2d_array";
+            break;
+        default:
+            throw new Error(`Unsupported viewDimension '${member.viewDimension}'`);
+    }
+
+    proper_type += "<";
+
+    proper_type += wgsl_texture_declaration_by_sample_type(member.sampleType);
+
+    proper_type += ">";
+
+    return proper_type;
+}
+
+/**
+ *
+ * @param {StorageTextureBindingLayout} member
+ * @returns {string}
+ */
+function gen_type_storage_texture(member) {
+    /**
+     * @type {string}
+     */
+    let proper_type;
+
+    if (member.viewDimension === "2d") {
+        proper_type = "texture_storage_2d"
+    } else if (member.viewDimension === "2d-array") {
+        proper_type = "texture_storage_2d_array";
+    } else if (member.viewDimension === "3d") {
+        proper_type = "texture_storage_3d";
+    } else {
+        throw new Error(`Unsupported viewDimension '${member.viewDimension}'`);
+    }
+
+    /**
+     *
+     * @param {GPUStorageTextureAccess} access
+     */
+    function gen_access(access) {
+        switch (access) {
+            case "write-only":
+                return "write";
+            case "read-write":
+                // TODO validate
+                return "read_write";
+            case "read-only":
+                // TODO valida
+                return "read";
+            default:
+                throw new Error(`Unsupported access ${access}`);
+        }
+    }
+
+    proper_type += `< ${member.format}, ${gen_access(member.access)} >`
+
+    return proper_type;
+}
+
+/**
+ *
+ * @param {SamplerBindingLayout} member
+ * @returns {string}
+ */
+function gen_type_sampler(member) {
+    // see https://www.w3.org/TR/WGSL/#sampler-type
+
+    // WGSL has no "non-filtering" sampler type; filtering is a bind-group-layout property, so
+    // both "filtering" and "non-filtering" declare a plain `sampler`
+    if (member.type === "filtering" || member.type === "non-filtering") {
+        return "sampler";
+    } else if (member.type === "comparison") {
+        return "sampler_comparison";
+    } else {
+        throw new Error(`Unsupported sampler type '${member.type}'`);
+    }
+
+}
+
+export class ShaderResourceSetDescriptor {
+
+    /**
+     *
+     * @type {ShaderResourceGroupDescriptor[]}
+     */
+    #groups = [];
+
+    /**
+     * The shader's immediate data declaration, or undefined when it has none.
+     *
+     * Deliberately not a member of any {@link ShaderResourceGroupDescriptor}: immediate data has no
+     * `@group` and no `@binding`, and WGSL is explicit that it is part of a shader's *interface*
+     * without being part of its *resource interface*. Modelling it as a group member would give it
+     * a binding index that does not exist.
+     *
+     * @type {{name: string, type: WebGPUType}|undefined}
+     */
+    #immediate = undefined;
+
+    /**
+     * @returns {{name: string, type: WebGPUType}|undefined}
+     */
+    get immediate() {
+        return this.#immediate;
+    }
+
+    /**
+     * Bytes of immediate data this shader reads, rounded up to the 4-byte granularity WebGPU
+     * requires of `immediateSize`. Zero when there is no immediate declaration.
+     *
+     * @returns {number}
+     */
+    get immediateSize() {
+        if (this.#immediate === undefined) {
+            return 0;
+        }
+
+        return round_up(this.#immediate.type.size, 4);
+    }
+
+    /**
+     * Declare this shader's immediate data — the WGSL `immediate` address space, which reaches the
+     * GPU through `setImmediates` on the pass encoder rather than through a bind group.
+     *
+     * Every restriction below is checked here rather than left to `createShaderModule`, because the
+     * device-side failure is a shader-creation error whose message names neither this descriptor nor
+     * the shader it belongs to.
+     *
+     * @param {string} name
+     * @param {WebGPUType|string} _type must be host-shareable, constructible, array-free, and fit
+     *        the device's `maxImmediateSize`
+     * @returns {this}
+     */
+    setImmediate(name, _type) {
+        assert.isString(name, 'name');
+        assert.defined(_type, 'type');
+
+        if (this.#immediate !== undefined) {
+            throw new Error(
+                `Immediate data is already declared as '${this.#immediate.name}'. WGSL allows at most one immediate variable per entry point, so '${name}' would have to replace it.`
+            );
+        }
+
+        let type = _type;
+
+        if (typeof type === "string") {
+            type = parse_wgsl_type(type);
+        } else {
+            assert.equal(type.isWebGPUType, true, 'type.isWebGPUType !== true');
+        }
+
+        if (type.runtime_sized) {
+            throw new Error(`Immediate data '${name}' must have a size known ahead of time, and '${type}' is runtime-sized`);
+        }
+
+        if (type_has_arrays(type)) {
+            throw new Error(
+                `Immediate data '${name}' may not contain an array: the immediate address space excludes arrays and structures with array members. Keep the array in a storage buffer and pass an index.`
+            );
+        }
+
+        // https://www.w3.org/TR/WGSL/#atomic-type — an immediate is immutable, so an atomic in one
+        // could never be operated on anyway
+        assert.equal(type_has_atomics(type), false, 'atomics are not allowed in immediate data');
+
+        const size = round_up(type.size, 4);
+
+        if (size > IMMEDIATE_SIZE_FLOOR) {
+            throw new Error(
+                `Immediate data '${name}' is ${size} bytes, over the ${IMMEDIATE_SIZE_FLOOR}-byte maxImmediateSize that every WebGPU device is guaranteed to offer. Move the bulk of it to a uniform buffer.`
+            );
+        }
+
+        // The top-level member names, kept so that `writeImmediate` can tell a value of this type
+        // from something that merely happens to be an object. `undefined` for a scalar, vector or
+        // matrix immediate, which has no members to name.
+        const field_names = type instanceof WebGPUStruct
+            ? type.fields.map(field => field.name)
+            : undefined;
+
+        this.#immediate = { name, type, field_names };
+
+        return this;
+    }
+
+    /**
+     * Do not modify directly
+     * @returns {ShaderResourceGroupDescriptor[]}
+     */
+    get groups() {
+        return this.#groups;
+    }
+
+
+    /**
+     *
+     * @return {boolean}
+     */
+    get isShaderResourceSetDescriptor() {
+        return true;
+    }
+
+    #getEmptySlot() {
+        for (let i = 0; i < 1024; i++) {
+            if (this.#groups[i] === undefined) {
+                return i;
+            }
+        }
+
+        throw new Error(`All slots are used up`);
+    }
+
+
+    /**
+     *
+     * @param {string} name
+     * @returns {ShaderResourceDescriptor}
+     */
+    /**
+     * Whether `name` is this shader's immediate data.
+     *
+     * Immediate data is deliberately absent from {@link getResourceByName}: it is not a bound
+     * resource and has no binding layout, so anything walking the resource interface should not see
+     * it. The graph helpers still need to recognise the name, because an immediate value travels to
+     * the encoder as a plain value rather than as a graph resource — and a `u32` immediate is a
+     * number, which those helpers would otherwise read as a graph resource id.
+     *
+     * @param {string} name
+     * @returns {boolean}
+     */
+    isImmediateName(name) {
+        return this.#immediate !== undefined && this.#immediate.name === name;
+    }
+
+    getResourceByName(name) {
+
+        for (const group of this.#groups) {
+
+            const resource = group.get(name);
+
+            if (resource !== undefined) {
+                return resource;
+            }
+
+        }
+
+    }
+
+    /**
+     *
+     * @param {Object} [options]
+     * @param {number} [options.index]
+     * @param {string} [options.label]
+     * @returns {ShaderResourceGroupDescriptor}
+     */
+    createGroup({
+                    index = this.#getEmptySlot(),
+                    label = "",
+                } = {}) {
+
+        assert.isNonNegativeInteger(index, 'index');
+        assert.lessThan(index, 1024, 'Too high');
+        assert.isString(label, 'label');
+
+        if (this.#groups[index] !== undefined) {
+            throw new Error(`Group ${index} already exists`);
+        }
+
+        const r = new ShaderResourceGroupDescriptor();
+
+        r.label = label;
+
+        this.#groups[index] = r;
+
+        return r;
+    }
+
+    /**
+     *
+     * @param {ShaderResourceGroupDescriptor} group
+     * @returns {boolean}
+     */
+    addGroup(group) {
+        // TODO check for name collisions
+
+        const added = array_push_if_unique(this.#groups, group);
+
+        return added;
+    }
+
+    /**
+     *
+     * @param {GPUShaderStage|number} stage
+     */
+    addVisibility(stage) {
+        const groups = this.#groups;
+        const group_count = groups.length;
+
+        for (let i = 0; i < group_count; i++) {
+            const group = groups[i];
+
+            group.addVisibility(stage);
+        }
+    }
+
+    /**
+     * @returns {PipelineLayoutDescriptor}
+     */
+    generatePipelineLayoutDescriptor() {
+        const r = new PipelineLayoutDescriptor();
+
+        const groups = this.#groups;
+        const group_count = groups.length;
+        for (let i = 0; i < group_count; i++) {
+
+            const group = groups[i];
+
+            r.bindGroupLayouts[i] = group.generateBindGroupLayoutDescriptor();
+        }
+
+        r.immediateSize = this.immediateSize;
+
+        return r;
+    }
+
+    /**
+     *
+     * @return {[][]}
+     */
+    generateBindingsArray() {
+        const binding_groups = [];
+
+        const groups = this.#groups;
+
+        for (let group_index = 0; group_index < groups.length; group_index++) {
+            const group = groups[group_index];
+
+            binding_groups[group_index] = group.resources.map(r => r.member_descriptor);
+        }
+
+        return binding_groups;
+    }
+
+    /**
+     *
+     * @param {GPUShaderStage|number} stage
+     * @returns {PipelineLayoutDescriptor}
+     */
+    generatePipelineLayout(stage) {
+        assert.defined(stage, 'stage');
+
+        return PipelineLayoutDescriptor.forStage(stage, this.generateBindingsArray(), this.immediateSize);
+    }
+
+    /**
+     *
+     * @param {Object} map
+     * @param {ShadeGPUCommandContext} [encoder] optional, allows resolving more defaults
+     * @returns {GPUBindingResource[][]}
+     */
+    generateBindings(map, encoder) {
+
+        const groups = this.#groups;
+        const group_count = groups.length;
+
+        const output = [];
+
+        for (let i = 0; i < group_count; i++) {
+            const group = groups[i];
+
+            output[i] = group.generateBindings(map, encoder);
+        }
+
+        return output;
+    }
+
+    /**
+     * Generates WGSL code declaring bindings
+     * @return {CodeChunk}
+     */
+    generateCodeChunk() {
+        const builder = new LineBuilder();
+
+        /**
+         *
+         * @type {Set<CodeChunk>}
+         */
+        const dependencies = new Set();
+
+        const groups = this.#groups;
+
+        const immediate = this.#immediate;
+        let uses_f16 = false;
+
+        if (immediate !== undefined) {
+            const immediate_type = immediate.type;
+
+            if (immediate_type.requires_declaration) {
+                dependencies.add(immediate_type.declaration_chunk);
+            }
+
+            if (type_has_f16(immediate_type)) {
+                uses_f16 = true;
+            }
+
+            // no @group, no @binding — this is the one module-scope variable that has neither
+            builder.add(`var<immediate> ${immediate.name} : ${immediate_type.wgsl_ref};`);
+        }
+
+        for (let group_index = 0; group_index < groups.length; group_index++) {
+            const group = groups[group_index];
+
+
+            const resources = group.resources;
+            const resource_count = resources.length;
+
+
+            for (let i = 0; i < resource_count; i++) {
+                const resource = resources[i];
+
+                const member = resource.member_descriptor;
+                const resource_type = resource.type;
+
+                let declaration = `@group(${group_index}) @binding(${resource.binding_index}) var`
+
+                let proper_type;
+
+                if (resource_type === ResourceType.Buffer) {
+
+                    const gpu_type = resource.buffer_type;
+
+                    if (gpu_type.requires_declaration) {
+                        dependencies.add(gpu_type.declaration_chunk);
+                    }
+
+                    if (type_has_f16(gpu_type)) {
+                        uses_f16 = true;
+                    }
+
+                    const layout_type = member.type;
+
+                    if (layout_type === "uniform") {
+                        declaration += "<uniform>"
+                    } else if (layout_type === "storage") {
+                        declaration += "<storage, read_write>"
+                    } else if (layout_type === "read-only-storage") {
+                        declaration += "<storage, read>"
+                    } else {
+                        throw new Error(`Unsupported layout type '${layout_type}'`);
+                    }
+
+                    proper_type = gpu_type.wgsl_ref;
+
+                } else if (resource_type === ResourceType.Texture) {
+                    proper_type = gen_type_texture(member);
+
+                } else if (resource_type === ResourceType.StorageTexture) {
+
+                    proper_type = gen_type_storage_texture(member);
+
+                } else if (resource_type === ResourceType.Sampler) {
+
+                    proper_type = gen_type_sampler(member);
+
+                } else {
+                    throw new Error(`Unsupported type ${objectKeyByValue(ResourceType, resource_type)}(=${resource_type})`)
+                }
+
+                declaration += " ";
+                declaration += resource.name;
+                declaration += " : ";
+
+
+                declaration += proper_type;
+
+                declaration += ";" // terminate the line
+
+                builder.add(declaration);
+            }
+
+        }
+
+        const chunk = CodeChunk.from(builder.build(), Array.from(dependencies));
+
+        if (immediate !== undefined) {
+            // `requires`, not `enable` — see CodeChunk#addLanguageExtension
+            chunk.addLanguageExtension(IMMEDIATE_ADDRESS_SPACE_EXTENSION);
+        }
+
+        if (uses_f16) {
+            chunk.addExtension(WebGPUExtensionType.ShaderF16);
+        }
+
+        return chunk;
+
+    }
+
+    /**
+     * Serialise this shader's immediate data into `buffer` at its current `position`, advancing
+     * `position` past what was written.
+     *
+     * **Allocates nothing.** That is the point of taking a caller-owned {@link BinaryBuffer} rather
+     * than returning bytes: `write_gpu_typed_buffer` would rebind a scratch buffer with a fresh
+     * `DataView` and `Uint8Array` on every call, which is two allocations per dispatch for a value
+     * that is often four bytes. {@link write_wgsl_type_value} takes the buffer directly and does not.
+     *
+     * The caller owns `position` because the caller owns the buffer — this only ever appends at the
+     * cursor it is handed.
+     *
+     * @param {Object} map the same binding map {@link generateBindings} reads
+     * @param {BinaryBuffer} buffer must already be set to the platform's endianness
+     * @returns {boolean} false when this shader declares no immediate data, and nothing was written
+     */
+    writeImmediate(map, buffer) {
+        const immediate = this.#immediate;
+
+        if (immediate === undefined) {
+            return false;
+        }
+
+        const value = map[immediate.name];
+
+        if (value === undefined || value === null) {
+            throw new Error(
+                `Value for immediate data '${immediate.name}' is missing from the input. Unlike a buffer binding it has no default: WebGPU refuses a draw whose immediate slots were never written.`
+            );
+        }
+
+        // Refuse a value of the wrong shape rather than serialise what it does not contain.
+        //
+        // The whole declared range travels every dispatch, and the zeroes this method clears it to are
+        // indistinguishable from deliberate ones: every slot ends up *set*, so WebGPU's immediate
+        // validation — and the software device's copy of it — has nothing to report. A wrong-shaped
+        // value therefore reaches the shader as zeroes, silently, and the only symptom is wrong
+        // output. That is what a call site left behind by the uniform -> immediate migration does: it
+        // keeps handing over the transient GPUBuffer the uniform needed, `generateBindings` ignores
+        // the extra key so the buffer is never bound, and nothing on a GPUBuffer matches the type.
+        //
+        // A value that names *some* of the members is left alone. Structs carry explicit padding
+        // members the CPU side has no value for, and skipping absent fields is load-bearing anyway
+        // (GPUTypedTable#set_range writes one member of a record through the same serialiser). Only a
+        // value that could not have populated the type at all is an unambiguous mistake.
+        const field_names = immediate.field_names;
+
+        if (field_names === undefined) {
+            // Scalar, vector or matrix: the serialiser reads the value as a number or indexes it.
+            const usable = typeof value === "number"
+                || typeof value === "boolean"
+                || typeof value[0] === "number";
+
+            if (!usable) {
+                throw new Error(
+                    `Immediate data '${immediate.name}' of type '${immediate.type}' was given a value the`
+                    + ` serialiser cannot read as a number: '${value}'. An immediate takes the plain value,`
+                    + ` not something bindable — a GPUBuffer is what a *uniform* binding wants, and one`
+                    + ` passed here is ignored by generateBindings and would serialise as zeroes.`
+                );
+            }
+        } else if (!value_names_a_member(value, field_names)) {
+            // Note: no `${immediate.type}` in the message. Interpolating a struct type runs its whole
+            // WGSL declaration through the code generator, and the member list is the actionable half
+            // of that anyway.
+            throw new Error(
+                `Immediate data '${immediate.name}' was given a value naming none of its members`
+                + ` (${field_names.join(', ')}), so the dispatch would have read zeroes. An immediate`
+                + ` takes the plain value — '{ ${field_names[0]}: ... }' — not`
+                + ` something bindable: a GPUBuffer is what a *uniform* binding wants, and one passed`
+                + ` here is ignored by generateBindings and serialises to nothing.`
+            );
+        }
+
+        const start = buffer.position;
+        const size = this.immediateSize;
+
+        buffer.ensureCapacity(start + size);
+
+        // Clear the whole declared range up front, rather than filling in from wherever the
+        // serialiser's cursor stopped.
+        //
+        // Two reasons, and the second is the one that bites. The first: the serialiser stops after the
+        // final member, so a struct with trailing padding — say `{vec4f, u32}`, 20 bytes written of a
+        // 32-byte type — leaves a tail. That tail is padding, WebGPU's AccessibleSlots excludes
+        // padding, and a short write would in fact validate; it would also make the bytes handed to
+        // `setImmediates` shorter than the `immediateSize` the pipeline layout declares, true-but-subtle
+        // in a way that only holds as long as nobody changes how either number is derived.
+        //
+        // The second: this buffer is one scratch region reused by every dispatch of a context, and it
+        // is only ever written over, never cleared. A member the value did not name is skipped, and a
+        // skipped member before the final one is not in the tail — filling from the cursor left it
+        // holding the bytes the *previous* dispatch put at that offset. A partial value is legal (see
+        // above), so that made one dispatch's immediate data a function of the one before it. Clearing
+        // first closes the holes and the tail together, and costs at most 64 bytes of memset.
+        buffer.raw_bytes.fill(0, start, start + size);
+
+        write_wgsl_type_value(value, buffer, immediate.type);
+
+        buffer.position = start + size;
+
+        return true;
+    }
+}
+
+/**
+ * Whether `value` carries at least one of `field_names`.
+ *
+ * A plain loop, and a free function rather than a closure over `value`, because
+ * {@link ShaderResourceSetDescriptor#writeImmediate} runs once per dispatch and allocates nothing.
+ *
+ * @param {Object} value
+ * @param {string[]} field_names
+ * @returns {boolean}
+ */
+function value_names_a_member(value, field_names) {
+    const count = field_names.length;
+
+    for (let i = 0; i < count; i++) {
+        if (value[field_names[i]] !== undefined) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Special immutable empty set
+ * @readonly
+ * @type {Readonly<ShaderResourceSetDescriptor>}
+ */
+ShaderResourceSetDescriptor.EMPTY = Object.freeze(new ShaderResourceSetDescriptor());