@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/shader/chunk/texture/sample/chunk_texture3d_trilinear_corners.js

@@ -0,0 +1,159 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_uv3_to_texel_coordinate } from "../chunk_uv3_to_texel_coordinate.js";
+import { TEXTURE3D_TRILINEAR_CORNERS_STRUCT } from "../TEXTURE3D_TRILINEAR_CORNERS_STRUCT.js";
+import { chunk_interpolate_bilinear_f32 } from "./chunk_interpolate_bilinear_f32.js";
+
+/*
+ A trilinear tap on the first channel of a texture_3d<f32>, done by hand: eight textureLoads and
+ f32 weights, where a filtering sampler gives as little as 4 bits of weight. Two uses: the blend
+ (texture3d_trilinear_interpolate), and the eight corners themselves, which bound the blend and are
+ what a MacCormack limiter clamps its correction to.
+
+ The pieces, smallest first:
+ - texture3d_trilinear_corners_load: the eight texels at given lower and upper corners. A reader
+   with its own addressing (a toroidal window wraps each corner on its own) computes the corners
+   and calls this.
+ - texture3d_trilinear_corners: a region of the texture, a texel coordinate with texel c centred at
+   c, and the corners clamped to the region (clamp-to-edge; nothing outside the region is read).
+ - two concrete alignments over uv in [0, 1] of the region:
+   - corner-aligned: uv 0 is the first texel's centre and uv 1 the last's, uv outside [0, 1] the
+     edge. A distance field sampled at its own lattice points reads this way.
+   - cell-centred: texel c covers [c, c + 1) and is centred at uv (c + 0.5) / n. A grid of cells (a
+     fluid's) reads this way, as a linear sampler would.
+*/
+
+/**
+ * The eight texels at `lo` and `hi`, absolute texel coordinates of the lower and upper corner along
+ * each axis (equal on an axis held at an edge), and `weight`, the fraction from `lo` toward `hi`.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_load = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_corners_load(
+    source: texture_3d<f32>,
+    lo: vec3<u32>,
+    hi: vec3<u32>,
+    weight: vec3<f32>
+) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let c000 = textureLoad(source, lo, 0).r;
+    let c100 = textureLoad(source, vec3<u32>(hi.x, lo.y, lo.z), 0).r;
+    let c010 = textureLoad(source, vec3<u32>(lo.x, hi.y, lo.z), 0).r;
+    let c110 = textureLoad(source, vec3<u32>(hi.x, hi.y, lo.z), 0).r;
+
+    let c001 = textureLoad(source, vec3<u32>(lo.x, lo.y, hi.z), 0).r;
+    let c101 = textureLoad(source, vec3<u32>(hi.x, lo.y, hi.z), 0).r;
+    let c011 = textureLoad(source, vec3<u32>(lo.x, hi.y, hi.z), 0).r;
+    let c111 = textureLoad(source, hi, 0).r;
+
+    return ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(c000, c100, c010, c110),
+        vec4<f32>(c001, c101, c011, c111),
+        weight
+    );
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+    ]
+);
+
+/**
+ * The corners of a tap at a texel coordinate in a region of the texture: texel `c` of the region is
+ * centred at coordinate `c`, the region starts at `region_offset` and is `region_size` texels
+ * across. Each corner is clamped to the region on its own, so a coordinate past an edge reads the
+ * edge texel on both sides — clamp-to-edge, and nothing outside the region is ever loaded.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_corners(
+    source: texture_3d<f32>,
+    region_offset: vec3<u32>,
+    region_size: vec3<u32>,
+    texel: vec3<f32>
+) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    // floor before converting: a negative coordinate truncated toward zero would take the wrong
+    // lower corner, while the weight below would still be measured from the floor
+    let base = floor(texel);
+    let base_i = vec3<i32>(base);
+    let max_texel = vec3<i32>(region_size) - vec3<i32>(1);
+
+    let lo = vec3<u32>(clamp(base_i, vec3<i32>(0), max_texel));
+    let hi = vec3<u32>(clamp(base_i + vec3<i32>(1), vec3<i32>(0), max_texel));
+
+    return texture3d_trilinear_corners_load(source, region_offset + lo, region_offset + hi, texel - base);
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_texture3d_trilinear_corners_load,
+    ]
+);
+
+/**
+ * Corner-aligned: uv 0 is the centre of the region's first texel and uv 1 the centre of its last,
+ * so the texel coordinate is `uv · (size − 1)`; uv outside [0, 1] reads the edge. How the geometry
+ * SDF reads a tile of its atlas.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_corner_aligned = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_corners_corner_aligned(
+    source: texture_3d<f32>,
+    region_offset: vec3<u32>,
+    region_size: vec3<u32>,
+    uv: vec3<f32>
+) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let texel = saturate(uv) * vec3<f32>(region_size - vec3<u32>(1u));
+
+    return texture3d_trilinear_corners(source, region_offset, region_size, texel);
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_texture3d_trilinear_corners,
+    ]
+);
+
+/**
+ * Cell-centred: texel `c` covers `[c, c + 1)` and is centred at uv `(c + 0.5) / size`, so the
+ * texel coordinate is `uv · size − 0.5`; past the outer half texel the edge is held. How a linear
+ * sampler reads a texture, and how a grid of cells (a fluid's) is read.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_cell_centred = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_corners_cell_centred(
+    source: texture_3d<f32>,
+    region_offset: vec3<u32>,
+    region_size: vec3<u32>,
+    uv: vec3<f32>
+) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    return texture3d_trilinear_corners(source, region_offset, region_size, uv3_to_texel_coordinate(uv, region_size));
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_texture3d_trilinear_corners,
+        chunk_uv3_to_texel_coordinate,
+    ]
+);
+
+/**
+ * The trilinear blend of a tap's corners: bilinear across each z face, then along z.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_interpolate = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_interpolate(corners: ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}) -> f32 {
+    let lower = interpolate_bilinear_f32(corners.z0, corners.weight.xy);
+    let upper = interpolate_bilinear_f32(corners.z1, corners.weight.xy);
+
+    return mix(lower, upper, corners.weight.z);
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_interpolate_bilinear_f32,
+    ]
+);

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

@@ -1,3 +1,12 @@
+/**
+ * @typedef {import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
+ * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+/**
+ * A binding some chunk of a linked graph reads, and the first chunk in link order that declared it.
+ * @typedef {{resource: ShaderResourceDescriptor, chunk: CodeChunk}} CodeChunkResourceRequirement
+ */
 export class CodeChunk {
     /**
      * Special singleton
@@ -11,6 +20,13 @@ export class CodeChunk {
      * @returns {CodeChunk}
      */
     static from(code: string, dependencies?: CodeChunk[]): CodeChunk;
+    /**
+     * @param {CodeChunk} chunk
+     * @param {ShaderSwitchSet} set
+     * @param {Map<CodeChunk, CodeChunk>} memo what each chunk of this call's graph became
+     * @returns {CodeChunk}
+     */
+    static "__#77@#specialize"(chunk: CodeChunk, set: ShaderSwitchSet, memo: Map<CodeChunk, CodeChunk>): CodeChunk;
     get isCodeChunk(): boolean;
     /**
      *
@@ -28,6 +44,22 @@ export class CodeChunk {
      * @returns {boolean} true iff added, false if already present
      */
     addLanguageExtension(extension: string): boolean;
+    /**
+     * Declare that this chunk's own text reads the binding `resource` describes. A link collects these
+     * over the graph it links, as it does extensions ({@link compile}), and a shader checks each against
+     * the resources it binds, so a missing or mistyped binding is an error naming this chunk.
+     *
+     * @param {ShaderResourceDescriptor} resource a declaration, see {@link ShaderResourceDescriptor.uniform} and its siblings
+     * @returns {boolean} true iff added, false if already present
+     */
+    requireResource(resource: ShaderResourceDescriptor): boolean;
+    /**
+     * The bindings this chunk's own text declares it reads; see {@link requireResource}. Its
+     * dependencies declare their own.
+     *
+     * @returns {ShaderResourceDescriptor[]}
+     */
+    get required_resources(): import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor[];
     /**
      *
      * @param {CodeChunk} dependency
@@ -51,18 +83,42 @@ export class CodeChunk {
      * @returns {CodeChunk[]}
      */
     collectDependencies(): CodeChunk[];
+    /**
+     * 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(): ShaderSwitch[];
+    /**
+     * 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: ShaderSwitchSet): CodeChunk;
     /**
      * Unroll all dependencies, excluding this chunk, into a single list where all dependencies are in the correct order
      * @return {CodeChunk[]}
      */
     coalesceDependencies(): CodeChunk[];
     /**
-     * @returns {{text:string, extensions: string[], language_extensions: string[]}}
+     * `resources` holds every binding a chunk of the graph declared it reads ({@link requireResource}),
+     * once per declaration, with the first chunk in link order that declared it.
+     *
+     * @returns {{text:string, extensions: string[], language_extensions: string[], resources: CodeChunkResourceRequirement[]}}
      */
     compile(): {
         text: string;
         extensions: string[];
         language_extensions: string[];
+        resources: CodeChunkResourceRequirement[];
     };
     toString(): string;
     /**
@@ -88,5 +144,15 @@ export class CodeChunk {
     equals(other: CodeChunk): boolean;
     #private;
 }
+export type ShaderResourceDescriptor = import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor;
+export type ShaderSwitch = import("./ShaderSwitch.js").ShaderSwitch;
+export type ShaderSwitchSet = import("./ShaderSwitchSet.js").ShaderSwitchSet;
+/**
+ * A binding some chunk of a linked graph reads, and the first chunk in link order that declared it.
+ */
+export type CodeChunkResourceRequirement = {
+    resource: ShaderResourceDescriptor;
+    chunk: CodeChunk;
+};
 import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 //# sourceMappingURL=CodeChunk.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"CodeChunk.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunk.js"],"names":[],"mappings":"AAOA;IAMI;;;OAGG;IACH,cAFU,SAAS,SAAS,CAAC,CAEoB;IAkGjD;;;;;OAKG;IACH,kBAHW,MAAM,iBADN,SAAS,EAAE,GAET,SAAS,CAqBrB;IAnID,2BAEC;IAcD;;;OAGG;IACH,mBAEC;IAeD;;;;OAIG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAMnB;IAkBD;;;OAGG;IACH,gCAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;OAIG;IACH,0BAHW,SAAS,GACP,OAAO,CAmBnB;IAqCD;;;;OAIG;IACH,6CAHW,IAAI,SAAS,CAAC,GACZ,OAAO,CAgBnB;IAED;;;;OAIG;IACH,+BAHW,SAAS,GACP,OAAO,CAqBnB;IAED;;;OAGG;IACH,uBAFa,SAAS,EAAE,CAoCvB;IAED;;;OAGG;IACH,wBAFY,SAAS,EAAE,CAgDtB;IAED;;OAEG;IACH,WAFa;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,mBAAmB,EAAE,MAAM,EAAE,CAAA;KAAC,CA4C9E;IAED,mBAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,YAFW,SAAS,QAOnB;IAED;;;OAGG;IACH,SAFY,SAAS,CAQpB;IAED;;;;OAIG;IACH,cAHW,SAAS,GACP,OAAO,CAWnB;;CACJ;oCAtXmC,4CAA4C"}
+{"version":3,"file":"CodeChunk.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunk.js"],"names":[],"mappings":"AAMA;;;;GAIG;AAEH;;;GAGG;AAGH;IAMI;;;OAGG;IACH,cAFU,SAAS,SAAS,CAAC,CAEoB;IAiIjD;;;;;OAKG;IACH,kBAHW,MAAM,iBADN,SAAS,EAAE,GAET,SAAS,CAqBrB;IA+JD;;;;;OAKG;IACH,kCALW,SAAS,OACT,eAAe,QACf,IAAI,SAAS,EAAE,SAAS,CAAC,GACvB,SAAS,CAuDrB;IA5XD,2BAEC;IAcD;;;OAGG;IACH,mBAEC;IAeD;;;;OAIG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAMnB;IAkBD;;;OAGG;IACH,gCAHW,MAAM,GACJ,OAAO,CAMnB;IAQD;;;;;;;OAOG;IACH,0BAHW,wBAAwB,GACtB,OAAO,CAOnB;IAED;;;;;OAKG;IACH,uGAEC;IAED;;;;OAIG;IACH,0BAHW,SAAS,GACP,OAAO,CAmBnB;IAqCD;;;;OAIG;IACH,6CAHW,IAAI,SAAS,CAAC,GACZ,OAAO,CAgBnB;IAED;;;;OAIG;IACH,+BAHW,SAAS,GACP,OAAO,CAqBnB;IAED;;;OAGG;IACH,uBAFa,SAAS,EAAE,CAuCvB;IAED;;;;;;OAMG;IACH,mBAFa,YAAY,EAAE,CA0C1B;IAED;;;;;;;;;;OAUG;IACH,gBAHW,eAAe,GACb,SAAS,CAOrB;IA+DD;;;OAGG;IACH,wBAFY,SAAS,EAAE,CAgDtB;IAED;;;;;OAKG;IACH,WAFa;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,mBAAmB,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,4BAA4B,EAAE,CAAA;KAAC,CAiEzH;IAED,mBAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,YAFW,SAAS,QAQnB;IAED;;;OAGG;IACH,SAFY,SAAS,CAQpB;IAED;;;;OAIG;IACH,cAHW,SAAS,GACP,OAAO,CAgBnB;;CACJ;uCA9jBY,OAAO,yCAAyC,EAAE,wBAAwB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;;;;2CAK9C;IAAC,QAAQ,EAAE,wBAAwB,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAC;oCAV/B,4CAA4C"}

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

