@woosh/meep-engine 3.11.2 → 3.12.0

package/src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.d.ts

@@ -1,4 +1,32 @@
 export class ShaderResourceSetDescriptor {
+    /**
+     * @returns {{name: string, type: WebGPUType}|undefined}
+     */
+    get immediate(): {
+        name: string;
+        type: WebGPUType;
+    };
+    /**
+     * 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(): number;
+    /**
+     * 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: string, _type: WebGPUType | string): this;
     /**
      * Do not modify directly
      * @returns {ShaderResourceGroupDescriptor[]}
@@ -14,7 +42,20 @@ export class ShaderResourceSetDescriptor {
      * @param {string} name
      * @returns {ShaderResourceDescriptor}
      */
-    getResourceByName(name: string): 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: string): boolean;
+    getResourceByName(name: any): import("./ShaderResourceDescriptor.js").ShaderResourceDescriptor;
     /**
      *
      * @param {number} [index]
@@ -60,6 +101,23 @@ export class ShaderResourceSetDescriptor {
      * @return {CodeChunk}
      */
     generateCodeChunk(): CodeChunk;
+    /**
+     * 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: any, buffer: BinaryBuffer): boolean;
     #private;
 }
 export namespace ShaderResourceSetDescriptor {

package/src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderResourceSetDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js"],"names":[],"mappings":"AAwHA;IAQI;;;OAGG;IACH,8CAEC;IAGD;;;OAGG;IACH,6CAEC;IAaD;;;;OAIG;IACH,wBAHW,MAAM,4BAehB;IAED;;;;;OAKG;IACH,gCAJW,MAAM,GAEJ,6BAA6B,CAsBzC;IAED;;;;OAIG;IACH,gBAHW,6BAA6B,GAC3B,OAAO,CAQnB;IAED;;;OAGG;IACH,qBAFW,iBAAe,MAAM,QAW/B;IAED;;OAEG;IACH,oCAFa,wBAAwB,CAepC;IAED;;;OAGG;IACH,yBAFY,EAAE,EAAE,CAcf;IAED;;;;OAIG;IACH,8BAHW,iBAAe,MAAM,GACnB,wBAAwB,CAMpC;IAED;;;;;OAKG;IACH,8DAFa,oBAAoB,EAAE,CAgBlC;IAED;;;OAGG;IACH,qBAFY,SAAS,CAoFpB;;CACJ;;eAKS,SAAS,2BAA2B,CAAC;;8CA9XD,oCAAoC;yCANzC,0DAA0D;0BAIzE,0BAA0B"}
+{"version":3,"file":"ShaderResourceSetDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js"],"names":[],"mappings":"AA8HA;IAoBI;;OAEG;IACH;cAFoB,MAAM;;MAIzB;IAED;;;;;OAKG;IACH,4BAMC;IAED;;;;;;;;;;;;OAYG;IACH,mBALW,MAAM,SACN,aAAW,MAAM,GAEf,IAAI,CA6ChB;IAED;;;OAGG;IACH,8CAEC;IAGD;;;OAGG;IACH,6CAEC;IAaD;;;;OAIG;IACH;;;;;;;;;;;OAWG;IACH,sBAHW,MAAM,GACJ,OAAO,CAInB;IAED,+FAYC;IAED;;;;;OAKG;IACH,gCAJW,MAAM,GAEJ,6BAA6B,CAsBzC;IAED;;;;OAIG;IACH,gBAHW,6BAA6B,GAC3B,OAAO,CAQnB;IAED;;;OAGG;IACH,qBAFW,iBAAe,MAAM,QAW/B;IAED;;OAEG;IACH,oCAFa,wBAAwB,CAiBpC;IAED;;;OAGG;IACH,yBAFY,EAAE,EAAE,CAcf;IAED;;;;OAIG;IACH,8BAHW,iBAAe,MAAM,GACnB,wBAAwB,CAMpC;IAED;;;;;OAKG;IACH,8DAFa,oBAAoB,EAAE,CAgBlC;IAED;;;OAGG;IACH,qBAFY,SAAS,CAwGpB;IAED;;;;;;;;;;;;;;;OAeG;IACH,gDAFa,OAAO,CA0CnB;;CACJ;;eAKS,SAAS,2BAA2B,CAAC;;8CAzjBD,oCAAoC;yCAXzC,0DAA0D;0BAIzE,0BAA0B"}

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

@@ -1,4 +1,5 @@
 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";
@@ -7,6 +8,11 @@ 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 { 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";
 
@@ -126,6 +132,97 @@ export class ShaderResourceSetDescriptor {
      */
     #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.`
