@woosh/meep-engine 3.11.2 → 3.12.0

package/src/shade/device/immediate_data_supported.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether this browser's WGSL implementation has the `immediate` address space.
+ *
+ * Synchronous and free: `wgslLanguageFeatures` hangs off `navigator.gpu`, so this needs neither an
+ * adapter nor a device and can be asked before either exists — including at module scope, where
+ * shader descriptors are built.
+ *
+ * **This is not a device floor.** Shade's floor (see `RENDERER_CONTRACT.md` §2) is fixed and
+ * `Renderer.initialize()` does not consult this — a browser without immediates still starts, and
+ * still renders, as long as nothing asks it for a shader that uses them. Deciding what to do about
+ * a missing capability belongs to whoever wrote the shader: refuse, or reach for a variant that
+ * declares the same struct as a uniform. Both are one `if` at the point where the shader is chosen,
+ * which is a far smaller thing than a capability branch threaded through codegen and binding.
+ *
+ * @returns {boolean}
+ */
+export function immediate_data_supported(): boolean;
+/**
+ * Whether `device` can actually carry `byte_count` bytes of immediate data.
+ *
+ * Separate from {@link immediate_data_supported} because they answer different questions of
+ * different objects: the language extension is a property of the browser's WGSL implementation, the
+ * budget is a property of the adapter. A conformant device reports at least 64 bytes whenever the
+ * extension is present — `maxImmediateSize` is a `maximum`-class limit defaulting to 64 with no
+ * separate compatibility-mode value — so the two agree in practice. Checking anyway costs nothing
+ * and turns a device that disagrees into a legible error instead of a shader-creation failure.
+ *
+ * @param {GPUDevice} device
+ * @param {number} [byte_count]
+ * @returns {boolean}
+ */
+export function device_supports_immediate_size(device: GPUDevice, byte_count?: number): boolean;
+//# sourceMappingURL=immediate_data_supported.d.ts.map

package/src/shade/device/immediate_data_supported.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"immediate_data_supported.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/immediate_data_supported.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,4CAFa,OAAO,CAgBnB;AAED;;;;;;;;;;;;;GAaG;AACH,+EAHW,MAAM,GACJ,OAAO,CAMnB"}

package/src/shade/device/immediate_data_supported.js

@@ -0,0 +1,53 @@
+import { IMMEDIATE_ADDRESS_SPACE_EXTENSION } from "../renderer/shader/resource/IMMEDIATE_DATA.js";
+
+/**
+ * Whether this browser's WGSL implementation has the `immediate` address space.
+ *
+ * Synchronous and free: `wgslLanguageFeatures` hangs off `navigator.gpu`, so this needs neither an
+ * adapter nor a device and can be asked before either exists — including at module scope, where
+ * shader descriptors are built.
+ *
+ * **This is not a device floor.** Shade's floor (see `RENDERER_CONTRACT.md` §2) is fixed and
+ * `Renderer.initialize()` does not consult this — a browser without immediates still starts, and
+ * still renders, as long as nothing asks it for a shader that uses them. Deciding what to do about
+ * a missing capability belongs to whoever wrote the shader: refuse, or reach for a variant that
+ * declares the same struct as a uniform. Both are one `if` at the point where the shader is chosen,
+ * which is a far smaller thing than a capability branch threaded through codegen and binding.
+ *
+ * @returns {boolean}
+ */
+export function immediate_data_supported() {
+    const gpu = globalThis.navigator?.gpu;
+
+    if (gpu === undefined || gpu === null) {
+        return false;
+    }
+
+    const features = gpu.wgslLanguageFeatures;
+
+    if (features === undefined || features === null) {
+        return false;
+    }
+
+    return features.has(IMMEDIATE_ADDRESS_SPACE_EXTENSION);
+}
+
+/**
+ * Whether `device` can actually carry `byte_count` bytes of immediate data.
+ *
+ * Separate from {@link immediate_data_supported} because they answer different questions of
+ * different objects: the language extension is a property of the browser's WGSL implementation, the
+ * budget is a property of the adapter. A conformant device reports at least 64 bytes whenever the
+ * extension is present — `maxImmediateSize` is a `maximum`-class limit defaulting to 64 with no
+ * separate compatibility-mode value — so the two agree in practice. Checking anyway costs nothing
+ * and turns a device that disagrees into a legible error instead of a shader-creation failure.
+ *
+ * @param {GPUDevice} device
+ * @param {number} [byte_count]
+ * @returns {boolean}
+ */
+export function device_supports_immediate_size(device, byte_count = 4) {
+    const limit = device?.limits?.maxImmediateSize ?? 0;
+
+    return limit >= byte_count;
+}

package/src/shade/device/mock/SoftwareGPUCommandEncoder.d.ts

