@woosh/meep-engine 3.47.0 → 3.49.0

package/src/shade/renderer/shader/compiler/CodeChunk.js

@@ -4,6 +4,11 @@ import { isArrayEqual } from "../../../../core/collection/array/isArrayEqual.js"
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 
+/**
+ * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+
 
 export class CodeChunk {
 
@@ -206,6 +211,9 @@ export class CodeChunk {
 
             const chunk = stack[stack_pointer];
 
+            if (chunk.isCodeChunkChoice === true) {
+                throw new Error(`The graph holds a ${chunk}; specialize it before linking it, see CodeChunk.specialize`);
+            }
 
             if (collected.has(chunk)) {
                 // already visited, skip
@@ -227,6 +235,133 @@ export class CodeChunk {
         return Array.from(collected);
     }
 
+    /**
+     * Every {@link ShaderSwitch} this chunk's graph decides somewhere, through every alternative of
+     * every {@link CodeChunkChoice}, selected or not: the switches a shader built on it depends on.
+     * Each appears once, in the order a breadth-first walk from here meets it.
+     *
+     * @returns {ShaderSwitch[]}
+     */
+    collectSwitches() {
+        /**
+         * @type {ShaderSwitch[]}
+         */
+        const switches = [];
+
+        /**
+         * @type {Set<CodeChunk>}
+         */
+        const visited = new Set([this]);
+
+        /**
+         * @type {CodeChunk[]}
+         */
+        const queue = [this];
+
+        for (let cursor = 0; cursor < queue.length; cursor++) {
+            const chunk = queue[cursor];
+
+            let next;
+
+            if (chunk.isCodeChunkChoice === true) {
+                array_push_if_unique(switches, chunk.shader_switch);
+
+                next = chunk.alternatives;
+            } else {
+                next = chunk.#dependencies;
+            }
+
+            for (let i = 0; i < next.length; i++) {
+                const dependency = next[i];
+
+                if (!visited.has(dependency)) {
+                    visited.add(dependency);
+                    queue.push(dependency);
+                }
+            }
+        }
+
+        return switches;
+    }
+
+    /**
+     * This graph as `set` makes it: every {@link CodeChunkChoice} in it replaced by the alternative
+     * `set` selects, so the result holds no choice and links like any other graph.
+     *
+     * Only what lies above a choice is new. A chunk whose closure holds no choice is returned as it is,
+     * and so is this chunk when the whole graph holds none. Within one call each chunk is specialized
+     * once, so what two chunks share in this graph they still share in the result.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {CodeChunk}
+     */
+    specialize(set) {
+        assert.defined(set, 'set');
+        assert.equal(set.isShaderSwitchSet, true, 'set.isShaderSwitchSet !== true');
+
+        return CodeChunk.#specialize(this, set, new Map());
+    }
+
+    /**
+     * @param {CodeChunk} chunk
+     * @param {ShaderSwitchSet} set
+     * @param {Map<CodeChunk, CodeChunk>} memo what each chunk of this call's graph became
+     * @returns {CodeChunk}
+     */
+    static #specialize(chunk, set, memo) {
+        let r = memo.get(chunk);
+
+        if (r !== undefined) {
+            return r;
+        }
+
+        if (chunk.isCodeChunkChoice === true) {
+            r = CodeChunk.#specialize(chunk.alternative_for(set), set, memo);
+
+            memo.set(chunk, r);
+
+            return r;
+        }
+
+        const dependencies = chunk.#dependencies;
+        const n = dependencies.length;
+
+        /**
+         * Left null for as long as every dependency comes back as itself.
+         * @type {CodeChunk[]|null}
+         */
+        let specialized = null;
+
+        for (let i = 0; i < n; i++) {
+            const dependency = dependencies[i];
+            const s = CodeChunk.#specialize(dependency, set, memo);
+
+            if (specialized === null && s !== dependency) {
+                specialized = dependencies.slice(0, i);
+            }
+
+            if (specialized !== null) {
+                // two choices may select one chunk, or a choice the chunk that is also a sibling
+                array_push_if_unique(specialized, s);
+            }
+        }
+
+        if (specialized === null) {
+            r = chunk;
+        } else {
+            r = new CodeChunk();
+
+            r.#text = chunk.#text;
+            r.#dependencies = specialized;
+            r.#extensions = chunk.#extensions.slice();
+            r.#language_extensions = chunk.#language_extensions.slice();
+        }
+
+        memo.set(chunk, r);
+
+        return r;
+    }
+
     /**
      * Unroll all dependencies, excluding this chunk, into a single list where all dependencies are in the correct order
      * @return {CodeChunk[]}
@@ -371,6 +506,11 @@ export class CodeChunk {
             return true;
         }
 
+        if (other.isCodeChunkChoice === true) {
+            // a choice has no text of its own; it is equal only to itself
+            return false;
+        }
+
         return this.#text === other.#text
             && isArrayEqual(this.#dependencies, other.#dependencies)
             ;

package/src/shade/renderer/shader/compiler/CodeChunkChoice.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+/**
+ * The place in a chunk graph where a {@link ShaderSwitch} is decided: a chunk that stands for one
+ * alternative per value of the switch.
+ *
+ * Every alternative defines the same WGSL functions, so whatever depends on the choice is written
+ * once, whichever is linked. Each alternative is an ordinary {@link CodeChunk} with its own
+ * dependencies. {@link CodeChunk#specialize} replaces the choice with the alternative a
+ * {@link ShaderSwitchSet} selects, so the graph that is compiled has only that alternative's closure
+ * in it, and no choice.
+ *
+ * ```js
+ * export const chunk_shadowmap_sample_directional = CodeChunkChoice.from(SHADOW_DIRECTIONAL_TECHNIQUE);
+ * chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Cascades, chunk_shadowmap_sample_directional_cascades);
+ * chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Virtual, chunk_shadowmap_sample_directional_virtual);
+ * ```
+ *
+ * A chunk depends on the choice as on any chunk, however deep, and a shader learns that it depends on
+ * the switch from its graph ({@link CodeChunk#collectSwitches}).
+ */
+export class CodeChunkChoice extends CodeChunk {
+    /**
+     * @param {ShaderSwitch} shader_switch
+     * @returns {CodeChunkChoice} with no alternatives yet; {@link add} one per value
+     */
+    static from(shader_switch: ShaderSwitch): CodeChunkChoice;
+    /**
+     * @returns {ShaderSwitch}
+     */
+    get shader_switch(): import("./ShaderSwitch.js").ShaderSwitch;
+    /**
+     * Every alternative given so far, for walks that must see all of them.
+     * @returns {CodeChunk[]}
+     */
+    get alternatives(): CodeChunk[];
+    /**
+     * @param {number|boolean} value one of the switch's values — a member of its enum, or `false`/`true` — not
+     * given an alternative yet
+     * @param {CodeChunk} alternative linked when the switch has this value. It may itself be a choice,
+     * of another switch.
+     */
+    add(value: number | boolean, alternative: CodeChunk): void;
+    /**
+     * @param {ShaderSwitchSet} set
+     * @returns {CodeChunk} the alternative `set` selects
+     * @throws {Error} when the selected value has no alternative here
+     */
+    alternative_for(set: ShaderSwitchSet): CodeChunk;
+    /**
+     * A choice is linked as the alternative it stands for; see {@link CodeChunk#specialize}.
+     */
+    compile(): void;
+    /**
+     * @param {CodeChunkChoice} other
+     */
+    copy(other: CodeChunkChoice): void;
+    /**
+     * @returns {CodeChunkChoice}
+     */
+    clone(): CodeChunkChoice;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isCodeChunkChoice: boolean;
+    #private;
+}
+export type ShaderSwitch = import("./ShaderSwitch.js").ShaderSwitch;
+export type ShaderSwitchSet = import("./ShaderSwitchSet.js").ShaderSwitchSet;
+import { CodeChunk } from "./CodeChunk.js";
+//# sourceMappingURL=CodeChunkChoice.d.ts.map