+            );
+        }
+
+        this.#immediate = { name, type };
+
+        return this;
+    }
+
     /**
      * Do not modify directly
      * @returns {ShaderResourceGroupDescriptor[]}
@@ -159,6 +256,22 @@ export class ShaderResourceSetDescriptor {
      * @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) {
@@ -244,6 +357,8 @@ export class ShaderResourceSetDescriptor {
             r.bindGroupLayouts[i] = group.generateBindGroupLayoutDescriptor();
         }
 
+        r.immediateSize = this.immediateSize;
+
         return r;
     }
 
@@ -273,7 +388,7 @@ export class ShaderResourceSetDescriptor {
     generatePipelineLayout(stage) {
         assert.defined(stage, 'stage');
 
-        return PipelineLayoutDescriptor.forStage(stage, this.generateBindingsArray());
+        return PipelineLayoutDescriptor.forStage(stage, this.generateBindingsArray(), this.immediateSize);
     }
 
     /**
@@ -313,6 +428,19 @@ export class ShaderResourceSetDescriptor {
 
         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];
 
@@ -382,8 +510,73 @@ export class ShaderResourceSetDescriptor {
 
         }
 
-        return CodeChunk.from(builder.build(), Array.from(dependencies));
+        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.`
+            );
+        }
+
+        const start = buffer.position;
+        const size = this.immediateSize;
+
+        buffer.ensureCapacity(start + size);
+
+        write_wgsl_type_value(value, buffer, immediate.type);
+
+        // Zero-fill out to the declared size rather than stopping where the last member ended.
+        //
+        // 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 mean the bytes handed to `setImmediates` are shorter than the `immediateSize`
+        // the pipeline layout declares, which is true-but-subtle in a way that only holds as long as
+        // nobody changes how either number is derived. Writing the full declared size costs at most
+        // 64 bytes of memset and makes the two trivially equal.
+        const written = buffer.position - start;
+
+        for (let i = written; i < size; i++) {
+            buffer.raw_bytes[start + i] = 0;
+        }
+
+        buffer.position = start + size;
+
+        return true;
     }
 }
 

package/src/shade/renderer/shader/type/type_has_arrays.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether a type is, or transitively contains, an array.
+ *
+ * Exists for the `immediate` address space, whose store type must be "a host-shareable constructible
+ * type, excluding arrays and structures that contain array members". The restriction is not
+ * arbitrary: immediates lower to D3D12 root constants and Metal `setBytes`, where a dynamically
+ * indexed array has nowhere good to live.
+ *
+ * @see https://www.w3.org/TR/WGSL/#var-decls
+ * @param {WebGPUType} t
+ * @return {boolean}
+ */
+export function type_has_arrays(t: WebGPUType): boolean;
+//# sourceMappingURL=type_has_arrays.d.ts.map

package/src/shade/renderer/shader/type/type_has_arrays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type_has_arrays.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/type/type_has_arrays.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,gDAFY,OAAO,CAsBlB"}

package/src/shade/renderer/shader/type/type_has_arrays.js

@@ -0,0 +1,33 @@
+/**
+ * Whether a type is, or transitively contains, an array.
+ *
+ * Exists for the `immediate` address space, whose store type must be "a host-shareable constructible
+ * type, excluding arrays and structures that contain array members". The restriction is not
+ * arbitrary: immediates lower to D3D12 root constants and Metal `setBytes`, where a dynamically
+ * indexed array has nowhere good to live.
+ *
+ * @see https://www.w3.org/TR/WGSL/#var-decls
+ * @param {WebGPUType} t
+ * @return {boolean}
+ */
+export function type_has_arrays(t) {
+    if (t.isArray) {
+        return true;
+    }
+
+    if (t.isPrimitive || t.isAtomic) {
+        return false;
+    }
+
+    if (t.isStruct) {
+        for (const f of t.fields) {
+            if (type_has_arrays(f.type)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    throw new Error(`Unsupported type '${t}'`);
+}

package/src/shade/renderer/shader/util/compute_infer_workgroup_size_from_source.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Recover a compute entry point's workgroup size from its WGSL source.
+ *
+ * Follows the `workgroup_size_attr` grammar, so every spelling below is read alike, and the omitted
+ * dimensions default to `1`:
+ *
+ * ```wgsl
+ * @workgroup_size(64)              // -> [64, 1, 1]
+ * @workgroup_size(8, 8)            // -> [8, 8, 1]
+ * @workgroup_size( 8 , 8 , 4 , )   // -> [8, 8, 4], blankspace anywhere, trailing comma
+ * @workgroup_size(0x40u)           // -> [64, 1, 1], hexadecimal, and the i/u type suffixes
+ * ```
+ *
+ * An argument may also name a `const` that the same module binds directly to an integer literal,
+ * which is how a shader states its block size once and then uses it in both the attribute and the
+ * body:
+ *
+ * ```wgsl
+ * const BLOCK_DIM = 256u;
+ * @workgroup_size(BLOCK_DIM)       // -> [256, 1, 1]
+ * ```
+ *
+ * Comments count as blankspace and are removed first, so they may sit between any two tokens of the
+ * attribute, and an attribute that is itself commented out is correctly not found.
+ *
+ * **One level of aliasing, and no arithmetic.** WGSL permits any const-expression or
+ * override-expression, so `@workgroup_size(BLOCK_DIM / 2u)` is legal, and so is
+ * `@workgroup_size(WG_X)` for an `override WG_X` whose value only arrives with the pipeline.
+ * Neither is resolvable from the source text alone. Such a shader throws rather than being guessed
+ * at, because every caller for this number divides a thread count by it, and a wrong divisor
+ * silently dispatches the wrong fraction of the workload. A loud failure is recoverable; a
+ * plausible one is not.
+ *
+ * Entry points that disagree are an error for the same reason. A module may hold several, and
+ * choosing between two conflicting sizes would be choosing at random.
+ *
+ * @param {string} code WGSL source
+ * @returns {[number, number, number]} `[x, y, z]`
+ * @throws {Error} if no `@workgroup_size` attribute is present, if its arguments are neither
+ * integer literals nor names resolving to one, if a dimension is not a positive integer, or if
+ * entry points disagree on the size
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function compute_infer_workgroup_size_from_source(code: string): [number, number, number];
+//# sourceMappingURL=compute_infer_workgroup_size_from_source.d.ts.map

package/src/shade/renderer/shader/util/compute_infer_workgroup_size_from_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute_infer_workgroup_size_from_source.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/util/compute_infer_workgroup_size_from_source.js"],"names":[],"mappings":"AA2SA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,+DATW,MAAM,GACJ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CA+GpC"}