@@ -38,6 +38,24 @@ export class SoftwareGPUCommandEncoder extends SoftwareGPUObjectBase implements
      * @returns {void}
      */
     notify_pass_ended(pass: SoftwareGPUComputePassEncoder | SoftwareGPURenderPassEncoder): void;
+    /**
+     * The device this encoder was created by. Passes read its limits — `maxImmediateSize` is the
+     * only one so far — and have no other route to it.
+     *
+     * @returns {SoftwareGPUDevice}
+     */
+    get device(): SoftwareGPUDevice;
+    /**
+     * Called by a pass this encoder opened, when that pass encodes something WebGPU refuses.
+     *
+     * A pass has nowhere of its own to put a validation error: WebGPU invalidates the *encoder* and
+     * reports from `finish()`, so a pass-level failure has to travel up here rather than being
+     * raised where it happened. See {@link #validation_error} for why the deferral matters.
+     *
+     * @param {string} message
+     * @returns {void}
+     */
+    notify_pass_validation_error(message: string): void;
     /**
      * Begin a compute pass. The pass **records** and executes nothing — see
      * {@link SoftwareGPUComputePassEncoder}. Every pass begun on this encoder stays on

package/src/shade/device/mock/SoftwareGPUCommandEncoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUCommandEncoder.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUCommandEncoder.js"],"names":[],"mappings":"AA2DA;;;;GAIG;AACH,gFAFgB,iBAAiB;IA+D7B;;;;OAIG;IACH,iFAIC;IAzDD;;;;OAIG;IACH,gBAFU,6BAA6B,EAAE,CAErB;IAEpB;;;;OAIG;IACH,eAFU,4BAA4B,EAAE,CAErB;IAEnB;;;;;;OAMG;IACH,QAFU,CAAC,6BAA6B,GAAC,4BAA4B,CAAC,EAAE,CAE5D;IA0EZ,mCAiBC;IAkBD;;;;;OAKG;IACH,wBAHW,6BAA6B,GAAC,4BAA4B,GACxD,IAAI,CAMhB;IAED;;;;;;;OAOG;IACH,+EAeC;IAED;;;;;;;OAOG;IACH,4EAaC;IAED;;;;;;;;OAQG;IACH,oHAFa,IAAI,CAsBhB;IAED;;;;;OAKG;IACH,kHAFa,IAAI,CAsBhB;IAED;;;;;OAKG;IACH,kHAFa,IAAI,CAsBhB;IAED;;;;;;;;;OASG;IACH,2DANW,MAAM,cACN,MAAM,qDAEN,MAAM,GACJ,IAAI,CAuBhB;IAwCD;;;;OAIG;IACH,sBAFW,MAAM,QAIhB;IAED,sBAEC;IAED;;OAEG;IACH,yBAFW,MAAM,QAIhB;IAyED;;;;;;;;OAQG;IACH,4DANW,MAAM,qDAEN,MAAM,QACN,MAAM,GACJ,IAAI,CA+BhB;IAED;;;;;;;OAOG;IACH,gDAJW,MAAM,SACN,MAAM,GACJ,IAAI,CA4BhB;IAGL;;;OAGG;IACH,sCAFU,OAAO,CAE8C;;CAN9D;sCA3kBqC,4BAA4B;8CAFpB,oCAAoC;6CAGrC,mCAAmC;yCAJvC,+BAA+B"}
+{"version":3,"file":"SoftwareGPUCommandEncoder.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUCommandEncoder.js"],"names":[],"mappings":"AA2DA;;;;GAIG;AACH,gFAFgB,iBAAiB;IA+D7B;;;;OAIG;IACH,iFAIC;IAzDD;;;;OAIG;IACH,gBAFU,6BAA6B,EAAE,CAErB;IAEpB;;;;OAIG;IACH,eAFU,4BAA4B,EAAE,CAErB;IAEnB;;;;;;OAMG;IACH,QAFU,CAAC,6BAA6B,GAAC,4BAA4B,CAAC,EAAE,CAE5D;IA0EZ,mCAiBC;IAkBD;;;;;OAKG;IACH,wBAHW,6BAA6B,GAAC,4BAA4B,GACxD,IAAI,CAMhB;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;;;;;OASG;IACH,sCAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;;;;OAOG;IACH,+EAeC;IAED;;;;;;;OAOG;IACH,4EAaC;IAED;;;;;;;;OAQG;IACH,oHAFa,IAAI,CAsBhB;IAED;;;;;OAKG;IACH,kHAFa,IAAI,CAsBhB;IAED;;;;;OAKG;IACH,kHAFa,IAAI,CAsBhB;IAED;;;;;;;;;OASG;IACH,2DANW,MAAM,cACN,MAAM,qDAEN,MAAM,GACJ,IAAI,CAuBhB;IAwCD;;;;OAIG;IACH,sBAFW,MAAM,QAIhB;IAED,sBAEC;IAED;;OAEG;IACH,yBAFW,MAAM,QAIhB;IAyED;;;;;;;;OAQG;IACH,4DANW,MAAM,qDAEN,MAAM,QACN,MAAM,GACJ,IAAI,CA+BhB;IAED;;;;;;;OAOG;IACH,gDAJW,MAAM,SACN,MAAM,GACJ,IAAI,CA4BhB;IAGL;;;OAGG;IACH,sCAFU,OAAO,CAE8C;;CAN9D;sCAnmBqC,4BAA4B;8CAFpB,oCAAoC;6CAGrC,mCAAmC;yCAJvC,+BAA+B"}

package/src/shade/device/mock/SoftwareGPUCommandEncoder.js

@@ -217,6 +217,30 @@ export class SoftwareGPUCommandEncoder extends SoftwareGPUObjectBase {
         }
     }
 
+    /**
+     * The device this encoder was created by. Passes read its limits — `maxImmediateSize` is the
+     * only one so far — and have no other route to it.
+     *
+     * @returns {SoftwareGPUDevice}
+     */
+    get device() {
+        return this.#device;
+    }
+
+    /**
+     * Called by a pass this encoder opened, when that pass encodes something WebGPU refuses.
+     *
+     * A pass has nowhere of its own to put a validation error: WebGPU invalidates the *encoder* and
+     * reports from `finish()`, so a pass-level failure has to travel up here rather than being
+     * raised where it happened. See {@link #validation_error} for why the deferral matters.
+     *
+     * @param {string} message
+     * @returns {void}
+     */
+    notify_pass_validation_error(message) {
+        this.#invalidate(message);
+    }
+
     /**
      * Begin a compute pass. The pass **records** and executes nothing — see
      * {@link SoftwareGPUComputePassEncoder}. Every pass begun on this encoder stays on

package/src/shade/device/mock/SoftwareGPUComputePassEncoder.d.ts

@@ -57,6 +57,13 @@ export class SoftwareGPUComputePassEncoder extends SoftwareGPUObjectBase impleme
      * @param {number} [dynamic_offsets_length]
      */
     setBindGroup(index: number, bind_group: GPUBindGroup, dynamic_offsets?: number[] | Uint32Array, dynamic_offsets_start?: number, dynamic_offsets_length?: number): void;
