@woosh/meep-engine 3.11.3 → 3.12.0

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

@@ -1,218 +1,218 @@
-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.compile(),
-            layout: descriptor.resources.generatePipelineLayout(GPUShaderStage.FRAGMENT),
-            targets,
-            depthStencil,
-        });
-    }
-
-    // TODO simplify constructor
-    /**
-     * Utility constructor, matching general Shade API
-     * @param {ShaderDescriptor} descriptor
-     * @param {ColorTargetState[]} targets
-     * @param {DepthStencilState} [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";
+
+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 {ShaderDescriptor} descriptor
+     * @param {ColorTargetState[]} targets
+     * @param {DepthStencilState} [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();
+
+    }
 }

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

@@ -21,6 +21,11 @@ export class ShaderDescriptor {
      * @return {string|GPUFeatureName[]}
      */
     get features(): string | GPUFeatureName[];
+    /**
+     * @see compile
+     * @returns {string}
+     */
+    get source(): string;
     /**
      *
      * @return {string}

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;IA2II;;;;;OAKG;IACH,yCAJW,MAAM,oBAwBhB;IA9JD;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAaD;;;OAGG;IACH,0CAEC;IAED;;;OAGG;IACH,WAFY,MAAM,CAiCjB;IAED;;;OAGG;IACH,iDA6BC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA6BJ;4CAxK2C,2CAA2C"}
+{"version":3,"file":"ShaderDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ShaderDescriptor.js"],"names":[],"mappings":"AAIA;IA+JI;;;;;OAKG;IACH,yCAJW,MAAM,oBAwBhB;IAlLD;;;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;;CA6BJ;4CA5L2C,2CAA2C"}

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

@@ -49,6 +49,26 @@ export class ShaderDescriptor {
         return this.#features;
     }
 
+    /**
+     *
+     * @type {string}
+     */
+    #source = undefined;
+
+    /**
+     * @see compile
+     * @returns {string}
+     */
+    get source() {
+
+        if (this.#source === undefined) {
+            this.#source = this.compile();
+        }
+
+        return this.#source;
+
+    }
+
     /**
      *
      * @return {string}

package/src/shade/renderer/shader/util/compute_infer_workgroup_size_from_source.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Recover a compute entry point's workgroup size from its WGSL source.
+ *
+ * Follows the `workgroup_size_attr` grammar, so every spelling below is read alike, and the omitted
+ * dimensions default to `1`:
+ *
+ * ```wgsl
+ * @workgroup_size(64)              // -> [64, 1, 1]
+ * @workgroup_size(8, 8)            // -> [8, 8, 1]
+ * @workgroup_size( 8 , 8 , 4 , )   // -> [8, 8, 4], blankspace anywhere, trailing comma
+ * @workgroup_size(0x40u)           // -> [64, 1, 1], hexadecimal, and the i/u type suffixes
+ * ```
+ *
+ * An argument may also name a `const` that the same module binds directly to an integer literal,
+ * which is how a shader states its block size once and then uses it in both the attribute and the
+ * body:
+ *
+ * ```wgsl
+ * const BLOCK_DIM = 256u;
+ * @workgroup_size(BLOCK_DIM)       // -> [256, 1, 1]
+ * ```
+ *
+ * Comments count as blankspace and are removed first, so they may sit between any two tokens of the
+ * attribute, and an attribute that is itself commented out is correctly not found.
+ *
+ * **One level of aliasing, and no arithmetic.** WGSL permits any const-expression or
+ * override-expression, so `@workgroup_size(BLOCK_DIM / 2u)` is legal, and so is
+ * `@workgroup_size(WG_X)` for an `override WG_X` whose value only arrives with the pipeline.
+ * Neither is resolvable from the source text alone. Such a shader throws rather than being guessed
+ * at, because every caller for this number divides a thread count by it, and a wrong divisor
+ * silently dispatches the wrong fraction of the workload. A loud failure is recoverable; a
+ * plausible one is not.
+ *
+ * Entry points that disagree are an error for the same reason. A module may hold several, and
+ * choosing between two conflicting sizes would be choosing at random.
+ *
+ * @param {string} code WGSL source
+ * @returns {[number, number, number]} `[x, y, z]`
+ * @throws {Error} if no `@workgroup_size` attribute is present, if its arguments are neither
+ * integer literals nor names resolving to one, if a dimension is not a positive integer, or if
+ * entry points disagree on the size
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function compute_infer_workgroup_size_from_source(code: string): [number, number, number];
+//# sourceMappingURL=compute_infer_workgroup_size_from_source.d.ts.map

package/src/shade/renderer/shader/util/compute_infer_workgroup_size_from_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute_infer_workgroup_size_from_source.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/util/compute_infer_workgroup_size_from_source.js"],"names":[],"mappings":"AA2SA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,+DATW,MAAM,GACJ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CA+GpC"}