@woosh/meep-engine 3.11.2 → 3.12.0

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

@@ -1,215 +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);
-
-        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
-        });
-
-        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;IAiHI;;;;;OAKG;IACH,yCAJW,MAAM,oBAwBhB;IApID;;;OAGG;IACH,oBAEC;IAOD;;;OAGG;IACH,6CAEC;IAaD;;;OAGG;IACH,0CAEC;IAED;;;OAGG;IACH,WAFY,MAAM,CAyBjB;IAED;;;OAGG;IACH,iDAWC;IAED;;;;;OAKG;IACH,0CAHa,OAAO,CAenB;;CA6BJ;4CA9I2C,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}
@@ -70,6 +90,14 @@ export class ShaderDescriptor {
         for (const extension of extensions) {
             result_parts.unshift(`enable ${extension};`);
         }
+
+        // Language extensions take `requires`, not `enable`, and are not GPUFeatureNames — so they
+        // are not folded into `#features`, which `validate_gpu_features` checks against
+        // `device.features`. Looking `immediate_address_space` up there would never find it.
+        for (const language_extension of compiled.language_extensions) {
+            result_parts.unshift(`requires ${language_extension};`);
+        }
+
         result_parts.push(compiled.text);
 
         this.#features = Object.freeze(extensions);
@@ -92,6 +120,24 @@ export class ShaderDescriptor {
             }
         }
 
+        {
+            // immediate data budget. Not a device floor — a browser without immediates still starts
+            // and still renders; it just cannot run *this* shader. Saying so by name beats the
+            // shader-creation error a device would otherwise raise, which names neither the shader
+            // nor the feature.
+            const required = this.resources.immediateSize;
+
+            if (required > 0) {
+                const limit = device.limits.maxImmediateSize ?? 0;
+
+                if (limit < required) {
+                    throw new Error(
+                        `Shader '${this.label}' needs ${required} bytes of immediate data and this device offers ${limit}. Immediate data is an optional capability — check immediate_data_supported() and pick a shader variant that uses a uniform buffer instead.`
+                    );
+                }
+            }
+        }
+
         this.validate_gpu_features(device);
     }
 

package/src/shade/renderer/shader/chunk/atmosphere/ATMOSPHERE_RADII_DECLARATION.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The two sphere radii the atmosphere is bounded by, as f32.
+ *
+ * `PLANET_RADIUS` and `ATMOSPHERE_HEIGHT` carry no type suffix, so they are AbstractInt.
+ * That converts silently wherever it is used directly in an f32 expression, but binding one
+ * to an un-annotated `let` materialises it to i32 — which then neither mixes with f32 nor
+ * holds the square of a planetary radius, since 6478000^2 is four orders of magnitude past
+ * what an i32 can represent. Anything that needs a radius as a value rather than as a term
+ * takes it from here.
+ *
+ * The squares are what the ray/sphere quadratics actually want, and as module-scope consts
+ * they are folded once rather than recomputed per invocation.
+ *
+ * @type {CodeChunk}
+ */
+export const ATMOSPHERE_RADII_DECLARATION: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=ATMOSPHERE_RADII_DECLARATION.d.ts.map

package/src/shade/renderer/shader/chunk/atmosphere/ATMOSPHERE_RADII_DECLARATION.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ATMOSPHERE_RADII_DECLARATION.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/atmosphere/ATMOSPHERE_RADII_DECLARATION.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,2CAFU,SAAS,CAcjB;0BA/BwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/atmosphere/ATMOSPHERE_RADII_DECLARATION.js