+    /**
+     * @param {number} range_offset byte offset into the immediate data range
+     * @param {ArrayBuffer|ArrayBufferView} data
+     * @param {number} [data_offset] in elements if `data` is a TypedArray, bytes otherwise
+     * @param {number} [data_size] in elements if `data` is a TypedArray, bytes otherwise
+     */
+    setImmediates(range_offset: number, data: ArrayBuffer | ArrayBufferView, data_offset?: number, data_size?: number): void;
     /**
      * @param {number} x
      * @param {number} [y]

package/src/shade/device/mock/SoftwareGPUComputePassEncoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUComputePassEncoder.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUComputePassEncoder.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,oFAFgB,qBAAqB;IAqDjC;;;OAGG;IACH,uFAOC;IA7DD;;;;OAIG;IACH,YAFU;QAAC,QAAQ,EAAE,qBAAmB,IAAI,CAAC;QAAC,WAAW,EAAE,cAAc,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,EAAE,CAAC;QAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KAAC,EAAE,CAEjI;IAEhB;;;;;OAKG;IACH,qCAAW;IA4BX;;;;OAIG;IACH,uBAEC;IAqBD;;OAEG;IACH,gDAIC;IAED;;;;;;;;;OASG;IACH,oBANW,MAAM,8CAEN,MAAM,EAAE,GAAC,WAAW,0BACpB,MAAM,2BACN,MAAM,QAWhB;IAeD;;;;OAIG;IACH,sBAJW,MAAM,MACN,MAAM,MACN,MAAM,QAUhB;IAED;;;OAGG;IACH,wEAFW,MAAM,QAYhB;IAED;;OAEG;IACH,sBAFW,MAAM,QAIhB;IAED,sBAEC;IAED;;OAEG;IACH,yBAFW,MAAM,QAIhB;IAED,YAQC;IAGL;;;OAGG;IACH,0CAFU,OAAO,CAEsD;;CANtE;sCA5LqC,4BAA4B"}
+{"version":3,"file":"SoftwareGPUComputePassEncoder.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUComputePassEncoder.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH,oFAFgB,qBAAqB;IA6DjC;;;OAGG;IACH,uFAQC;IAtED;;;;OAIG;IACH,YAFU;QAAC,QAAQ,EAAE,qBAAmB,IAAI,CAAC;QAAC,WAAW,EAAE,cAAc,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,EAAE,CAAC;QAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KAAC,EAAE,CAEjI;IAEhB;;;;;OAKG;IACH,qCAAW;IAoCX;;;;OAIG;IACH,uBAEC;IAsBD;;OAEG;IACH,gDAIC;IAED;;;;;;;;;OASG;IACH,oBANW,MAAM,8CAEN,MAAM,EAAE,GAAC,WAAW,0BACpB,MAAM,2BACN,MAAM,QAWhB;IAED;;;;;OAKG;IACH,4BALW,MAAM,QACN,WAAW,GAAC,eAAe,gBAC3B,MAAM,cACN,MAAM,QAUhB;IAkCD;;;;OAIG;IACH,sBAJW,MAAM,MACN,MAAM,MACN,MAAM,QAWhB;IAED;;;OAGG;IACH,wEAFW,MAAM,QAahB;IAED;;OAEG;IACH,sBAFW,MAAM,QAIhB;IAED,sBAEC;IAED;;OAEG;IACH,yBAFW,MAAM,QAIhB;IAED,YAQC;IAGL;;;OAGG;IACH,0CAFU,OAAO,CAEsD;;CANtE;sCA1OqC,4BAA4B"}

package/src/shade/device/mock/SoftwareGPUComputePassEncoder.js

@@ -1,4 +1,6 @@
 import { normalize_dynamic_offsets } from "./normalize_dynamic_offsets.js";
+import { pipeline_immediate_size } from "./pipeline_immediate_size.js";
+import { SoftwareGPUImmediateData } from "./SoftwareGPUImmediateData.js";
 import { SoftwareGPUObjectBase } from "./SoftwareGPUObjectBase.js";
 import { write_pass_timestamp } from "./write_pass_timestamp.js";
 
@@ -56,6 +58,14 @@ export class SoftwareGPUComputePassEncoder extends SoftwareGPUObjectBase {
      */
     #dynamic_offsets = [];
 
