@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/shader/ComputeShader.d.ts

@@ -46,6 +46,17 @@ export class ComputeShader {
      * @returns {ShaderDescriptor}
      */
     get descriptor(): ShaderDescriptor;
+    /**
+     * This shader as `set` makes it — see {@link ShaderDescriptor#variant}. Sets that agree on the
+     * descriptor's switches get the one shader, and the set with all of them `0` gets this one.
+     *
+     * Every variant has this shader's `@workgroup_size`: a switch changes what a pass computes, never
+     * how it is dispatched, and a dispatch sized by one variant must fit them all.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {ComputeShader}
+     */
+    variant(set: ShaderSwitchSet): ComputeShader;
     /**
      *
      * @param {Object} options
@@ -115,6 +126,27 @@ export class ComputeShader {
         group_count_y?: number;
         group_count_z?: number;
     }): void;
+    /**
+     * Like {@link dispatch}, into a compute pass the caller has open and ends, so that a run of
+     * dispatches shares one pass. A dispatch sees the writes of the dispatches before it in the
+     * same pass.
+     *
+     * @param {Object} options
+     * @param {ShadeGPUCommandContext} options.encoder the context `pass` was begun on
+     * @param {ShadeGPUComputePassEncoder} options.pass
+     * @param {Object} options.bindings
+     * @param {number} [options.group_count_x]
+     * @param {number} [options.group_count_y]
+     * @param {number} [options.group_count_z]
+     */
+    dispatchInPass({ encoder, pass, bindings, group_count_x, group_count_y, group_count_z, }: {
+        encoder: ShadeGPUCommandContext;
+        pass: ShadeGPUComputePassEncoder;
+        bindings: any;
+        group_count_x?: number;
+        group_count_y?: number;
+        group_count_z?: number;
+    }): void;
     /**
      * Dispatch with the workgroup counts a GPU pass wrote into `command`.
      *
@@ -141,6 +173,7 @@ export class ComputeShader {
     readonly isComputeShader: boolean;
     #private;
 }
+export type ShaderSwitchSet = import("./compiler/ShaderSwitchSet.js").ShaderSwitchSet;
 import { ComputePipelineDescriptor } from "../../descriptor/pipeline/compute/ComputePipelineDescriptor.js";
 import { ShaderDescriptor } from "./ShaderDescriptor.js";
 //# sourceMappingURL=ComputeShader.d.ts.map

package/src/shade/renderer/shader/ComputeShader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComputeShader.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ComputeShader.js"],"names":[],"mappings":"AAMA;IA0GI;;;;;;;;;;OAUG;IACH;QAR4B,KAAK,GAAtB,MAAM;QAC+B,SAAS;QAC3B,IAAI;QACJ,UAAU,GAA7B,MAAM,EAAE;QAGN,aAAa,CAuBzB;IA5DD;;;OAGG;IACH,wBAFW,gBAAgB,EAwB1B;IAhFD;;;OAGG;IACH,0CAEC;IAgBD;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,mCAEC;IAgED;;;;;;OAMG;IACH;QAJ2C,OAAO;QACvB,QAAQ;mCA8BlC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH;QAP2C,OAAO;QACvB,QAAQ;QACP,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;aAgChB;IAED;;;;;;;;;;;;OAYG;IACH;QAL2C,OAAO;QACvB,QAAQ;QACR,aAAa,EAA7B,MAAM;aAsBhB;IAED;;;;;;;;OAQG;IACH;QAN2C,OAAO;QACvB,QAAQ;QACP,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;aA2ChB;IAED;;;;;;;;;;;;OAYG;IACH;QAL2C,OAAO;QACpB,OAAO;QACV,QAAQ;QACP,cAAc,GAA/B,MAAM;aAwChB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;;CANtC;0CA/WyC,gEAAgE;iCACzE,uBAAuB"}
+{"version":3,"file":"ComputeShader.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ComputeShader.js"],"names":[],"mappings":"AAUA;IA2JI;;;;;;;;;;OAUG;IACH;QAR4B,KAAK,GAAtB,MAAM;QAC+B,SAAS;QAC3B,IAAI;QACJ,UAAU,GAA7B,MAAM,EAAE;QAGN,aAAa,CAuBzB;IA5DD;;;OAGG;IACH,wBAFW,gBAAgB,EAwB1B;IAjID;;;OAGG;IACH,0CAEC;IAgBD;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,mCAEC;IAQD;;;;;;;;;OASG;IACH,aAHW,eAAe,GACb,aAAa,CAiCzB;IAgED;;;;;;OAMG;IACH;QAJ2C,OAAO;QACvB,QAAQ;mCA8BlC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH;QAP2C,OAAO;QACvB,QAAQ;QACP,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;aAgChB;IAED;;;;;;;;;;;;OAYG;IACH;QAL2C,OAAO;QACvB,QAAQ;QACR,aAAa,EAA7B,MAAM;aAsBhB;IAED;;;;;;;;OAQG;IACH;QAN2C,OAAO;QACvB,QAAQ;QACP,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;aA2ChB;IAED;;;;;;;;;;;;OAYG;IACH;QAP2C,OAAO;QACH,IAAI;QACxB,QAAQ;QACP,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;aAyChB;IAED;;;;;;;;;;;;OAYG;IACH;QAL2C,OAAO;QACpB,OAAO;QACV,QAAQ;QACP,cAAc,GAA/B,MAAM;aAwChB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;;CANtC;8BAtdY,OAAO,+BAA+B,EAAE,eAAe;0CAJ1B,gEAAgE;iCACzE,uBAAuB"}

package/src/shade/renderer/shader/ComputeShader.js

@@ -2,6 +2,10 @@ import { assert } from "../../../core/assert.js";
 import { ComputePipelineDescriptor } from "../../descriptor/pipeline/compute/ComputePipelineDescriptor.js";
 import { ShaderDescriptor } from "./ShaderDescriptor.js";
 
+/**
+ * @typedef {import("./compiler/ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+
 const VALIDATION_ENABLED = true;
 
 export class ComputeShader {
@@ -82,6 +86,55 @@ export class ComputeShader {
         return this.#descriptor;
     }
 
+    /**
+     * This shader's variants, by every set asked for and by the descriptor each was built from.
+     * @type {Map<ShaderSwitchSet|ShaderDescriptor, ComputeShader>}
+     */
+    #variants = new Map();
+
+    /**
+     * This shader as `set` makes it — see {@link ShaderDescriptor#variant}. Sets that agree on the
+     * descriptor's switches get the one shader, and the set with all of them `0` gets this one.
+     *
+     * Every variant has this shader's `@workgroup_size`: a switch changes what a pass computes, never
+     * how it is dispatched, and a dispatch sized by one variant must fit them all.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {ComputeShader}
+     */
+    variant(set) {
+        let r = this.#variants.get(set);
+
+        if (r !== undefined) {
+            return r;
+        }
+
+        const descriptor = this.#descriptor.variant(set);
+
+        if (descriptor === this.#descriptor) {
+            r = this;
+        } else {
+            r = this.#variants.get(descriptor);
+
+            if (r === undefined) {
+                r = new ComputeShader(descriptor);
+
+                const own = this.#group_size;
+                const theirs = r.#group_size;
+
+                if (own[0] !== theirs[0] || own[1] !== theirs[1] || own[2] !== theirs[2]) {
+                    throw new Error(`ComputeShader '${descriptor.label}' has @workgroup_size(${theirs}), and '${this.#descriptor.label}' has (${own}); the variants of a shader dispatch alike`);
+                }
+
+                this.#variants.set(descriptor, r);
+            }
+        }
+
+        this.#variants.set(set, r);
+
+        return r;
+    }
+
     /**
      *
      * @param {ShaderDescriptor} descriptor
@@ -314,6 +367,60 @@ export class ComputeShader {
 
     }
 
+    /**
+     * Like {@link dispatch}, into a compute pass the caller has open and ends, so that a run of
+     * dispatches shares one pass. A dispatch sees the writes of the dispatches before it in the
+     * same pass.
+     *
+     * @param {Object} options
+     * @param {ShadeGPUCommandContext} options.encoder the context `pass` was begun on
+     * @param {ShadeGPUComputePassEncoder} options.pass
+     * @param {Object} options.bindings
+     * @param {number} [options.group_count_x]
+     * @param {number} [options.group_count_y]
+     * @param {number} [options.group_count_z]
+     */
+    dispatchInPass({
+                       encoder,
+                       pass,
+                       bindings,
+                       group_count_x = 1,
+                       group_count_y = 1,
+                       group_count_z = 1,
+                   }) {
+
+        assert.defined(encoder, 'encoder');
+        assert.defined(pass, 'pass');
+        assert.defined(bindings, 'bindings');
+
+        assert.isNonNegativeInteger(group_count_x, 'group_count_x');
+        assert.isNonNegativeInteger(group_count_y, 'group_count_y');
+        assert.isNonNegativeInteger(group_count_z, 'group_count_z');
+
+        assert.greaterThanOrEqual(group_count_x, 1, 'must be at least 1');
+        assert.greaterThanOrEqual(group_count_y, 1, 'must be at least 1');
+        assert.greaterThanOrEqual(group_count_z, 1, 'must be at least 1');
+
+        const device = encoder.device;
+
+        if (VALIDATION_ENABLED && device !== this.#validated_device) {
+            this.#descriptor.validate_against_device(device);
+
+            this.#validated_device = device;
+        }
+
+        const resources = this.#descriptor.resources;
+
+        encoder.bindComputePipeline({
+            pass,
+            pipeline: this.#pipeline,
+            bindings: resources.generateBindings(bindings, encoder),
+            immediate: encoder.writeImmediate(resources, bindings),
+        });
+
+        pass.dispatchWorkgroups(group_count_x, group_count_y, group_count_z);
+    }
+
     /**
      * Dispatch with the workgroup counts a GPU pass wrote into `command`.
      *

package/src/shade/renderer/shader/ImageShader.d.ts

@@ -15,13 +15,11 @@ export class ImageShader {
         targets: ColorTargetState[];
         depthStencil?: DepthStencilState;
     }): ImageShader;
-    /**
-     *
-     * @param {ShaderDescriptor} descriptor
-     * @param {(ColorTargetState|{clearValue?:number[]})[]} [targets]
-     * @param {DepthStencilState} [depthStencil]
-     */
-    constructor({ descriptor, targets, depthStencil, }: ShaderDescriptor);
+    constructor({ descriptor, targets, depthStencil, }: {
+        descriptor: any;
+        targets?: any[];
+        depthStencil: any;
+    });
     /**
      *
      * @returns {ShaderDescriptor}
@@ -36,12 +34,31 @@ export class ImageShader {
      *
      * @returns {RenderPipelineDescriptor}
      */
-    get pipeline(): RenderPipelineDescriptor;
+    get pipeline(): import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+    /**
+     * The pipeline {@link draw} uses when it draws into attachments of these formats: {@link pipeline}
+     * itself when they are the formats it declares, otherwise a copy rewritten for them
+     * (rgba8unorm -> bgra8unorm, say). Offer this, not {@link pipeline}, for a pass that draws into
+     * a target it was handed — what an offer compiles is otherwise a variant no frame draws with.
+     *
+     * @param {GPUTextureFormat[]} color_formats one per fragment target
+     * @returns {RenderPipelineDescriptor}
+     */
+    pipeline_for(color_formats: GPUTextureFormat[]): RenderPipelineDescriptor;
     /**
      *
      * @returns {boolean}
      */
     get isImageShader(): boolean;
+    /**
+     * This shader as `set` makes it — see {@link ShaderDescriptor#variant}. The same targets and depth
+     * state, the body specialized. Sets that agree on the descriptor's switches get the one shader, and
+     * the set with all of them `0` gets this one.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {ImageShader}
+     */
+    variant(set: ShaderSwitchSet): ImageShader;
     /**
      * Note the absence of depth target, image shader is a full-screen pass, so depth is not used.
      *
@@ -55,4 +72,6 @@ export class ImageShader {
     draw({ encoder, bindings, colorAttachments, depthStencilAttachment, color_formats, viewport }: ShadeGPUCommandContext): void;
     #private;
 }
+export type RenderPipelineDescriptor = import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export type ShaderSwitchSet = import("./compiler/ShaderSwitchSet.js").ShaderSwitchSet;
 //# sourceMappingURL=ImageShader.d.ts.map

package/src/shade/renderer/shader/ImageShader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImageShader.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ImageShader.js"],"names":[],"mappings":"AAQA;;GAEG;AACH;IAiHI;;;;;;;OAOG;IACH;QALqC,UAAU;QACR,OAAO,EAAnC,kBAAkB;QACU,YAAY;QACtC,WAAW,CAavB;IAnFD;;;;;OAKG;IACH,sEAuDC;IAxGD;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,cAFU,MAAM,EAAE,EAAE,CAEF;IAelB;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,6BAEC;IAuFD;;;;;;;;;OASG;IACH,6HA0EC;;CACJ"}
+{"version":3,"file":"ImageShader.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ImageShader.js"],"names":[],"mappings":"AAaA;;GAEG;AACH;IAiLI;;;;;;;OAOG;IACH;QALqC,UAAU;QACR,OAAO,EAAnC,kBAAkB;QACU,YAAY;QACtC,WAAW,CAavB;IA9ED;;;;OAwDC;IAxKD;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,cAFU,MAAM,EAAE,EAAE,CAEF;IAelB;;;OAGG;IACH,gHAEC;IAED;;;;;;;;OAQG;IACH,4BAHW,kBAAkB,GAChB,wBAAwB,CAIpC;IAED;;;OAGG;IACH,6BAEC;IAoBD;;;;;;;OAOG;IACH,aAHW,eAAe,GACb,WAAW,CA8BvB;IAkFD;;;;;;;;;OASG;IACH,6HA0EC;;CACJ;uCApSY,OAAO,8DAA8D,EAAE,wBAAwB;8BAC/F,OAAO,+BAA+B,EAAE,eAAe"}

package/src/shade/renderer/shader/ImageShader.js

@@ -4,6 +4,11 @@ import {
 } from "../../device/pipeline/rp_validate_and_rewrite_for_color_attachments.js";
 import { create_full_quad_pipeline_descriptor } from "./fullscreen/create_full_quad_pipeline_descriptor.js";
 
+/**
+ * @typedef {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("./compiler/ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+
 const VALIDATION_ENABLED = true;
 
 /**
@@ -50,6 +55,19 @@ export class ImageShader {
         return this.#pipeline
     }
 
+    /**
+     * The pipeline {@link draw} uses when it draws into attachments of these formats: {@link pipeline}
+     * itself when they are the formats it declares, otherwise a copy rewritten for them
+     * (rgba8unorm -> bgra8unorm, say). Offer this, not {@link pipeline}, for a pass that draws into
+     * a target it was handed — what an offer compiles is otherwise a variant no frame draws with.
+     *
+     * @param {GPUTextureFormat[]} color_formats one per fragment target
+     * @returns {RenderPipelineDescriptor}
+     */
+    pipeline_for(color_formats) {
+        return rp_validate_and_rewrite_for_color_attachments(this.#pipeline, color_formats);
+    }
+
     /**
      *
      * @returns {boolean}
@@ -64,6 +82,56 @@ export class ImageShader {
      * @param {(ColorTargetState|{clearValue?:number[]})[]} [targets]
      * @param {DepthStencilState} [depthStencil]
      */
+    /**
+     * What the constructor was given, so that {@link variant} can build its siblings the same way.
+     * @type {{targets: (ColorTargetState|{clearValue?:number[]})[], depthStencil: (DepthStencilState|undefined)}}
+     */
+    #construction;
+
+    /**
+     * This shader's variants, by every set asked for and by the descriptor each was built from.
+     * @type {Map<ShaderSwitchSet|ShaderDescriptor, ImageShader>}
+     */
+    #variants = new Map();
+
+    /**
+     * This shader as `set` makes it — see {@link ShaderDescriptor#variant}. The same targets and depth
+     * state, the body specialized. Sets that agree on the descriptor's switches get the one shader, and
+     * the set with all of them `0` gets this one.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {ImageShader}
+     */
+    variant(set) {
+        let r = this.#variants.get(set);
+
+        if (r !== undefined) {
+            return r;
+        }
+
+        const descriptor = this.#descriptor.variant(set);
+
+        if (descriptor === this.#descriptor) {
+            r = this;
+        } else {
+            r = this.#variants.get(descriptor);
+
+            if (r === undefined) {
+                r = new ImageShader({
+                    descriptor,
+                    targets: this.#construction.targets,
+                    depthStencil: this.#construction.depthStencil,
+                });
+
+                this.#variants.set(descriptor, r);
+            }
+        }
+
+        this.#variants.set(set, r);
+
+        return r;
+    }
+
     constructor({
                     descriptor,
                     targets = [],
@@ -71,6 +139,7 @@ export class ImageShader {
                 }) {
 
         this.#descriptor = descriptor;
+        this.#construction = { targets, depthStencil };
 
         // process optional clearValue parameter
         for (let i = 0; i < targets.length; i++) {
@@ -187,7 +256,7 @@ export class ImageShader {
         if (color_formats !== undefined) {
             // potentially rewrite the pipeline to be compatible with output formats
             // example: rgba8unorm -> rgba16float
-            pipeline = rp_validate_and_rewrite_for_color_attachments(pipeline, color_formats);
+            pipeline = this.pipeline_for(color_formats);
         }
 
         const pass = encoder.constructRenderPass({

package/src/shade/renderer/shader/ShaderDescriptor.d.ts

@@ -21,6 +21,13 @@ export class ShaderDescriptor {
      * @return {ShaderResourceSetDescriptor}
      */
     get resources(): ShaderResourceSetDescriptor;
+    /**
+     * The chunk graph this shader links, before its resources' declarations are added at link. It may
+     * still hold choices: `body.specialize(set)` is the graph {@link variant} links for `set`.
+     *
+     * @returns {CodeChunk}
+     */
+    get body(): CodeChunk;
     /**
      *
      * @return {string|GPUFeatureName[]}
@@ -32,7 +39,23 @@ export class ShaderDescriptor {
      */
     get source(): string;
     /**
+     * The switches this shader depends on: every one its body's chunk graph decides somewhere. Empty
+     * for a shader with one variant.
+     *
+     * @returns {ShaderSwitch[]}
+     */
+    get switches(): import("./compiler/ShaderSwitch.js").ShaderSwitch[];
+    /**
+     * This shader as `set` makes it: the same resources, and the body specialized to the switches'
+     * values, so it holds no choice. Sets that agree on {@link switches} get the one variant, and the
+     * set with every one of them `0` gets this descriptor, whose {@link source} is that variant's.
      *
+     * @param {ShaderSwitchSet} set values for the switches; those this shader does not depend on are ignored
+     * @returns {ShaderDescriptor}
+     */
+    variant(set: ShaderSwitchSet): ShaderDescriptor;
+    /**
+     * The source of the variant with every switch `0`; see {@link variant} for the others.
      * @return {string}
      */
     compile(): string;
@@ -50,6 +73,10 @@ export class ShaderDescriptor {
     validate_gpu_features(device: GPUDevice): boolean;
     #private;
 }
+export type CodeChunkResourceRequirement = import("./compiler/CodeChunk.js").CodeChunkResourceRequirement;
+export type ShaderSwitch = import("./compiler/ShaderSwitch.js").ShaderSwitch;
+export type ShaderResourceDescriptor = import("./resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor;
 import { ShaderResourceSetDescriptor } from "./resource/ShaderResourceSetDescriptor.js";
 import { CodeChunk } from "./compiler/CodeChunk.js";
+import { ShaderSwitchSet } from "./compiler/ShaderSwitchSet.js";
 //# sourceMappingURL=ShaderDescriptor.d.ts.map

package/src/shade/renderer/shader/ShaderDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ShaderDescriptor.js"],"names":[],"mappings":"AAIA;IA+JI;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACgC,SAAS,GAA/C,2BAA2B;QACR,IAAI,EAAvB,SAAS;yBAsBnB;IAnLD;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAaD;;;OAGG;IACH,0CAEC;IAQD;;;OAGG;IACH,qBAQC;IAED;;;OAGG;IACH,WAFY,MAAM,CAiCjB;IAED;;;OAGG;IACH,iDA6BC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA8BJ;4CA7L2C,2CAA2C;0BAD7D,yBAAyB"}
+{"version":3,"file":"ShaderDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ShaderDescriptor.js"],"names":[],"mappings":"AA2EA;IA2OI;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACgC,SAAS,GAA/C,2BAA2B;QACR,IAAI,EAAvB,SAAS;yBAuBnB;IAhQD;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAOD;;;;;OAKG;IACH,sBAEC;IAQD;;;OAGG;IACH,0CAEC;IAQD;;;OAGG;IACH,qBAQC;IAOD;;;;;OAKG;IACH,oEAMC;IASD;;;;;;;OAOG;IACH,aAHW,eAAe,GACb,gBAAgB,CA8B5B;IAED;;;OAGG;IACH,WAFY,MAAM,CAmCjB;IAED;;;OAGG;IACH,iDA6BC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA+BJ;2CA7UY,OAAO,yBAAyB,EAAE,4BAA4B;2BAC9D,OAAO,4BAA4B,EAAE,YAAY;uCACjD,OAAO,wCAAwC,EAAE,wBAAwB;4CAL1C,2CAA2C;0BAF7D,yBAAyB;gCACnB,+BAA+B"}

package/src/shade/renderer/shader/ShaderDescriptor.js

@@ -1,7 +1,78 @@
 import { assert } from "../../../core/assert.js";
 import { CodeChunk } from "./compiler/CodeChunk.js";
+import { ShaderSwitchSet } from "./compiler/ShaderSwitchSet.js";
 import { ShaderResourceSetDescriptor } from "./resource/ShaderResourceSetDescriptor.js";
 
+/**
+ * @typedef {import("./compiler/CodeChunk.js").CodeChunkResourceRequirement} CodeChunkResourceRequirement
+ * @typedef {import("./compiler/ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
+ */
+
+/**
+ * A chunk's name for an error: the first thing its text declares, as a reader searching for it would type it.
+ *
+ * @param {CodeChunk} chunk
+ * @returns {string}
+ */
+function chunk_name(chunk) {
+    const match = /\b(?:fn|struct|const|alias|override|var(?:<[^>]*>)?)\s+([A-Za-z_][A-Za-z0-9_]*)/.exec(chunk.text);
+
+    return match === null ? `a chunk beginning '${chunk.text.trim().slice(0, 40)}'` : `'${match[1]}'`;
+}
+
+/**
+ * How a binding reads in WGSL terms, for an error.
+ *
+ * @param {ShaderResourceDescriptor} resource
+ * @returns {string}
+ */
+function describe_resource(resource) {
+    const member = resource.member_descriptor;
+
+    if (resource.buffer_type !== undefined) {
+        return `a ${member.type} buffer of ${resource.buffer_type.wgsl_ref}`;
+    }
+
+    if (member.sampleType !== undefined) {
+        return `a ${member.multisampled ? "multisampled " : ""}${member.viewDimension} ${member.sampleType} texture`;
+    }
+
+    if (member.format !== undefined) {
+        return `a ${member.viewDimension} ${member.format} ${member.access} storage texture`;
+    }
+
+    return `a ${member.type} sampler`;
+}
+
+/**
+ * Throw unless `resources` binds every binding the linked graph declared it reads, each as the declaration
+ * says. A shader's own resources are the one place its bindings are written down, so a chunk that reads
+ * one the shader lacks is the shader's error, named here rather than as an unresolved identifier.
+ *
+ * @param {CodeChunkResourceRequirement[]} required
+ * @param {ShaderResourceSetDescriptor} resources
+ * @param {string} label the shader's
+ */
+function check_required_resources(required, resources, label) {
+    for (let i = 0; i < required.length; i++) {
+        const { resource, chunk } = required[i];
+
+        const bound = resources.getResourceByName(resource.name);
+
+        if (bound === undefined) {
+            throw new Error(`${chunk_name(chunk)} reads '${resource.name}', which '${label}' does not bind`);
+        }
+
+        if (!resource.isSatisfiedBy(bound)) {
+            throw new Error(
+                `${chunk_name(chunk)} reads '${resource.name}' as ${describe_resource(resource)},`
+                + ` which '${label}' binds as ${describe_resource(bound)}`
+            );
+        }
+    }
+}
+
 export class ShaderDescriptor {
     /**
      * Human-readable label
@@ -35,6 +106,16 @@ export class ShaderDescriptor {
      */
     #body;
 
+    /**
+     * The chunk graph this shader links, before its resources' declarations are added at link. It may
+     * still hold choices: `body.specialize(set)` is the graph {@link variant} links for `set`.
+     *
+     * @returns {CodeChunk}
+     */
+    get body() {
+        return this.#body;
+    }
+
     /**
      *
      * @type {string|GPUFeatureName[]}
@@ -70,16 +151,82 @@ export class ShaderDescriptor {
     }
 
     /**
+     * @type {ShaderSwitch[]|undefined}
+     */
+    #switches = undefined;
+
+    /**
+     * The switches this shader depends on: every one its body's chunk graph decides somewhere. Empty
+     * for a shader with one variant.
      *
+     * @returns {ShaderSwitch[]}
+     */
+    get switches() {
+        if (this.#switches === undefined) {
+            this.#switches = Object.freeze(this.#body.collectSwitches());
+        }
+
+        return this.#switches;
+    }
+
+    /**
+     * Variants made so far, by every set asked for. Sets are interned, so a frame asking again with
+     * the same one finds its variant with one lookup and allocates nothing.
+     * @type {Map<ShaderSwitchSet, ShaderDescriptor>}
+     */
+    #variants = new Map();
+
+    /**
+     * This shader as `set` makes it: the same resources, and the body specialized to the switches'
+     * values, so it holds no choice. Sets that agree on {@link switches} get the one variant, and the
+     * set with every one of them `0` gets this descriptor, whose {@link source} is that variant's.
+     *
+     * @param {ShaderSwitchSet} set values for the switches; those this shader does not depend on are ignored
+     * @returns {ShaderDescriptor}
+     */
+    variant(set) {
+        let r = this.#variants.get(set);
+
+        if (r !== undefined) {
+            return r;
+        }
+
+        const own = set.restricted_to(this.switches);
+
+        if (own === ShaderSwitchSet.EMPTY) {
+            r = this;
+        } else {
+            r = this.#variants.get(own);
+
+            if (r === undefined) {
+                r = ShaderDescriptor.from({
+                    label: `${this.#label} [${own}]`,
+                    resources: this.#resources,
+                    body: this.#body.specialize(own),
+                });
+
+                this.#variants.set(own, r);
+            }
+        }
+
+        this.#variants.set(set, r);
+
+        return r;
+    }
+
+    /**
+     * The source of the variant with every switch `0`; see {@link variant} for the others.
      * @return {string}
      */
     compile() {
 
-        const chunk = this.#body.clone();
+        const chunk = this.#body.specialize(ShaderSwitchSet.EMPTY).clone();
         chunk.addDependency(this.#resources.generateCodeChunk())
 
         const compiled = chunk.compile();
 
+        check_required_resources(compiled.resources, this.#resources, this.#label);
+
         /**
          *
          * @type {string[]}
@@ -178,6 +325,7 @@ export class ShaderDescriptor {
 
         assert.defined(body, 'body');
         assert.equal(body.isCodeChunk, true, 'body.isCodeChunk !== true');
+        assert.notEqual(body.isCodeChunkChoice, true, 'body is a CodeChunkChoice; make it a dependency of the body instead');
 
         assert.isString(label, 'label');