@@ -0,0 +1,32 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { ATMOSPHERE_HEIGHT_DECLARATION } from "./ATMOSPHERE_HEIGHT_DECLARATION.js";
+import { PLANET_RADIUS_DECLARATION } from "./PLANET_RADIUS_DECLARATION.js";
+
+/**
+ * The two sphere radii the atmosphere is bounded by, as f32.
+ *
+ * `PLANET_RADIUS` and `ATMOSPHERE_HEIGHT` carry no type suffix, so they are AbstractInt.
+ * That converts silently wherever it is used directly in an f32 expression, but binding one
+ * to an un-annotated `let` materialises it to i32 — which then neither mixes with f32 nor
+ * holds the square of a planetary radius, since 6478000^2 is four orders of magnitude past
+ * what an i32 can represent. Anything that needs a radius as a value rather than as a term
+ * takes it from here.
+ *
+ * The squares are what the ray/sphere quadratics actually want, and as module-scope consts
+ * they are folded once rather than recomputed per invocation.
+ *
+ * @type {CodeChunk}
+ */
+export const ATMOSPHERE_RADII_DECLARATION = CodeChunk.from(
+    //language=WGSL
+    `
+const ATMOSPHERE_GROUND_RADIUS = f32(PLANET_RADIUS);
+const ATMOSPHERE_TOP_RADIUS = f32(PLANET_RADIUS) + f32(ATMOSPHERE_HEIGHT);
+
+const ATMOSPHERE_GROUND_RADIUS_SQUARED = ATMOSPHERE_GROUND_RADIUS * ATMOSPHERE_GROUND_RADIUS;
+const ATMOSPHERE_TOP_RADIUS_SQUARED = ATMOSPHERE_TOP_RADIUS * ATMOSPHERE_TOP_RADIUS;
+    `, [
+        PLANET_RADIUS_DECLARATION,
+        ATMOSPHERE_HEIGHT_DECLARATION,
+    ]
+);

package/src/shade/renderer/shader/chunk/atmosphere/PLANET_CENTER_DECLARATION.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The dependency is load-bearing rather than tidiness: without it the emitted module's
+ * ordering was whatever else happened to pull PLANET_RADIUS_DECLARATION in first, and a
+ * closure where nothing did put this line above the constant it reads.
+ *
+ * @type {CodeChunk}
+ */
 export const PLANET_CENTER_DECLARATION: CodeChunk;
 import { CodeChunk } from "../../compiler/CodeChunk.js";
 //# sourceMappingURL=PLANET_CENTER_DECLARATION.d.ts.map

package/src/shade/renderer/shader/chunk/atmosphere/PLANET_CENTER_DECLARATION.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PLANET_CENTER_DECLARATION.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/atmosphere/PLANET_CENTER_DECLARATION.js"],"names":[],"mappings":"AAEA,kDAGE;0BALwB,6BAA6B"}
+{"version":3,"file":"PLANET_CENTER_DECLARATION.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/atmosphere/PLANET_CENTER_DECLARATION.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wCAFU,SAAS,CAQjB;0BAhBwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/atmosphere/PLANET_CENTER_DECLARATION.js

@@ -1,6 +1,17 @@
-import { CodeChunk } from "../../compiler/CodeChunk.js";
-
-export const PLANET_CENTER_DECLARATION = CodeChunk.from(
-//language=WGSL
-    `const PLANET_CENTER = vec3(0.0, -PLANET_RADIUS, 0.0);`
-);
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { PLANET_RADIUS_DECLARATION } from "./PLANET_RADIUS_DECLARATION.js";
+
+/**
+ * The dependency is load-bearing rather than tidiness: without it the emitted module's
+ * ordering was whatever else happened to pull PLANET_RADIUS_DECLARATION in first, and a
+ * closure where nothing did put this line above the constant it reads.
+ *
+ * @type {CodeChunk}
+ */
+export const PLANET_CENTER_DECLARATION = CodeChunk.from(
+//language=WGSL
+    `const PLANET_CENTER = vec3(0.0, -PLANET_RADIUS, 0.0);`,
+    [
+        PLANET_RADIUS_DECLARATION
+    ]
+);

package/src/shade/renderer/shader/chunk/atmosphere/chunk_atmosphere_ray_bounds.d.ts

@@ -0,0 +1,21 @@
+/**
+ * How far a ray inside the atmosphere may be marched, and whether it ends on the surface.
+ *
+ * The ground and the atmosphere shell are concentric on the planet and the ray is shared, so
+ * one quadratic setup serves both intersections — only the radius term differs. Calling a
+ * general sphere-intersection routine twice instead recomputes the ray-origin offset and all
+ * three dot products for the second sphere, and re-derives a leading coefficient that is 1
+ * for a unit direction.
+ *
+ * `origin_rel` is relative to the planet centre and assumed to be inside the atmosphere and
+ * at or above the surface, which is what makes the shell's far root the exit point.
+ * `ray_direction` must be normalised.
+ *
+ * `ground_distance` is negative when the ray never meets the surface, which includes looking
+ * up from above it: both roots are behind the origin there.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_atmosphere_ray_bounds: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_atmosphere_ray_bounds.d.ts.map

package/src/shade/renderer/shader/chunk/atmosphere/chunk_atmosphere_ray_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_atmosphere_ray_bounds.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/atmosphere/chunk_atmosphere_ray_bounds.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAFU,SAAS,CAiDjB;0BApEwB,6BAA6B"}