+    /**
+     * Immediate data for this pass. Per-encoder state in WebGPU, and a new pass starts over — which
+     * is why it is constructed here rather than carried in from the command encoder.
+     *
+     * @type {SoftwareGPUImmediateData}
+     */
+    #immediates;
+
     #ended = false;
 
     /**
@@ -76,6 +86,7 @@ export class SoftwareGPUComputePassEncoder extends SoftwareGPUObjectBase {
 
         this.#encoder = encoder;
         this.descriptor = descriptor;
+        this.#immediates = new SoftwareGPUImmediateData(encoder.device.limits.maxImmediateSize);
 
         write_pass_timestamp(descriptor, 'beginningOfPassWriteIndex');
     }
@@ -116,19 +127,54 @@ export class SoftwareGPUComputePassEncoder extends SoftwareGPUObjectBase {
         );
     }
 
+    /**
+     * @param {number} range_offset byte offset into the immediate data range
+     * @param {ArrayBuffer|ArrayBufferView} data
+     * @param {number} [data_offset] in elements if `data` is a TypedArray, bytes otherwise
+     * @param {number} [data_size] in elements if `data` is a TypedArray, bytes otherwise
+     */
+    setImmediates(range_offset, data, data_offset = 0, data_size) {
+        this.#assert_encoding();
+
+        const message = this.#immediates.write(range_offset, data, data_offset, data_size);
+
+        if (message !== null) {
+            this.#encoder.notify_pass_validation_error(message);
+        }
+    }
+
     /**
      * The bind group state a dispatch would run under, copied so later `setBindGroup` calls do not
      * rewrite an already-recorded dispatch.
      *
-     * @returns {{bind_groups: GPUBindGroup[], dynamic_offsets: number[][]}}
+     * @returns {{bind_groups: GPUBindGroup[], dynamic_offsets: number[][], immediates: {bytes: Uint8Array, slots_set: boolean[]}}}
      */
     #snapshot_bindings() {
         return {
             bind_groups: this.#bind_groups.slice(),
             dynamic_offsets: this.#dynamic_offsets.map(offsets => offsets === undefined ? [] : offsets.slice()),
+            immediates: this.#immediates.snapshot(),
         };
     }
 