@@ -4,6 +4,17 @@ import { isArrayEqual } from "../../../../core/collection/array/isArrayEqual.js"
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 
+/**
+ * @typedef {import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
+ * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+
+/**
+ * A binding some chunk of a linked graph reads, and the first chunk in link order that declared it.
+ * @typedef {{resource: ShaderResourceDescriptor, chunk: CodeChunk}} CodeChunkResourceRequirement
+ */
+
 
 export class CodeChunk {
 
@@ -81,6 +92,37 @@ export class CodeChunk {
         return array_push_if_unique(this.#language_extensions, extension);
     }
 
+    /**
+     * Bindings this chunk's own text reads.
+     * @type {ShaderResourceDescriptor[]}
+     */
+    #resources = [];
+
+    /**
+     * Declare that this chunk's own text reads the binding `resource` describes. A link collects these
+     * over the graph it links, as it does extensions ({@link compile}), and a shader checks each against
+     * the resources it binds, so a missing or mistyped binding is an error naming this chunk.
+     *
+     * @param {ShaderResourceDescriptor} resource a declaration, see {@link ShaderResourceDescriptor.uniform} and its siblings
+     * @returns {boolean} true iff added, false if already present
+     */
+    requireResource(resource) {
+        assert.defined(resource, 'resource');
+        assert.equal(resource.isShaderResourceDescriptor, true, 'resource.isShaderResourceDescriptor !== true');
+
+        return array_push_if_unique(this.#resources, resource);
+    }
+
+    /**
+     * The bindings this chunk's own text declares it reads; see {@link requireResource}. Its
+     * dependencies declare their own.
+     *
+     * @returns {ShaderResourceDescriptor[]}
+     */
+    get required_resources() {
+        return this.#resources;
+    }
+
     /**
      *
      * @param {CodeChunk} dependency
@@ -206,6 +248,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 +272,134 @@ 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();
+            r.#resources = chunk.#resources.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[]}
@@ -280,7 +453,10 @@ export class CodeChunk {
     }
 
     /**
-     * @returns {{text:string, extensions: string[], language_extensions: string[]}}
+     * `resources` holds every binding a chunk of the graph declared it reads ({@link requireResource}),
+     * once per declaration, with the first chunk in link order that declared it.
+     *
+     * @returns {{text:string, extensions: string[], language_extensions: string[], resources: CodeChunkResourceRequirement[]}}
      */
     compile() {
 
@@ -290,6 +466,16 @@ export class CodeChunk {
         const extension_hash = {};
         const language_extension_hash = {};
 
+        /**
+         * @type {CodeChunkResourceRequirement[]}
+         */
+        const resources = [];
+
+        /**
+         * @type {Set<ShaderResourceDescriptor>}
+         */
+        const required = new Set();
+
         /**
          *
          * @type {string[]}
@@ -311,6 +497,16 @@ export class CodeChunk {
             for (let j = 0; j < lang_ext.length; j++) {
                 language_extension_hash[lang_ext[j]] = true;
             }
+
+            const res = chunk.#resources;
+            for (let j = 0; j < res.length; j++) {
+                const resource = res[j];
+
+                if (!required.has(resource)) {
+                    required.add(resource);
+                    resources.push({ resource, chunk });
+                }
+            }
         }
 
         // Enable required extensions
@@ -322,7 +518,8 @@ export class CodeChunk {
         return {
             text,
             extensions,
-            language_extensions
+            language_extensions,
+            resources
         };
     }
 
@@ -347,6 +544,7 @@ export class CodeChunk {
         this.#dependencies = other.#dependencies.slice();
         this.#extensions = other.#extensions.slice();
         this.#language_extensions = other.#language_extensions.slice();
+        this.#resources = other.#resources.slice();
     }
 
     /**
@@ -371,6 +569,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,76 @@
+/**
+ * @typedef {import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
+ * @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 ShaderResourceDescriptor = import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor;
+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;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA+HI;;;OAGG;IACH,2BAHW,YAAY,GACV,eAAe,CAW3B;IAtID;;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;IA2BD;;OAEG;IACH,gBAEC;IAWD;;OAEG;IACH,YAFW,eAAe,QAKzB;IAED;;OAEG;IACH,SAFa,eAAe,CAQ3B;IAsBL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;uCArKY,OAAO,yCAAyC,EAAE,wBAAwB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;0BALjC,gBAAgB"}