@woosh/meep-engine 3.11.2 → 3.12.0

package/src/shade/wgsl/emulator/ComputeShaderEmulator.js

@@ -1,291 +1,291 @@
-import { assert } from "../../../core/assert.js";
-import { WGSLParser } from "../WGSLParser.js";
-import { WGSLJavaScriptCompiler } from "./WGSLJavaScriptCompiler.js";
-import { WGSLLanguageCore } from "./WGSLLanguageCore.js";
-
-/**
- * Emulates a {@link ComputeShader} on the CPU by translating its WGSL source to JavaScript
- * and dispatching threads point-wise.
- *
- * Intended for testing — feed the same shader instance you'd run on a GPU, drive it from a
- * unit test, and inspect the resulting bindings or texture state.
- *
- * Texture bindings expect a {@link CPUBitmapData} (1D / 2D / 3D inferred from
- * the bitmap's `size`). Sampling routes through {@link cpu_texture_sample},
- * which honours the bound sampler's address modes and filter.
- *
- * @example
- *   const shader = ComputeShader.from({...});
- *   const emu = await ComputeShaderEmulator.create(shader);
- *   emu.bindings = { data: someArray };
- *   emu.dispatch([0, 0, 0]);   // global_invocation_id = (0,0,0)
- *   emu.dispatch([1, 0, 0]);   // global_invocation_id = (1,0,0)
- *   // ... bindings now contain results
- */
-export class ComputeShaderEmulator {
-
-    /** @type {string} */
-    #source;
-
-    /** @type {string} */
-    #js_source;
-
-    /** @type {object} */
-    #module;
-
-    /** @type {object} */
-    #workgroup_state;
-
-    /** @type {object} */
-    #language_core;
-
-    /**
-     * Bindings currently in effect. Keys match the WGSL variable names declared with
-     * `@group(...) @binding(...) var ...: T`.
-     * @type {object}
-     */
-    bindings = {};
-
-    /**
-     * Construct directly when you already have the WGSL source string.
-     *
-     * For most use cases prefer {@link create} or {@link fromComputeShader}.
-     *
-     * @param {object} options
-     * @param {object} options.module — the compiled module returned by the JS factory
-     * @param {string} options.source — the original WGSL source
-     * @param {string} options.jsSource — the generated JS source (kept for debugging)
-     * @param {object} options.languageCore — the runtime `wgsl` object
-     */
-    constructor({ module, source, jsSource, languageCore }) {
-        this.#module = module;
-        this.#source = source;
-        this.#js_source = jsSource;
-        this.#language_core = languageCore;
-        // Fragment-stage entries have no var<workgroup>, so the module skips emitting the
-        // workgroup-state factory; in that case workgroup_state is a no-op empty object.
-        this.#workgroup_state = typeof module.create_workgroup_state === 'function'
-            ? module.create_workgroup_state()
-            : {};
-    }
-
-    /**
-     * @returns {string} the WGSL source.
-     */
-    get source() {
-        return this.#source;
-    }
-
-    /**
-     * @returns {string} the generated JavaScript source. Useful for debugging.
-     */
-    get jsSource() {
-        return this.#js_source;
-    }
-
-    /**
-     * @returns {object} the language core object passed to the generated JS as `wgsl`.
-     */
-    get languageCore() {
-        return this.#language_core;
-    }
-
-    /**
-     * @returns {string} the name of the entry function (whether @compute or @fragment).
-     */
-    get entryName() {
-        return this.#module.entry_name;
-    }
-
-    /**
-     * @returns {'compute' | 'fragment'} which shader stage the entry function targets.
-     */
-    get stage() {
-        return this.#module.stage;
-    }
-
-    /**
-     * @returns {number[] | undefined} the workgroup size for @compute entries (undefined for @fragment).
-     */
-    get workgroup_size() {
-        return this.#module.workgroup_size;
-    }
-
-    /**
-     * @returns {string[]} the entry function's parameter names, in declaration order.
-     */
-    get entryParamNames() {
-        return this.#module.param_names;
-    }
-
-    /**
-     * @returns {object} the current workgroup state — workgroup-scope variables live here.
-     */
-    get workgroup() {
-        return this.#workgroup_state;
-    }
-
-    /**
-     * Reset the workgroup state. Call between simulated workgroups so that `var<workgroup>`
-     * variables start fresh. No-op for fragment-stage entries.
-     */
-    resetWorkgroup() {
-        if (typeof this.#module.create_workgroup_state === 'function') {
-            this.#workgroup_state = this.#module.create_workgroup_state();
-        }
-    }
-
-    /**
-     * Dispatch a single thread (point-wise simulation). The arguments are the entry function's
-     * parameters, in declaration order — for example a `@builtin(global_invocation_id)` param of
-     * type `vec3<u32>` is supplied as a 3-element array.
-     *
-     * For @compute entries, returns whatever the entry function returns (typically nothing —
-     * results land in bindings). For @fragment entries, returns the fragment's output value
-     * (typically a vec4 for `@location(0)` or a struct of locations).
-     *
-     * @param {...*} mainArgs
-     * @returns {*}
-     */
-    dispatch(...mainArgs) {
-        if (this.#module.stage === 'fragment') {
-            return this.#module.entry(this.bindings, ...mainArgs);
-        }
-        return this.#module.entry(this.bindings, this.#workgroup_state, ...mainArgs);
-    }
-
-    /**
-     * Compile a WGSL source string into an executable emulator. Requires a `@compute` or
-     * `@fragment` entry function; for chunks of pure helper code with no entry, use
-     * {@link fromCodeChunk}.
-     *
-     * @param {string} source
-     * @param {object} [options]
-     * @param {WGSLParser} [options.parser] — share a parser across multiple compiles
-     * @param {object} [options.languageCore] — defaults to {@link WGSLLanguageCore}
-     * @returns {Promise<ComputeShaderEmulator>}
-     */
-    static async fromSource(source, options = {}) {
-        const { module, jsSource } = await compileWgslSource(source, options);
-        if (typeof module.entry !== 'function') {
-            throw new Error('ComputeShaderEmulator.fromSource: WGSL has no @compute or @fragment entry function. Use ComputeShaderEmulator.fromCodeChunk for library-style code.');
-        }
-        return new ComputeShaderEmulator({
-            module,
-            source,
-            jsSource,
-            languageCore: options.languageCore || WGSLLanguageCore,
-        });
-    }
-
-    /**
-     * Build an emulator from an existing {@link ComputeShader} instance.
-     *
-     * @param {import("../../renderer/shader/ComputeShader.js").ComputeShader} shader
-     * @param {object} [options]
-     * @param {WGSLParser} [options.parser]
-     * @param {object} [options.languageCore]
-     * @returns {Promise<ComputeShaderEmulator>}
-     */
-    static async fromComputeShader(shader, options = {}) {
-        assert.defined(shader, 'shader');
-        const source = shader.descriptor.compile();
-        return ComputeShaderEmulator.fromSource(source, options);
-    }
-
-    /**
-     * Build an emulator from an existing {@link ImageShader} instance — a full-screen fragment
-     * pass. The vertex stage is intentionally skipped (single-pixel emulation), so callers
-     * provide the `@builtin(position)` value (and any other fragment inputs) directly to
-     * {@link dispatch}.
-     *
-     * Derivative builtins (`dpdx`, `dpdy`, `fwidth` and their fine/coarse variants) throw at
-     * runtime — their values can't be faked from a single pixel.
-     *
-     * @example
-     *   const emu = await ComputeShaderEmulator.fromImageShader(shader);
-     *   emu.bindings = { input: someCPUBitmapData };
-     *   const out = emu.dispatch(new Float32Array([100.5, 200.5, 0, 1])); // vec4 frag.position
-     *   // `out` is the fragment's @location(0) return value (typically a vec4).
-     *
-     * @param {import("../../renderer/shader/ImageShader.js").ImageShader} shader
-     * @param {object} [options]
-     * @param {WGSLParser} [options.parser]
-     * @param {object} [options.languageCore]
-     * @returns {Promise<ComputeShaderEmulator>}
-     */
-    static async fromImageShader(shader, options = {}) {
-        assert.defined(shader, 'shader');
-        const source = shader.descriptor.compile();
-        return ComputeShaderEmulator.fromSource(source, options);
-    }
-
-    /**
-     * Compile a {@link CodeChunk} (or a raw WGSL string) into a "library" object — every
-     * top-level WGSL function becomes a method, every `var<private>` becomes a getter/setter
-     * property, and every module-scope `const` becomes a read-only getter.
-     *
-     * No `@compute` entry is required. This is the one-line escape hatch for unit-testing pure
-     * helper code (RNGs, hashes, packing, math) without wrapping each chunk in a shader skeleton.
-     *
-     * @example
-     *   const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_random);
-     *   expect(lib.random()).toBeLessThan(1);
-     *
-     * @param {import("../../renderer/shader/compiler/CodeChunk.js").CodeChunk | string} chunk_or_source
-     * @param {object} [options]
-     * @param {WGSLParser} [options.parser]
-     * @param {object} [options.languageCore]
-     * @returns {Promise<object>} the library module
-     */
-    static async fromCodeChunk(chunk_or_source, options = {}) {
-        assert.defined(chunk_or_source, 'chunk_or_source');
-        const source = typeof chunk_or_source === 'string'
-            ? chunk_or_source
-            : chunk_or_source.compile().text;
-        const { module } = await compileWgslSource(source, options);
-        return module;
-    }
-}
-
-/**
- * Internal helper: parse + compile + evaluate a WGSL source string, returning the factory's
- * resulting module along with the generated JS for diagnostics.
- *
- * @param {string} source
- * @param {object} options
- * @param {WGSLParser} [options.parser]
- * @param {object} [options.languageCore]
- * @returns {Promise<{ module: object, jsSource: string }>}
- */
-async function compileWgslSource(source, { parser, languageCore = WGSLLanguageCore } = {}) {
-    assert.isString(source, 'source');
-
-    let p = parser;
-    if (p === undefined) {
-        p = new WGSLParser();
-        await p.init();
-    }
-
-    const tree = p.parse(source);
-    if (tree.rootNode.hasError) {
-        throw new Error(`WGSL parse error in source:\n${source}`);
-    }
-
-
-    const compiler = new WGSLJavaScriptCompiler();
-    const jsSource = compiler.compile(tree);
-
-    let factory;
-    try {
-        // eslint-disable-next-line no-new-func
-        factory = (new Function(`return ${jsSource};`))();
-    } catch (e) {
-        const err = new Error(`failed to evaluate generated JavaScript: ${e.message}\n--- generated JS ---\n${jsSource}`);
-        err.cause = e;
-        throw err;
-    }
-    const module = factory(languageCore);
-
-    return { module, jsSource };
-}
+import { assert } from "../../../core/assert.js";
+import { WGSLParser } from "../WGSLParser.js";
+import { WGSLJavaScriptCompiler } from "./WGSLJavaScriptCompiler.js";
+import { WGSLLanguageCore } from "./WGSLLanguageCore.js";
+
+/**
+ * Emulates a {@link ComputeShader} on the CPU by translating its WGSL source to JavaScript
+ * and dispatching threads point-wise.
+ *
+ * Intended for testing — feed the same shader instance you'd run on a GPU, drive it from a
+ * unit test, and inspect the resulting bindings or texture state.
+ *
+ * Texture bindings expect a {@link CPUBitmapData} (1D / 2D / 3D inferred from
+ * the bitmap's `size`). Sampling routes through {@link cpu_texture_sample},
+ * which honours the bound sampler's address modes and filter.
+ *
+ * @example
+ *   const shader = ComputeShader.from({...});
+ *   const emu = await ComputeShaderEmulator.create(shader);
+ *   emu.bindings = { data: someArray };
+ *   emu.dispatch([0, 0, 0]);   // global_invocation_id = (0,0,0)
+ *   emu.dispatch([1, 0, 0]);   // global_invocation_id = (1,0,0)
+ *   // ... bindings now contain results
+ */
+export class ComputeShaderEmulator {
+
+    /** @type {string} */
+    #source;
+
+    /** @type {string} */
+    #js_source;
+
+    /** @type {object} */
+    #module;
+
+    /** @type {object} */
+    #workgroup_state;
+
+    /** @type {object} */
+    #language_core;
+
+    /**
+     * Bindings currently in effect. Keys match the WGSL variable names declared with
+     * `@group(...) @binding(...) var ...: T`.
+     * @type {object}
+     */
+    bindings = {};
+
+    /**
+     * Construct directly when you already have the WGSL source string.
+     *
+     * For most use cases prefer {@link create} or {@link fromComputeShader}.
+     *
+     * @param {object} options
+     * @param {object} options.module — the compiled module returned by the JS factory
+     * @param {string} options.source — the original WGSL source
+     * @param {string} options.jsSource — the generated JS source (kept for debugging)
+     * @param {object} options.languageCore — the runtime `wgsl` object
+     */
+    constructor({ module, source, jsSource, languageCore }) {
+        this.#module = module;
+        this.#source = source;
+        this.#js_source = jsSource;
+        this.#language_core = languageCore;
+        // Fragment-stage entries have no var<workgroup>, so the module skips emitting the
+        // workgroup-state factory; in that case workgroup_state is a no-op empty object.
+        this.#workgroup_state = typeof module.create_workgroup_state === 'function'
+            ? module.create_workgroup_state()
+            : {};
+    }
+
+    /**
+     * @returns {string} the WGSL source.
+     */
+    get source() {
+        return this.#source;
+    }
+
+    /**
+     * @returns {string} the generated JavaScript source. Useful for debugging.
+     */
+    get jsSource() {
+        return this.#js_source;
+    }
+
+    /**
+     * @returns {object} the language core object passed to the generated JS as `wgsl`.
+     */
+    get languageCore() {
+        return this.#language_core;
+    }
+
+    /**
+     * @returns {string} the name of the entry function (whether @compute or @fragment).
+     */
+    get entryName() {
+        return this.#module.entry_name;
+    }
+
+    /**
+     * @returns {'compute' | 'fragment'} which shader stage the entry function targets.
+     */
+    get stage() {
+        return this.#module.stage;
+    }
+
+    /**
+     * @returns {number[] | undefined} the workgroup size for @compute entries (undefined for @fragment).
+     */
+    get workgroup_size() {
+        return this.#module.workgroup_size;
+    }
+
+    /**
+     * @returns {string[]} the entry function's parameter names, in declaration order.
+     */
+    get entryParamNames() {
+        return this.#module.param_names;
+    }
+
+    /**
+     * @returns {object} the current workgroup state — workgroup-scope variables live here.
+     */
+    get workgroup() {
+        return this.#workgroup_state;
+    }
+
+    /**
+     * Reset the workgroup state. Call between simulated workgroups so that `var<workgroup>`
+     * variables start fresh. No-op for fragment-stage entries.
+     */
+    resetWorkgroup() {
+        if (typeof this.#module.create_workgroup_state === 'function') {
+            this.#workgroup_state = this.#module.create_workgroup_state();
+        }
+    }
+
+    /**
+     * Dispatch a single thread (point-wise simulation). The arguments are the entry function's
+     * parameters, in declaration order — for example a `@builtin(global_invocation_id)` param of
+     * type `vec3<u32>` is supplied as a 3-element array.
+     *
+     * For @compute entries, returns whatever the entry function returns (typically nothing —
+     * results land in bindings). For @fragment entries, returns the fragment's output value
+     * (typically a vec4 for `@location(0)` or a struct of locations).
+     *
+     * @param {...*} mainArgs
+     * @returns {*}
+     */
+    dispatch(...mainArgs) {
+        if (this.#module.stage === 'fragment') {
+            return this.#module.entry(this.bindings, ...mainArgs);
+        }
+        return this.#module.entry(this.bindings, this.#workgroup_state, ...mainArgs);
+    }
+
+    /**
+     * Compile a WGSL source string into an executable emulator. Requires a `@compute` or
+     * `@fragment` entry function; for chunks of pure helper code with no entry, use
+     * {@link fromCodeChunk}.
+     *
+     * @param {string} source
+     * @param {object} [options]
+     * @param {WGSLParser} [options.parser] — share a parser across multiple compiles
+     * @param {object} [options.languageCore] — defaults to {@link WGSLLanguageCore}
+     * @returns {Promise<ComputeShaderEmulator>}
+     */
+    static async fromSource(source, options = {}) {
+        const { module, jsSource } = await compileWgslSource(source, options);
+        if (typeof module.entry !== 'function') {
+            throw new Error('ComputeShaderEmulator.fromSource: WGSL has no @compute or @fragment entry function. Use ComputeShaderEmulator.fromCodeChunk for library-style code.');
+        }
+        return new ComputeShaderEmulator({
+            module,
+            source,
+            jsSource,
+            languageCore: options.languageCore || WGSLLanguageCore,
+        });
+    }
+
+    /**
+     * Build an emulator from an existing {@link ComputeShader} instance.
+     *
+     * @param {import("../../renderer/shader/ComputeShader.js").ComputeShader} shader
+     * @param {object} [options]
+     * @param {WGSLParser} [options.parser]
+     * @param {object} [options.languageCore]
+     * @returns {Promise<ComputeShaderEmulator>}
+     */
+    static async fromComputeShader(shader, options = {}) {
+        assert.defined(shader, 'shader');
+        const source = shader.descriptor.source;
+        return ComputeShaderEmulator.fromSource(source, options);
+    }
+
+    /**
+     * Build an emulator from an existing {@link ImageShader} instance — a full-screen fragment
+     * pass. The vertex stage is intentionally skipped (single-pixel emulation), so callers
+     * provide the `@builtin(position)` value (and any other fragment inputs) directly to
+     * {@link dispatch}.
+     *
+     * Derivative builtins (`dpdx`, `dpdy`, `fwidth` and their fine/coarse variants) throw at
+     * runtime — their values can't be faked from a single pixel.
+     *
+     * @example
+     *   const emu = await ComputeShaderEmulator.fromImageShader(shader);
+     *   emu.bindings = { input: someCPUBitmapData };
+     *   const out = emu.dispatch(new Float32Array([100.5, 200.5, 0, 1])); // vec4 frag.position
+     *   // `out` is the fragment's @location(0) return value (typically a vec4).
+     *
+     * @param {import("../../renderer/shader/ImageShader.js").ImageShader} shader
+     * @param {object} [options]
+     * @param {WGSLParser} [options.parser]
+     * @param {object} [options.languageCore]
+     * @returns {Promise<ComputeShaderEmulator>}
+     */
+    static async fromImageShader(shader, options = {}) {
+        assert.defined(shader, 'shader');
+        const source = shader.descriptor.source;
+        return ComputeShaderEmulator.fromSource(source, options);
+    }
+
+    /**
+     * Compile a {@link CodeChunk} (or a raw WGSL string) into a "library" object — every
+     * top-level WGSL function becomes a method, every `var<private>` becomes a getter/setter
+     * property, and every module-scope `const` becomes a read-only getter.
+     *
+     * No `@compute` entry is required. This is the one-line escape hatch for unit-testing pure
+     * helper code (RNGs, hashes, packing, math) without wrapping each chunk in a shader skeleton.
+     *
+     * @example
+     *   const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_random);
+     *   expect(lib.random()).toBeLessThan(1);
+     *
+     * @param {import("../../renderer/shader/compiler/CodeChunk.js").CodeChunk | string} chunk_or_source
+     * @param {object} [options]
+     * @param {WGSLParser} [options.parser]
+     * @param {object} [options.languageCore]
+     * @returns {Promise<object>} the library module
+     */
+    static async fromCodeChunk(chunk_or_source, options = {}) {
+        assert.defined(chunk_or_source, 'chunk_or_source');
+        const source = typeof chunk_or_source === 'string'
+            ? chunk_or_source
+            : chunk_or_source.compile().text;
+        const { module } = await compileWgslSource(source, options);
+        return module;
+    }
+}
+
+/**
+ * Internal helper: parse + compile + evaluate a WGSL source string, returning the factory's
+ * resulting module along with the generated JS for diagnostics.
+ *
+ * @param {string} source
+ * @param {object} options
+ * @param {WGSLParser} [options.parser]
+ * @param {object} [options.languageCore]
+ * @returns {Promise<{ module: object, jsSource: string }>}
+ */
+async function compileWgslSource(source, { parser, languageCore = WGSLLanguageCore } = {}) {
+    assert.isString(source, 'source');
+
+    let p = parser;
+    if (p === undefined) {
+        p = new WGSLParser();
+        await p.init();
+    }
+
+    const tree = p.parse(source);
+    if (tree.rootNode.hasError) {
+        throw new Error(`WGSL parse error in source:\n${source}`);
+    }
+
+
+    const compiler = new WGSLJavaScriptCompiler();
+    const jsSource = compiler.compile(tree);
+
+    let factory;
+    try {
+        // eslint-disable-next-line no-new-func
+        factory = (new Function(`return ${jsSource};`))();
+    } catch (e) {
+        const err = new Error(`failed to evaluate generated JavaScript: ${e.message}\n--- generated JS ---\n${jsSource}`);
+        err.cause = e;
+        throw err;
+    }
+    const module = factory(languageCore);
+
+    return { module, jsSource };
+}

package/src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js

@@ -859,7 +859,14 @@ function collectGlobalVariable(c, node) {
 
     c.scope.declare(name, type);
 
-    if (group !== null && binding !== null) {
+    // `var<immediate>` carries neither attribute — immediate data is part of the shader interface
+    // but is not a bound resource, so WGSL gives it no @group/@binding. It still arrives from
+    // outside the shader, so it is a binding as far as the emulator is concerned, and binding here
+    // is what keeps it out of the `privateGlobals` branch below. Falling through to that branch
+    // would default-initialise it and every spec reading it would quietly see zeroes.
+    const is_immediate = address_space === 'immediate';
+
+    if (is_immediate || (group !== null && binding !== null)) {
         c.globalBindings.push({
             name, type, group, binding, addressSpace: address_space, accessMode: access_mode,
         });

package/src/shade/wgsl/emulator/WGSLLanguageCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":"AA0PA;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAu8Bd"}
+{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":"AA0PA;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAm+Bd"}