+    /**
+     * WebGPU's *Validate immediate data*: every slot the pipeline's immediate range covers must have
+     * been written before a command reads it. The bytes default to zero but the slots do not default
+     * to set, so a forgotten `setImmediates` is a refused draw on a real device rather than a shader
+     * quietly reading zeroes. Catching it here is the whole reason the slot bookkeeping exists.
+     *
+     * @returns {void}
+     */
+    #validate_immediates() {
+        const size = pipeline_immediate_size(this.#pipeline);
+
+        if (size > 0 && !this.#immediates.isRangeSet(0, size)) {
+            this.#encoder.notify_pass_validation_error(
+                `dispatch: pipeline declares ${size} bytes of immediate data, and not all of it was set by setImmediates`
+            );
+        }
+    }
+
     /**
      * @param {number} x
      * @param {number} [y]
@@ -136,6 +182,7 @@ export class SoftwareGPUComputePassEncoder extends SoftwareGPUObjectBase {
      */
     dispatchWorkgroups(x, y = 1, z = 1) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.dispatches.push({
             pipeline: this.#pipeline,
@@ -150,6 +197,7 @@ export class SoftwareGPUComputePassEncoder extends SoftwareGPUObjectBase {
      */
     dispatchWorkgroupsIndirect(indirect_buffer, indirect_offset) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         // The group counts live in a buffer a shader wrote, which nothing here executed — recording
         // a count read out of it would be fiction, so the entry says what it is.

package/src/shade/device/mock/SoftwareGPUDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AAyOA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;;;OAUG;IACH;QAT+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAyBrC;IAzDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAmCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmHD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;OAGG;IACH,kEAEC;IAED;;;OAGG;IACH,iFAEC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WAvnBa,mBAAiB,IAAI;;sCAxOG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}
+{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AA+OA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;;;OAUG;IACH;QAT+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAyBrC;IAzDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAmCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmHD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;OAGG;IACH,kEAEC;IAED;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WAnoBa,mBAAiB,IAAI;;sCA9OG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}

package/src/shade/device/mock/SoftwareGPUDevice.js

@@ -64,7 +64,13 @@ const DEFAULT_LIMITS = {
     maxStorageBuffersInFragmentStage: 8,
     maxStorageTexturesInVertexStage: 4,
     maxStorageTexturesInFragmentStage: 4,
-    maxImmediateSize: 0,
+    // The spec's default for this `maximum`-class limit, with no separate compatibility-mode value —
+    // so every conformant adapter reports at least this, and a device that exposes the
+    // `immediate_address_space` WGSL extension always has the budget to go with it. Unlike its
+    // neighbours above, this one is NOT a reading taken from a Dawn device: the `webgpu` package the
+    // comment above cites is not actually a dependency of this repo (it appears in `package.json`
+    // only as a keyword), so it could not be re-read. It is the spec value, deliberately.
+    maxImmediateSize: 64,
 }
 
 /**
@@ -764,7 +770,19 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase {
      * @returns {GPUPipelineLayout}
      */
     createPipelineLayout(descriptor) {
-        return { ...descriptor, isSoftwarePipelineLayout: true };
+        const immediate_size = descriptor.immediateSize ?? 0;
+
+        if (immediate_size > this.#limits.maxImmediateSize) {
+            this.generate_error(new SoftwareGPUValidationError(
+                `createPipelineLayout: immediateSize(=${immediate_size}) exceeds maxImmediateSize(=${this.#limits.maxImmediateSize})`
+            ));
+        } else if (immediate_size % 4 !== 0) {
+            this.generate_error(new SoftwareGPUValidationError(
+                `createPipelineLayout: immediateSize(=${immediate_size}) must be a multiple of 4`
+            ));
+        }
+
+        return { ...descriptor, immediateSize: immediate_size, isSoftwarePipelineLayout: true };
     }
 
     /**

package/src/shade/device/mock/SoftwareGPUImmediateData.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The immediate-data state a {@link GPUBindingCommandsMixin} carries — WebGPU's
+ * `[[immediate_data]]` and `[[immediate_slots_set]]`, which both pass encoders own a copy of.
+ *
+ * The two slot-tracking rules are the reason this exists rather than a plain `Uint8Array`:
+ *
+ * 1. The bytes start **zeroed** but every 4-byte slot starts **unset**, and a draw that reads an
+ *    unset slot is a validation error. A mock that only kept the bytes would hand a shader a
+ *    plausible zero where a real device refuses the draw — the exact class of bug this folder
+ *    exists to catch before a browser does.
+ * 2. `setImmediates` marks slots, it never clears them. Only a new pass starts over.
+ *
+ * @see https://www.w3.org/TR/webgpu/#dom-gpubindingcommandsmixin-setimmediates
+ */
+export class SoftwareGPUImmediateData {
+    /**
+     * @param {number} max_immediate_size the device's `maxImmediateSize` limit, in bytes
+     */
+    constructor(max_immediate_size: number);
+    /**
+     * @returns {number} the `maxImmediateSize` this was built for
+     */
+    get capacity(): number;
+    /**
+     * Record a `setImmediates` call.
+     *
+     * The content-timeline failures throw an `OperationError`, because that is what WebGPU does at
+     * the call site. The device-timeline failures do **not** throw — they return a message, which
+     * the pass hands to the encoder to surface from `finish()`, matching how every other encoding
+     * validation error in this folder behaves.
+     *
+     * @param {number} range_offset byte offset into the immediate data range
+     * @param {ArrayBuffer|ArrayBufferView} data
+     * @param {number} [data_offset] in elements if `data` is a TypedArray, bytes otherwise
+     * @param {number} [data_size] in elements if `data` is a TypedArray, bytes otherwise
+     * @returns {string|null} a validation message, or null when the call was accepted
+     * @throws {DOMException} `OperationError`, for the content-timeline failures
+     */
+    write(range_offset: number, data: ArrayBuffer | ArrayBufferView, data_offset?: number, data_size?: number): string | null;
+    /**
+     * Whether every slot in `[range_offset, range_offset + size)` has been written.
+     *
+     * This is the check a draw performs against the pipeline's declared immediate range. It is
+     * deliberately slot-granular rather than byte-granular, because WebGPU's `AccessibleSlots`
+     * excludes padding: a struct with a hole in it is fully initialised as long as every 4-byte
+     * slot it actually reads was touched.
+     *
+     * @param {number} range_offset
+     * @param {number} size in bytes
+     * @returns {boolean}
+     */
+    isRangeSet(range_offset: number, size: number): boolean;
+    /**
+     * The state a draw or dispatch would run under, copied so a later `setImmediates` does not
+     * rewrite an already-recorded command.
+     *
+     * @returns {{bytes: Uint8Array, slots_set: boolean[]}}
+     */
+    snapshot(): {
+        bytes: Uint8Array;
+        slots_set: boolean[];
+    };
+    #private;
+}
+//# sourceMappingURL=SoftwareGPUImmediateData.d.ts.map

package/src/shade/device/mock/SoftwareGPUImmediateData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SoftwareGPUImmediateData.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUImmediateData.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH;IAeI;;OAEG;IACH,gCAFW,MAAM,EAKhB;IAED;;OAEG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,oBAPW,MAAM,QACN,WAAW,GAAC,eAAe,gBAC3B,MAAM,cACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAgEvB;IAED;;;;;;;;;;;OAWG;IACH,yBAJW,MAAM,QACN,MAAM,GACJ,OAAO,CAanB;IAED;;;;;OAKG;IACH,YAFa;QAAC,KAAK,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,OAAO,EAAE,CAAA;KAAC,CAOrD;;CACJ"}

package/src/shade/device/mock/SoftwareGPUImmediateData.js

@@ -0,0 +1,160 @@
+/**
+ * The immediate-data state a {@link GPUBindingCommandsMixin} carries — WebGPU's
+ * `[[immediate_data]]` and `[[immediate_slots_set]]`, which both pass encoders own a copy of.
+ *
+ * The two slot-tracking rules are the reason this exists rather than a plain `Uint8Array`:
+ *
+ * 1. The bytes start **zeroed** but every 4-byte slot starts **unset**, and a draw that reads an
+ *    unset slot is a validation error. A mock that only kept the bytes would hand a shader a
+ *    plausible zero where a real device refuses the draw — the exact class of bug this folder
+ *    exists to catch before a browser does.
+ * 2. `setImmediates` marks slots, it never clears them. Only a new pass starts over.
+ *
+ * @see https://www.w3.org/TR/webgpu/#dom-gpubindingcommandsmixin-setimmediates
+ */
+export class SoftwareGPUImmediateData {
+    /**
+     * `[[immediate_data]]` — `maxImmediateSize` bytes, initially zero.
+     *
+     * @type {Uint8Array}
+     */
+    #bytes;
+
+    /**
+     * `[[immediate_slots_set]]` — one entry per 4-byte slot, initially false.
+     *
+     * @type {boolean[]}
+     */
+    #slots_set;
+
+    /**
+     * @param {number} max_immediate_size the device's `maxImmediateSize` limit, in bytes
+     */
+    constructor(max_immediate_size) {
+        this.#bytes = new Uint8Array(max_immediate_size);
+        this.#slots_set = new Array(Math.floor(max_immediate_size / 4)).fill(false);
+    }
+
+    /**
+     * @returns {number} the `maxImmediateSize` this was built for
+     */
+    get capacity() {
+        return this.#bytes.byteLength;
+    }
+
+    /**
+     * Record a `setImmediates` call.
+     *
+     * The content-timeline failures throw an `OperationError`, because that is what WebGPU does at
+     * the call site. The device-timeline failures do **not** throw — they return a message, which
+     * the pass hands to the encoder to surface from `finish()`, matching how every other encoding
+     * validation error in this folder behaves.
+     *
+     * @param {number} range_offset byte offset into the immediate data range
+     * @param {ArrayBuffer|ArrayBufferView} data
+     * @param {number} [data_offset] in elements if `data` is a TypedArray, bytes otherwise
+     * @param {number} [data_size] in elements if `data` is a TypedArray, bytes otherwise
+     * @returns {string|null} a validation message, or null when the call was accepted
+     * @throws {DOMException} `OperationError`, for the content-timeline failures
+     */
+    write(range_offset, data, data_offset = 0, data_size) {
+        const is_typed_array = ArrayBuffer.isView(data) && !(data instanceof DataView);
+
+        // "If data is an ArrayBuffer or DataView, let the element type be byte."
+        const bytes_per_element = is_typed_array ? data.BYTES_PER_ELEMENT : 1;
+
+        const data_element_count = is_typed_array
+            ? data.length
+            : (data instanceof DataView ? data.byteLength : data.byteLength);
+
+        const contents_size = data_size === undefined
+            ? data_element_count - data_offset
+            : data_size;
+
+        const contents_bytes = contents_size * bytes_per_element;
+
+        if (contents_size < 0) {
+            throw new DOMException(
+                `setImmediates: contentsSize(=${contents_size}) must be non-negative`,
+                'OperationError'
+            );
+        }
+
+        if (data_offset + contents_size > data_element_count) {
+            throw new DOMException(
+                `setImmediates: dataOffset(=${data_offset}) + contentsSize(=${contents_size}) exceeds data length(=${data_element_count})`,
+                'OperationError'
+            );
+        }
+
+        if (contents_bytes % 4 !== 0) {
+            throw new DOMException(
+                `setImmediates: contents size in bytes(=${contents_bytes}) must be a multiple of 4`,
+                'OperationError'
+            );
+        }
+
+        // device timeline from here — these invalidate rather than throw
+
+        if (range_offset % 4 !== 0) {
+            return `setImmediates: rangeOffset(=${range_offset}) must be a multiple of 4`;
+        }
+
+        if (range_offset + contents_bytes > this.#bytes.byteLength) {
+            return `setImmediates: rangeOffset(=${range_offset}) + ${contents_bytes} bytes exceeds maxImmediateSize(=${this.#bytes.byteLength})`;
+        }
+
+        const source = data instanceof ArrayBuffer
+            ? new Uint8Array(data)
+            : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+
+        const source_byte_offset = data_offset * bytes_per_element;
+
+        for (let i = 0; i < contents_bytes; i++) {
+            const byte_index = range_offset + i;
+
+            this.#bytes[byte_index] = source[source_byte_offset + i];
+            this.#slots_set[byte_index >> 2] = true;
+        }
+
+        return null;
+    }
+
+    /**
+     * Whether every slot in `[range_offset, range_offset + size)` has been written.
+     *
+     * This is the check a draw performs against the pipeline's declared immediate range. It is
+     * deliberately slot-granular rather than byte-granular, because WebGPU's `AccessibleSlots`
+     * excludes padding: a struct with a hole in it is fully initialised as long as every 4-byte
+     * slot it actually reads was touched.
+     *
+     * @param {number} range_offset
+     * @param {number} size in bytes
+     * @returns {boolean}
+     */
+    isRangeSet(range_offset, size) {
+        const first = range_offset >> 2;
+        const last = (range_offset + size - 1) >> 2;
+
+        for (let slot = first; slot <= last; slot++) {
+            if (this.#slots_set[slot] !== true) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * The state a draw or dispatch would run under, copied so a later `setImmediates` does not
+     * rewrite an already-recorded command.
+     *
+     * @returns {{bytes: Uint8Array, slots_set: boolean[]}}
+     */
+    snapshot() {
+        return {
+            bytes: this.#bytes.slice(),
+            slots_set: this.#slots_set.slice(),
+        };
+    }
+}

package/src/shade/device/mock/SoftwareGPURenderPassEncoder.d.ts

@@ -70,6 +70,13 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase implemen
      * @param {number} [dynamic_offsets_length]
      */
     setBindGroup(index: number, bind_group: GPUBindGroup, dynamic_offsets?: number[] | Uint32Array, dynamic_offsets_start?: number, dynamic_offsets_length?: number): void;
+    /**
+     * @param {number} range_offset byte offset into the immediate data range
+     * @param {ArrayBuffer|ArrayBufferView} data
+     * @param {number} [data_offset] in elements if `data` is a TypedArray, bytes otherwise
+     * @param {number} [data_size] in elements if `data` is a TypedArray, bytes otherwise
+     */
+    setImmediates(range_offset: number, data: ArrayBuffer | ArrayBufferView, data_offset?: number, data_size?: number): void;
     /**
      * @param {number} slot
      * @param {GPUBuffer} buffer

package/src/shade/device/mock/SoftwareGPURenderPassEncoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPURenderPassEncoder.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPURenderPassEncoder.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,mFAFgB,oBAAoB;IA2EhC;;;OAGG;IACH,sFAOC;IAnFD;;;;;;;;;OASG;IACH,OAFU;QAAC,QAAQ,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW,EAAE,cAAc,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,EAAE,MAAM,GAAC,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAC,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,GAAC,IAAI,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAC,EAAE,CAElR;IAEX;;;;;;OAMG;IACH,oCAAW;IA4CX;;;;OAIG;IACH,uBAEC;IAqBD;;OAEG;IACH,+CAIC;IAED;;;;;;;;OAQG;IACH,oBANW,MAAM,8CAEN,MAAM,EAAE,GAAC,WAAW,0BACpB,MAAM,2BACN,MAAM,QAWhB;IAED;;;;;OAKG;IACH,sBALW,MAAM,8BAEN,MAAM,SACN,MAAM,QAMhB;IAED;;;;;OAKG;IACH,yEAHW,MAAM,SACN,MAAM,QAMhB;IAED;;;;;;;OAOG;IACH,eAPW,MAAM,KACN,MAAM,SACN,MAAM,UACN,MAAM,aACN,MAAM,aACN,MAAM,QAMhB;IAED;;;;;OAKG;IACH,kBALW,MAAM,KACN,MAAM,SACN,MAAM,UACN,MAAM,QAMhB;IAED;;OAEG;IACH,wCAIC;IADG,yBAA2B;IAG/B;;OAEG;IACH,+BAFW,MAAM,QAMhB;IADG,0BAAkC;IAqBtC;;;OAGG;IACH,mBAHW,MAAM,mBACN,MAAM,QAYhB;IAED;;;OAGG;IACH,yBAHW,MAAM,mBACN,MAAM,QAYhB;IAED;;;OAGG;IACH,0DAFW,MAAM,QAehB;IAED;;;OAGG;IACH,iEAFW,MAAM,QAchB;IAED;;OAEG;IACH,sBAFW,MAAM,QAIhB;IAED,sBAEC;IAED;;OAEG;IACH,yBAFW,MAAM,QAIhB;IAED,YAQC;IAGL;;;OAGG;IACH,yCAFU,OAAO,CAEoD;;CANpE;sCAjUqC,4BAA4B"}
+{"version":3,"file":"SoftwareGPURenderPassEncoder.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPURenderPassEncoder.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,mFAFgB,oBAAoB;IAmFhC;;;OAGG;IACH,sFAQC;IA5FD;;;;;;;;;OASG;IACH,OAFU;QAAC,QAAQ,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW,EAAE,cAAc,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,EAAE,MAAM,GAAC,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAC,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,GAAC,IAAI,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAC,EAAE,CAElR;IAEX;;;;;;OAMG;IACH,oCAAW;IAoDX;;;;OAIG;IACH,uBAEC;IAsBD;;OAEG;IACH,+CAIC;IAED;;;;;;;;OAQG;IACH,oBANW,MAAM,8CAEN,MAAM,EAAE,GAAC,WAAW,0BACpB,MAAM,2BACN,MAAM,QAWhB;IAED;;;;;OAKG;IACH,4BALW,MAAM,QACN,WAAW,GAAC,eAAe,gBAC3B,MAAM,cACN,MAAM,QAUhB;IAED;;;;;OAKG;IACH,sBALW,MAAM,8BAEN,MAAM,SACN,MAAM,QAMhB;IAED;;;;;OAKG;IACH,yEAHW,MAAM,SACN,MAAM,QAMhB;IAED;;;;;;;OAOG;IACH,eAPW,MAAM,KACN,MAAM,SACN,MAAM,UACN,MAAM,aACN,MAAM,aACN,MAAM,QAMhB;IAED;;;;;OAKG;IACH,kBALW,MAAM,KACN,MAAM,SACN,MAAM,UACN,MAAM,QAMhB;IAED;;OAEG;IACH,wCAIC;IADG,yBAA2B;IAG/B;;OAEG;IACH,+BAFW,MAAM,QAMhB;IADG,0BAAkC;IAwCtC;;;OAGG;IACH,mBAHW,MAAM,mBACN,MAAM,QAahB;IAED;;;OAGG;IACH,yBAHW,MAAM,mBACN,MAAM,QAahB;IAED;;;OAGG;IACH,0DAFW,MAAM,QAgBhB;IAED;;;OAGG;IACH,iEAFW,MAAM,QAehB;IAED;;OAEG;IACH,sBAFW,MAAM,QAIhB;IAED,sBAEC;IAED;;OAEG;IACH,yBAFW,MAAM,QAIhB;IAED,YAQC;IAGL;;;OAGG;IACH,yCAFU,OAAO,CAEoD;;CANpE;sCAjXqC,4BAA4B"}