@woosh/meep-engine 3.0.2 → 3.2.0

package/src/shade/renderer/extension/SceneColor.js

@@ -1,40 +1,40 @@
-import { FramePhase } from "./FramePhase.js";
-import { FrameRecord } from "./FrameRecord.js";
-
-/**
- * The colour being carried through the frame, in HDR.
- *
- * Carried from {@link FramePhase.AfterLighting} — before which nothing has been lit and there is no
- * colour to hand out — through {@link FramePhase.BeforePresent}. **Not carried at
- * {@link FramePhase.Overlay}**, where the canvas is written rather than threaded; an extension that
- * wants the finished image as input belongs at `BeforePresent`, and finds that out at `get` time
- * rather than from a validation error inside a binding builder.
- *
- * The size of what this holds changes at the upscale, which is why nothing states it as a constant:
- * {@link FrameContext.resolution} reads it from the live handle.
- *
- * `copy` — a readable snapshot of the colour as it stood when the phase began, which a pass
- * rasterizing *into* the live colour needs in order to also sample what is behind it — is
- * deliberately absent. It is one of the frame's optional products, and products are their own
- * delivery step.
- */
-export class SceneColor extends FrameRecord {
-    #color = -1;
-
-    static is_present_at(phase) {
-        return phase === FramePhase.AfterLighting
-            || phase === FramePhase.AfterTransparency
-            || phase === FramePhase.BeforePresent;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get color() {
-        return this.read(this.#color);
-    }
-
-    set color(handle) {
-        this.#color = this.publish(handle);
-    }
-}
+import { FramePhase } from "./FramePhase.js";
+import { FrameRecord } from "./FrameRecord.js";
+
+/**
+ * The colour being carried through the frame, in HDR.
+ *
+ * Carried from {@link FramePhase.AfterLighting} — before which nothing has been lit and there is no
+ * colour to hand out — through {@link FramePhase.BeforePresent}. **Not carried at
+ * {@link FramePhase.Overlay}**, where the canvas is written rather than threaded; an extension that
+ * wants the finished image as input belongs at `BeforePresent`, and finds that out at `get` time
+ * rather than from a validation error inside a binding builder.
+ *
+ * The size of what this holds changes at the upscale, which is why nothing states it as a constant:
+ * {@link FrameContext.resolution} reads it from the live handle.
+ *
+ * `copy` — a readable snapshot of the colour as it stood when the phase began, which a pass
+ * rasterizing *into* the live colour needs in order to also sample what is behind it — is
+ * deliberately absent. It is one of the frame's optional products, and products are their own
+ * delivery step.
+ */
+export class SceneColor extends FrameRecord {
+    #color = -1;
+
+    static is_present_at(phase) {
+        return phase === FramePhase.AfterLighting
+            || phase === FramePhase.AfterTransparency
+            || phase === FramePhase.BeforePresent;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get color() {
+        return this.read(this.#color);
+    }
+
+    set color(handle) {
+        this.#color = this.publish(handle);
+    }
+}

package/src/shade/renderer/extension/ViewTextures.js

@@ -1,78 +1,78 @@
-import { FramePhase } from "./FramePhase.js";
-import { FrameRecord } from "./FrameRecord.js";
-
-/**
- * What the frame knows about where each pixel came from: this frame's depth, last frame's depth,
- * and the visibility buffer's mesh and triangle rows.
- *
- * Carried from {@link FramePhase.AfterGBuffer} through {@link FramePhase.BeforePresent}, and
- * writable wherever it is carried — an extension that rasterizes geometry which should own depth
- * publishes a replacement here, the same way any other record is published into.
- *
- * `velocity` is deliberately absent: it is one of the frame's optional products, and products are
- * their own delivery step. A field nothing may legally read yet would be a promise with no
- * mechanism behind it.
- */
-export class ViewTextures extends FrameRecord {
-    #depth = -1;
-    #depth_previous = -1;
-    #visibility_mesh = -1;
-    #visibility_triangle = -1;
-
-    static is_present_at(phase) {
-        return phase === FramePhase.AfterGBuffer
-            || phase === FramePhase.AfterLighting
-            || phase === FramePhase.AfterTransparency
-            || phase === FramePhase.BeforePresent;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get depth() {
-        return this.read(this.#depth);
-    }
-
-    set depth(handle) {
-        this.#depth = this.publish(handle);
-    }
-
-    /**
-     * Last frame's depth, which reprojection-shaped effects need.
-     *
-     * @returns {number}
-     */
-    get depth_previous() {
-        return this.read(this.#depth_previous);
-    }
-
-    set depth_previous(handle) {
-        this.#depth_previous = this.publish(handle);
-    }
-
-    /**
-     * Which mesh each pixel came from. What an outline or a selection highlight is derived from.
-     *
-     * @returns {number}
-     */
-    get visibility_mesh() {
-        return this.read(this.#visibility_mesh);
-    }
-
-    set visibility_mesh(handle) {
-        this.#visibility_mesh = this.publish(handle);
-    }
-
-    /**
-     * Which triangle each pixel came from.
-     *
-     * @returns {number}
-     */
-    get visibility_triangle() {
-        return this.read(this.#visibility_triangle);
-    }
-
-    set visibility_triangle(handle) {
-        this.#visibility_triangle = this.publish(handle);
-    }
-}
+import { FramePhase } from "./FramePhase.js";
+import { FrameRecord } from "./FrameRecord.js";
+
+/**
+ * What the frame knows about where each pixel came from: this frame's depth, last frame's depth,
+ * and the visibility buffer's mesh and triangle rows.
+ *
+ * Carried from {@link FramePhase.AfterGBuffer} through {@link FramePhase.BeforePresent}, and
+ * writable wherever it is carried — an extension that rasterizes geometry which should own depth
+ * publishes a replacement here, the same way any other record is published into.
+ *
+ * `velocity` is deliberately absent: it is one of the frame's optional products, and products are
+ * their own delivery step. A field nothing may legally read yet would be a promise with no
+ * mechanism behind it.
+ */
+export class ViewTextures extends FrameRecord {
+    #depth = -1;
+    #depth_previous = -1;
+    #visibility_mesh = -1;
+    #visibility_triangle = -1;
+
+    static is_present_at(phase) {
+        return phase === FramePhase.AfterGBuffer
+            || phase === FramePhase.AfterLighting
+            || phase === FramePhase.AfterTransparency
+            || phase === FramePhase.BeforePresent;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get depth() {
+        return this.read(this.#depth);
+    }
+
+    set depth(handle) {
+        this.#depth = this.publish(handle);
+    }
+
+    /**
+     * Last frame's depth, which reprojection-shaped effects need.
+     *
+     * @returns {number}
+     */
+    get depth_previous() {
+        return this.read(this.#depth_previous);
+    }
+
+    set depth_previous(handle) {
+        this.#depth_previous = this.publish(handle);
+    }
+
+    /**
+     * Which mesh each pixel came from. What an outline or a selection highlight is derived from.
+     *
+     * @returns {number}
+     */
+    get visibility_mesh() {
+        return this.read(this.#visibility_mesh);
+    }
+
+    set visibility_mesh(handle) {
+        this.#visibility_mesh = this.publish(handle);
+    }
+
+    /**
+     * Which triangle each pixel came from.
+     *
+     * @returns {number}
+     */
+    get visibility_triangle() {
+        return this.read(this.#visibility_triangle);
+    }
+
+    set visibility_triangle(handle) {
+        this.#visibility_triangle = this.publish(handle);
+    }
+}

package/src/shade/renderer/fow/GPUFogOfWarRenderer.js

@@ -1,182 +1,182 @@
-import { assert } from "../../../core/assert.js";
-import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
-import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
-import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
-import { FOG_OF_WAR_STRUCT, shader_fog_of_war } from "./shader_fog_of_war.js";
-
-/**
- * Composites fog of war over the frame.
- *
- * **The mask is a texture this owns rather than one the texture manager holds.** The manager uploads
- * an image once and keys its cache on that image's identity, which is the right contract for a
- * material's textures and the wrong one for a mask that changes whenever the player moves: every
- * change would allocate another texture and leave the previous one in the cache for the life of the
- * device. So the fog field's own `Sampler2D` is written into a texture allocated here, and rewritten
- * in place when it changes.
- */
-export class GPUFogOfWarRenderer {
-    /**
-     * @type {GPUTextureContext|null}
-     */
-    #mask = null;
-
-    /**
-     * The array the mask was last written from, and its version — together they say whether the
-     * texture still agrees with the field.
-     *
-     * @type {Uint8Array|null}
-     */
-    #mask_source = null;
-
-    /**
-     * @type {number}
-     */
-    #mask_version = -1;
-
-    /**
-     * Give the mask texture back.
-     *
-     * The renderer lives as long as the system that owns it, and a scene reload builds both again —
-     * so without this each reload would leave a mask behind on the device. The legacy path has
-     * exactly this shape of leak (a `ShaderMaterial` per run) and U5 says to resolve it rather than
-     * carry it across.
-     */
-    destroy() {
-        if (this.#mask !== null) {
-            this.#mask.destroy();
-
-            this.#mask = null;
-            this.#mask_source = null;
-            this.#mask_version = -1;
-        }
-    }
-
-    /**
-     * Record the fog composite into `graph`, over the colour it is given.
-     *
-     * @param {object} args
-     * @param {FrameGraph} args.graph
-     * @param {number} args.color colour resource handle to draw over
-     * @param {number} args.depth scene depth — **sampled**, which is why it is not also an
-     * attachment
-     * @param {GPUBuffer|GPUTypedBuffer} args.camera
-     * @param {FogField} args.field
-     * @returns {number} the colour handle after the composite
-     */
-    graph_draw({ graph, color, depth, camera, field }) {
-        assert.defined(graph, 'graph');
-        assert.defined(field, 'field');
-
-        const data = {};
-
-        const pass = graph.add('fog of war', data, (data, resources, context) => {
-            this.#execute(data, resources, context, camera, field);
-        });
-
-        data.depth = pass.read(depth);
-        data.color = pass.write(pass.read(color));
-
-        return data.color;
-    }
-
-    /**
-     * @param data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     * @param {GPUBuffer|GPUTypedBuffer} camera
-     * @param {FogField} field
-     */
-    #execute(data, resources, context, camera, field) {
-        const encoder = context.encoder;
-        const graphics = context.graphics;
-
-        const color_texture = resources.get(data.color);
-        const depth_texture = resources.get(data.depth);
-
-        const mask = this.#obtain_mask(graphics, field);
-
-        const fog = encoder.allocateTransientValueBuffer(FOG_OF_WAR_STRUCT, {
-            uv_transform: field.uv_transform,
-            color: field.color,
-            resolution: [field.sampler.width, field.sampler.height],
-            edge_extend: field.edge_extend
-        });
-
-        shader_fog_of_war.draw({
-            encoder,
-            bindings: {
-                camera,
-                fog,
-                tDepth: depth_texture.obtainView(),
-                tFog: mask.obtainView(),
-                fog_sampler: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE)
-            },
-            colorAttachments: [{
-                loadOp: "load",
-                storeOp: "store",
-                view: color_texture.obtainView(TextureViewDescriptor.from({
-                    mipLevelCount: 1,
-                    baseMipLevel: 0
-                }))
-            }],
-            color_formats: [color_texture.descriptor.format]
-        });
-    }
-
-    /**
-     * The mask as the GPU holds it, allocated on first use and rewritten when the field changes.
-     *
-     * **The field says when it changed, rather than the array being asked.** `FogOfWar` writes into
-     * its sampler's data directly — `fill(255)` for a conceal, a cell at a time for a fade — so
-     * neither the array's identity nor `Sampler2D.version` moves when the mask does. The component's
-     * own `textureChanged` signal is the thing that knows, and the system carries it here as a flag.
-     *
-     * @param {GraphicsContext} graphics
-     * @param {FogField} field
-     * @returns {GPUTextureContext}
-     */
-    #obtain_mask(graphics, field) {
-        const sampler = field.sampler;
-
-        const width = sampler.width;
-        const height = sampler.height;
-
-        const existing = this.#mask;
-
-        if (existing === null || existing.descriptor.size[0] !== width || existing.descriptor.size[1] !== height) {
-            /*
-             `r8unorm` because the mask is one byte per cell and is read through a linear sampler:
-             it has to be a filterable format, and a single-byte one keeps the upload as small as
-             the field itself.
-            */
-            this.#mask = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-                label: "fog of war mask",
-                size: [width, height],
-                format: "r8unorm",
-                mipLevelCount: 1,
-                usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
-            }));
-
-            this.#mask_source = null;
-            this.#mask_version = -1;
-        }
-
-        const data = sampler.data;
-
-        if (field.dirty || this.#mask_source !== data || this.#mask_version !== sampler.version) {
-            graphics.device.queue.writeTexture(
-                { texture: this.#mask.gpu_texture },
-                data,
-                { bytesPerRow: width, rowsPerImage: height },
-                [width, height]
-            );
-
-            this.#mask_source = data;
-            this.#mask_version = sampler.version;
-
-            field.dirty = false;
-        }
-
-        return this.#mask;
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
+import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { FOG_OF_WAR_STRUCT, shader_fog_of_war } from "./shader_fog_of_war.js";
+
+/**
+ * Composites fog of war over the frame.
+ *
+ * **The mask is a texture this owns rather than one the texture manager holds.** The manager uploads
+ * an image once and keys its cache on that image's identity, which is the right contract for a
+ * material's textures and the wrong one for a mask that changes whenever the player moves: every
+ * change would allocate another texture and leave the previous one in the cache for the life of the
+ * device. So the fog field's own `Sampler2D` is written into a texture allocated here, and rewritten
+ * in place when it changes.
+ */
+export class GPUFogOfWarRenderer {
+    /**
+     * @type {GPUTextureContext|null}
+     */
+    #mask = null;
+
+    /**
+     * The array the mask was last written from, and its version — together they say whether the
+     * texture still agrees with the field.
+     *
+     * @type {Uint8Array|null}
+     */
+    #mask_source = null;
+
+    /**
+     * @type {number}
+     */
+    #mask_version = -1;
+
+    /**
+     * Give the mask texture back.
+     *
+     * The renderer lives as long as the system that owns it, and a scene reload builds both again —
+     * so without this each reload would leave a mask behind on the device. The legacy path has
+     * exactly this shape of leak (a `ShaderMaterial` per run) and U5 says to resolve it rather than
+     * carry it across.
+     */
+    destroy() {
+        if (this.#mask !== null) {
+            this.#mask.destroy();
+
+            this.#mask = null;
+            this.#mask_source = null;
+            this.#mask_version = -1;
+        }
+    }
+
+    /**
+     * Record the fog composite into `graph`, over the colour it is given.
+     *
+     * @param {object} args
+     * @param {FrameGraph} args.graph
+     * @param {number} args.color colour resource handle to draw over
+     * @param {number} args.depth scene depth — **sampled**, which is why it is not also an
+     * attachment
+     * @param {GPUBuffer|GPUTypedBuffer} args.camera
+     * @param {FogField} args.field
+     * @returns {number} the colour handle after the composite
+     */
+    graph_draw({ graph, color, depth, camera, field }) {
+        assert.defined(graph, 'graph');
+        assert.defined(field, 'field');
+
+        const data = {};
+
+        const pass = graph.add('fog of war', data, (data, resources, context) => {
+            this.#execute(data, resources, context, camera, field);
+        });
+
+        data.depth = pass.read(depth);
+        data.color = pass.write(pass.read(color));
+
+        return data.color;
+    }
+
+    /**
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     * @param {GPUBuffer|GPUTypedBuffer} camera
+     * @param {FogField} field
+     */
+    #execute(data, resources, context, camera, field) {
+        const encoder = context.encoder;
+        const graphics = context.graphics;
+
+        const color_texture = resources.get(data.color);
+        const depth_texture = resources.get(data.depth);
+
+        const mask = this.#obtain_mask(graphics, field);
+
+        const fog = encoder.allocateTransientValueBuffer(FOG_OF_WAR_STRUCT, {
+            uv_transform: field.uv_transform,
+            color: field.color,
+            resolution: [field.sampler.width, field.sampler.height],
+            edge_extend: field.edge_extend
+        });
+
+        shader_fog_of_war.draw({
+            encoder,
+            bindings: {
+                camera,
+                fog,
+                tDepth: depth_texture.obtainView(),
+                tFog: mask.obtainView(),
+                fog_sampler: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE)
+            },
+            colorAttachments: [{
+                loadOp: "load",
+                storeOp: "store",
+                view: color_texture.obtainView(TextureViewDescriptor.from({
+                    mipLevelCount: 1,
+                    baseMipLevel: 0
+                }))
+            }],
+            color_formats: [color_texture.descriptor.format]
+        });
+    }
+
+    /**
+     * The mask as the GPU holds it, allocated on first use and rewritten when the field changes.
+     *
+     * **The field says when it changed, rather than the array being asked.** `FogOfWar` writes into
+     * its sampler's data directly — `fill(255)` for a conceal, a cell at a time for a fade — so
+     * neither the array's identity nor `Sampler2D.version` moves when the mask does. The component's
+     * own `textureChanged` signal is the thing that knows, and the system carries it here as a flag.
+     *
+     * @param {GraphicsContext} graphics
+     * @param {FogField} field
+     * @returns {GPUTextureContext}
+     */
+    #obtain_mask(graphics, field) {
+        const sampler = field.sampler;
+
+        const width = sampler.width;
+        const height = sampler.height;
+
+        const existing = this.#mask;
+
+        if (existing === null || existing.descriptor.size[0] !== width || existing.descriptor.size[1] !== height) {
+            /*
+             `r8unorm` because the mask is one byte per cell and is read through a linear sampler:
+             it has to be a filterable format, and a single-byte one keeps the upload as small as
+             the field itself.
+            */
+            this.#mask = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
+                label: "fog of war mask",
+                size: [width, height],
+                format: "r8unorm",
+                mipLevelCount: 1,
+                usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
+            }));
+
+            this.#mask_source = null;
+            this.#mask_version = -1;
+        }
+
+        const data = sampler.data;
+
+        if (field.dirty || this.#mask_source !== data || this.#mask_version !== sampler.version) {
+            graphics.device.queue.writeTexture(
+                { texture: this.#mask.gpu_texture },
+                data,
+                { bytesPerRow: width, rowsPerImage: height },
+                [width, height]
+            );
+
+            this.#mask_source = data;
+            this.#mask_version = sampler.version;
+
+            field.dirty = false;
+        }
+
+        return this.#mask;
+    }
+}