package/src/shade/renderer/shader/compiler/CodeChunkChoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeChunkChoice.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunkChoice.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAsHI;;;OAGG;IACH,2BAHW,YAAY,GACV,eAAe,CAW3B;IA7HD;;OAEG;IACH,8DAEC;IAQD;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,WALW,MAAM,GAAC,OAAO,eAEd,SAAS,QAcnB;IAED;;;;OAIG;IACH,qBAJW,eAAe,GACb,SAAS,CAarB;IAkBD;;OAEG;IACH,gBAEC;IAWD;;OAEG;IACH,YAFW,eAAe,QAKzB;IAED;;OAEG;IACH,SAFa,eAAe,CAQ3B;IAsBL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;2BA3JY,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;0BAJjC,gBAAgB"}

package/src/shade/renderer/shader/compiler/CodeChunkChoice.js

@@ -0,0 +1,166 @@
+import { assert } from "../../../../core/assert.js";
+import { CodeChunk } from "./CodeChunk.js";
+
+/**
+ * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+
+/**
+ * The place in a chunk graph where a {@link ShaderSwitch} is decided: a chunk that stands for one
+ * alternative per value of the switch.
+ *
+ * Every alternative defines the same WGSL functions, so whatever depends on the choice is written
+ * once, whichever is linked. Each alternative is an ordinary {@link CodeChunk} with its own
+ * dependencies. {@link CodeChunk#specialize} replaces the choice with the alternative a
+ * {@link ShaderSwitchSet} selects, so the graph that is compiled has only that alternative's closure
+ * in it, and no choice.
+ *
+ * ```js
+ * export const chunk_shadowmap_sample_directional = CodeChunkChoice.from(SHADOW_DIRECTIONAL_TECHNIQUE);
+ * chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Cascades, chunk_shadowmap_sample_directional_cascades);
+ * chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Virtual, chunk_shadowmap_sample_directional_virtual);
+ * ```
+ *
+ * A chunk depends on the choice as on any chunk, however deep, and a shader learns that it depends on
+ * the switch from its graph ({@link CodeChunk#collectSwitches}).
+ */
+export class CodeChunkChoice extends CodeChunk {
+    /**
+     * @type {ShaderSwitch}
+     */
+    #switch;
+
+    /**
+     * @returns {ShaderSwitch}
+     */
+    get shader_switch() {
+        return this.#switch;
+    }
+
+    /**
+     * By the switch's value.
+     * @type {Map<number|boolean, CodeChunk>}
+     */
+    #alternatives = new Map();
+
+    /**
+     * Every alternative given so far, for walks that must see all of them.
+     * @returns {CodeChunk[]}
+     */
+    get alternatives() {
+        return Array.from(this.#alternatives.values());
+    }
+
+    /**
+     * @param {number|boolean} value one of the switch's values — a member of its enum, or `false`/`true` — not
+     * given an alternative yet
+     * @param {CodeChunk} alternative linked when the switch has this value. It may itself be a choice,
+     * of another switch.
+     */
+    add(value, alternative) {
+        assert.ok(this.#switch.is_value(value), `${value} is not a value of shader switch '${this.#switch.label}'`);
+        assert.notOk(this.#alternatives.has(value), `${this.#switch.name_of(value)} of '${this.#switch.label}' already has an alternative`);
+        assert.defined(alternative, 'alternative');
+        assert.equal(alternative.isCodeChunk, true, 'alternative.isCodeChunk !== true');
+
+        if (alternative === this || alternative.findDependencyRecursive(this)) {
+            throw new Error(`Circular dependency detected: ${this} -> ${alternative}`);
+        }
+
+        this.#alternatives.set(value, alternative);
+    }
+
+    /**
+     * @param {ShaderSwitchSet} set
+     * @returns {CodeChunk} the alternative `set` selects
+     * @throws {Error} when the selected value has no alternative here
+     */
+    alternative_for(set) {
+        const value = set.get(this.#switch);
+
+        const alternative = this.#alternatives.get(value);
+
+        if (alternative === undefined) {
+            throw new Error(`Shader switch '${this.#switch.label}' has no alternative for ${this.#switch.name_of(value)} at this choice`);
+        }
+
+        return alternative;
+    }
+
+    /**
+     * Every alternative counts, selected or not: a cycle through any of them is a cycle.
+     *
+     * @param {CodeChunk} chunk
+     * @returns {boolean}
+     */
+    findDependencyRecursive(chunk) {
+        for (const alternative of this.#alternatives.values()) {
+            if (alternative.equals(chunk) || alternative.findDependencyRecursive(chunk)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * A choice is linked as the alternative it stands for; see {@link CodeChunk#specialize}.
+     */
+    compile() {
+        throw new Error(`${this} cannot be compiled; specialize the graph it is in first`);
+    }
+
+    /**
+     * A choice is itself and nothing else: it has no text of its own to compare.
+     * @param {CodeChunk} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this === other;
+    }
+
+    /**
+     * @param {CodeChunkChoice} other
+     */
+    copy(other) {
+        this.#switch = other.#switch;
+        this.#alternatives = new Map(other.#alternatives);
+    }
+
+    /**
+     * @returns {CodeChunkChoice}
+     */
+    clone() {
+        const r = new CodeChunkChoice();
+
+        r.copy(this);
+
+        return r;
+    }
+
+    toString() {
+        return `choice of '${this.#switch.label}'`;
+    }
+
+    /**
+     * @param {ShaderSwitch} shader_switch
+     * @returns {CodeChunkChoice} with no alternatives yet; {@link add} one per value
+     */
+    static from(shader_switch) {
+        assert.defined(shader_switch, 'shader_switch');
+        assert.equal(shader_switch.isShaderSwitch, true, 'shader_switch.isShaderSwitch !== true');
+
+        const r = new CodeChunkChoice();
+
+        r.#switch = shader_switch;
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+CodeChunkChoice.prototype.isCodeChunkChoice = true;