@woosh/meep-engine 3.46.0 → 3.49.0

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;IAyGI;;;;;;;OAOG;IACH;QALqC,UAAU;QACR,OAAO,EAAnC,kBAAkB;QACU,YAAY;QACtC,WAAW,CAavB;IAnFD;;;;;OAKG;IACH,sEAuDC;IAhGD;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,cAFU,MAAM,EAAE,EAAE,CAEF;IAOlB;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,6BAEC;IAuFD;;;;;;;;;OASG;IACH,6HAsEC;;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

@@ -1,219 +1,300 @@
-import { assert } from "../../../core/assert.js";
-import {
-    rp_validate_and_rewrite_for_color_attachments
-} 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";
-
-const VALIDATION_ENABLED = true;
-
-/**
- * Full-screen render shader
- */
-export class ImageShader {
-    /**
-     * @type {ShaderDescriptor}
-     */
-    #descriptor
-
-    /**
-     *
-     * @returns {ShaderDescriptor}
-     */
-    get descriptor() {
-        return this.#descriptor;
-    }
-
-    /**
-     * Optional clear values for each target
-     * @type {number[][]}
-     */
-    clear_values = [];
-
-    /**
-     * @type {RenderPipelineDescriptor}
-     */
-    #pipeline;
-
-    /**
-     *
-     * @returns {RenderPipelineDescriptor}
-     */
-    get pipeline() {
-        return this.#pipeline
-    }
-
-    /**
-     *
-     * @returns {boolean}
-     */
-    get isImageShader() {
-        return true;
-    }
-
-    /**
-     *
-     * @param {ShaderDescriptor} descriptor
-     * @param {(ColorTargetState|{clearValue?:number[]})[]} [targets]
-     * @param {DepthStencilState} [depthStencil]
-     */
-    constructor({
-                    descriptor,
-                    targets = [],
-                    depthStencil,
-                }) {
-
-        this.#descriptor = descriptor;
-
-        // process optional clearValue parameter
-        for (let i = 0; i < targets.length; i++) {
-            const target = targets[i];
-
-            const clearValue = target.clearValue;
-            if (clearValue !== undefined) {
-                assert.isArrayLike(clearValue, 'clearValue');
-
-                let sanitizedClearValue = clearValue;
-
-                // we need exactly 4 values according to spec
-
-                const value_count = sanitizedClearValue.length;
-
-                // TODO validate count against number of channels in the target
-
-                if (value_count === 4) {
-                    // correct length
-
-                } else if (value_count < 4) {
-                    // too few
-
-                    sanitizedClearValue = sanitizedClearValue.slice();
-
-                    for (let j = value_count; j < 4; j++) {
-                        // pad with 0
-                        sanitizedClearValue[j] = 0;
-                    }
-                } else if (value_count > 4) {
-                    // too many, drop the remainder
-
-                    sanitizedClearValue = sanitizedClearValue.slice(0, 4);
-
-                }
-
-                this.clear_values[i] = sanitizedClearValue;
-            }
-
-        }
-
-        this.#pipeline = create_full_quad_pipeline_descriptor({
-            label: descriptor.label,
-            fragment_code: descriptor.source,
-            layout: descriptor.resources.generatePipelineLayout(GPUShaderStage.FRAGMENT),
-            targets,
-            depthStencil,
-        });
-    }
-
-    // TODO simplify constructor
-    /**
-     * Utility constructor, matching general Shade API
-     * @param {Object} options
-     * @param {ShaderDescriptor} options.descriptor
-     * @param {ColorTargetState[]} options.targets
-     * @param {DepthStencilState} [options.depthStencil]
-     * @returns {ImageShader}
-     */
-    static from({
-                    descriptor,
-                    targets,
-                    depthStencil,
-                }) {
-
-        return new ImageShader({
-            descriptor,
-            depthStencil,
-            targets
-        });
-    }
-
-    /**
-     * Note the absence of depth target, image shader is a full-screen pass, so depth is not used.
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {Object} [bindings] data bindings. It's optional, but in 99.99% of use cases you will want to specify this.
-     * @param {GPURenderPassColorAttachment[]} [colorAttachments] where to draw, these are fragment shader outputs.
-     * @param {GPURenderPassDepthStencilAttachment} [depthStencilAttachment]
-     * @param {GPUTextureFormat[]} [color_formats] optional, if specified will be used to rewrite the pipeline for compatibility
-     * @param {number[]} [viewport] [x0, y0, width, height ]
-     */
-    draw({
-             encoder,
-             bindings = {},
-             colorAttachments = [],
-             depthStencilAttachment,
-             color_formats,
-             viewport
-         }) {
-
-        assert.defined(encoder, 'encoder');
-
-        // TODO I hate the separate color_formats parameter. Make a wrapper around GPURenderPassColorAttachment instead, and have a pointer to the GPUTextureContext in there so we can access the texture format
-
-        const shader_descriptor = this.#descriptor;
-
-        if (VALIDATION_ENABLED) {
-            shader_descriptor.validate_against_device(encoder.device);
-        }
-
-        const resolved_bindings = shader_descriptor.resources.generateBindings(bindings, encoder);
-
-        const immediate = encoder.writeImmediate(shader_descriptor.resources, bindings);
-
-        encoder.pushDebugGroup(shader_descriptor.label);
-
-        let pipeline = this.#pipeline;
-
-        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);
-        }
-
-        const pass = encoder.constructRenderPass({
-            pipeline,
-            bindings: resolved_bindings,
-            colorAttachments,
-            depthStencilAttachment,
-            immediate
-        });
-
-        if (viewport !== undefined) {
-            const _x = viewport[0];
-            const _y = viewport[1];
-            const _width = viewport[2];
-            const _height = viewport[3];
-
-            assert.greaterThanOrEqual(_width, 0, 'viewport width must be positive');
-            assert.greaterThanOrEqual(_height, 0, 'viewport width must be positive');
-
-            assert.notNaN(_x, '_x');
-            assert.notNaN(_y, '_y');
-
-
-            pass.setViewport(
-                _x,
-                _y,
-                _width,
-                _height,
-                0,
-                1
-            );
-        }
-
-        pass.draw(3);
-
-        pass.end();
-
-        encoder.popDebugGroup();
-
-    }
+import { assert } from "../../../core/assert.js";
+import {
+    rp_validate_and_rewrite_for_color_attachments
+} 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;
+
+/**
+ * Full-screen render shader
+ */
+export class ImageShader {
+    /**
+     * @type {ShaderDescriptor}
+     */
+    #descriptor
+
+    /**
+     *
+     * @returns {ShaderDescriptor}
+     */
+    get descriptor() {
+        return this.#descriptor;
+    }
+
+    /**
+     * Optional clear values for each target
+     * @type {number[][]}
+     */
+    clear_values = [];
+
+    /**
+     * @type {RenderPipelineDescriptor}
+     */
+    #pipeline;
+
+    /**
+     * The device this shader last passed {@link ShaderDescriptor#validate_against_device} on, or null:
+     * one check per device rather than one per draw. See `ComputeShader`'s field of the same name.
+     *
+     * @type {GPUDevice|null}
+     */
+    #validated_device = null;
+
+    /**
+     *
+     * @returns {RenderPipelineDescriptor}
+     */
+    get pipeline() {
+        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}
+     */
+    get isImageShader() {
+        return true;
+    }
+
+    /**
+     *
+     * @param {ShaderDescriptor} descriptor
+     * @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 = [],
+                    depthStencil,
+                }) {
+
+        this.#descriptor = descriptor;
+        this.#construction = { targets, depthStencil };
+
+        // process optional clearValue parameter
+        for (let i = 0; i < targets.length; i++) {
+            const target = targets[i];
+
+            const clearValue = target.clearValue;
+            if (clearValue !== undefined) {
+                assert.isArrayLike(clearValue, 'clearValue');
+
+                let sanitizedClearValue = clearValue;
+
+                // we need exactly 4 values according to spec
+
+                const value_count = sanitizedClearValue.length;
+
+                // TODO validate count against number of channels in the target
+
+                if (value_count === 4) {
+                    // correct length
+
+                } else if (value_count < 4) {
+                    // too few
+
+                    sanitizedClearValue = sanitizedClearValue.slice();
+
+                    for (let j = value_count; j < 4; j++) {
+                        // pad with 0
+                        sanitizedClearValue[j] = 0;
+                    }
+                } else if (value_count > 4) {
+                    // too many, drop the remainder
+
+                    sanitizedClearValue = sanitizedClearValue.slice(0, 4);
+
+                }
+
+                this.clear_values[i] = sanitizedClearValue;
+            }
+
+        }
+
+        this.#pipeline = create_full_quad_pipeline_descriptor({
+            label: descriptor.label,
+            fragment_code: descriptor.source,
+            layout: descriptor.resources.generatePipelineLayout(GPUShaderStage.FRAGMENT),
+            targets,
+            depthStencil,
+        });
+    }
+
+    // TODO simplify constructor
+    /**
+     * Utility constructor, matching general Shade API
+     * @param {Object} options
+     * @param {ShaderDescriptor} options.descriptor
+     * @param {ColorTargetState[]} options.targets
+     * @param {DepthStencilState} [options.depthStencil]
+     * @returns {ImageShader}
+     */
+    static from({
+                    descriptor,
+                    targets,
+                    depthStencil,
+                }) {
+
+        return new ImageShader({
+            descriptor,
+            depthStencil,
+            targets
+        });
+    }
+
+    /**
+     * Note the absence of depth target, image shader is a full-screen pass, so depth is not used.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {Object} [bindings] data bindings. It's optional, but in 99.99% of use cases you will want to specify this.
+     * @param {GPURenderPassColorAttachment[]} [colorAttachments] where to draw, these are fragment shader outputs.
+     * @param {GPURenderPassDepthStencilAttachment} [depthStencilAttachment]
+     * @param {GPUTextureFormat[]} [color_formats] optional, if specified will be used to rewrite the pipeline for compatibility
+     * @param {number[]} [viewport] [x0, y0, width, height ]
+     */
+    draw({
+             encoder,
+             bindings = {},
+             colorAttachments = [],
+             depthStencilAttachment,
+             color_formats,
+             viewport
+         }) {
+
+        assert.defined(encoder, 'encoder');
+
+        // TODO I hate the separate color_formats parameter. Make a wrapper around GPURenderPassColorAttachment instead, and have a pointer to the GPUTextureContext in there so we can access the texture format
+
+        const shader_descriptor = this.#descriptor;
+
+        const device = encoder.device;
+
+        if (VALIDATION_ENABLED && device !== this.#validated_device) {
+            shader_descriptor.validate_against_device(device);
+
+            this.#validated_device = device;
+        }
+
+        const resolved_bindings = shader_descriptor.resources.generateBindings(bindings, encoder);
+
+        const immediate = encoder.writeImmediate(shader_descriptor.resources, bindings);
+
+        encoder.pushDebugGroup(shader_descriptor.label);
+
+        let pipeline = this.#pipeline;
+
+        if (color_formats !== undefined) {
+            // potentially rewrite the pipeline to be compatible with output formats
+            // example: rgba8unorm -> rgba16float
+            pipeline = this.pipeline_for(color_formats);
+        }
+
+        const pass = encoder.constructRenderPass({
+            pipeline,
+            bindings: resolved_bindings,
+            colorAttachments,
+            depthStencilAttachment,
+            immediate
+        });
+
+        if (viewport !== undefined) {
+            const _x = viewport[0];
+            const _y = viewport[1];
+            const _width = viewport[2];
+            const _height = viewport[3];
+
+            assert.greaterThanOrEqual(_width, 0, 'viewport width must be positive');
+            assert.greaterThanOrEqual(_height, 0, 'viewport width must be positive');
+
+            assert.notNaN(_x, '_x');
+            assert.notNaN(_y, '_y');
+
+
+            pass.setViewport(
+                _x,
+                _y,
+                _width,
+                _height,
+                0,
+                1
+            );
+        }
+
+        pass.draw(3);
+
+        pass.end();
+
+        encoder.popDebugGroup();
+
+    }
 }

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

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("./compiler/ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ */
 export class ShaderDescriptor {
     /**
      *
@@ -32,7 +35,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 +69,8 @@ export class ShaderDescriptor {
     validate_gpu_features(device: GPUDevice): boolean;
     #private;
 }
+export type ShaderSwitch = import("./compiler/ShaderSwitch.js").ShaderSwitch;
 import { ShaderResourceSetDescriptor } from "./resource/ShaderResourceSetDescriptor.js";
+import { ShaderSwitchSet } from "./compiler/ShaderSwitchSet.js";
 import { CodeChunk } from "./compiler/CodeChunk.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":"AAKA;;GAEG;AAEH;IA+NI;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACgC,SAAS,GAA/C,2BAA2B;QACR,IAAI,EAAvB,SAAS;yBAuBnB;IApPD;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAaD;;;OAGG;IACH,0CAEC;IAQD;;;OAGG;IACH,qBAQC;IAOD;;;;;OAKG;IACH,oEAMC;IASD;;;;;;;OAOG;IACH,aAHW,eAAe,GACb,gBAAgB,CA8B5B;IAED;;;OAGG;IACH,WAFY,MAAM,CAiCjB;IAED;;;OAGG;IACH,iDA6BC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA+BJ;2BA/PY,OAAO,4BAA4B,EAAE,YAAY;4CAHlB,2CAA2C;gCADvD,+BAA+B;0BADrC,yBAAyB"}

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

@@ -1,7 +1,12 @@
 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/ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ */
+
 export class ShaderDescriptor {
     /**
      * Human-readable label
@@ -70,12 +75,76 @@ 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();
@@ -178,6 +247,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');