@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,104 +1,104 @@
-/**
- * Points in a frame at which a {@link RenderExtension} records into the frame's graph.
- *
- * A frame is otherwise a closed sequence, and working around a closed pipeline is precisely what
- * made the engine this one replaces awkward. These are the sanctioned way in: each names a moment
- * where a specific set of frame records exists and is stable, and an extension registered against
- * one is handed exactly those.
- *
- * The order below is the order they occur in.
- *
- * **The upscale is a phase boundary, and saying so is part of what a phase means.**
- * {@link AfterGBuffer}, {@link AfterLighting} and {@link AfterTransparency} are before it and run at
- * the internal render resolution; TAA and NSS upscale to the output resolution, so
- * {@link BeforePresent} and {@link Overlay} are after it. With `feature_taa_enabled === false` the
- * upscale does not happen at all and the two sides are the same size. Nothing here is a constant an
- * extension may rely on: {@link FrameContext.resolution} is derived from the live handle and is
- * right in every configuration, which is what the single `resolution` field it replaces was not.
- *
- * **Before the upscale is the common case, and the design leans on it.** An extension drawing into
- * the scene belongs at {@link AfterTransparency}: its work is then temporally resolved, upscaled and
- * sharpened along with everything else, and it draws at internal resolution.
- * {@link BeforePresent} is the deliberate other choice — full output resolution, still HDR — and it
- * is a trade rather than an upgrade: work there gets no temporal history and costs full-resolution
- * pixels.
- *
- * @enum {number}
- */
-export const FramePhase = {
-    /**
-     * The view is updated and nothing has been rasterized. There are no frame records yet — the
-     * view is all there is — so this is the phase for per-frame GPU compute that later phases
-     * depend on: a visibility grid update, a custom cull, a procedural buffer build.
-     *
-     * It exists so that such work has somewhere to go that is inside the graph. Bolted onto a draw
-     * pass at a later phase it sits in the wrong place in the graph and is mis-attributed in a
-     * capture; done outside the graph it is invisible to aliasing and lifetime reasoning entirely.
-     */
-    FrameStart: 0,
-
-    /**
-     * The G-buffer is resolved — albedo, normal, PBR and emissive are written and readable — and
-     * nothing has been lit yet. {@link GBufferTextures} and {@link ViewTextures} are carried; there
-     * is no scene colour, which is what makes this the phase for surface work.
-     *
-     * **This is the one phase where the G-buffer may be published into.** A pass reads the targets,
-     * writes replacements and publishes their handles, and the rest of the frame carries those.
-     * Replacing rather than writing in place is not a preference: two of the four targets are
-     * integer formats and cannot be blended, and no texture may be a render attachment and a
-     * sampled source in the same pass.
-     */
-    AfterGBuffer: 1,
-
-    /**
-     * Opaque surfaces are lit and composited, and volumetrics are over them. Transparency has not
-     * run, so anything drawn here is something transparent surfaces should blend over.
-     */
-    AfterLighting: 2,
-
-    /**
-     * Transparency is resolved. The colour is the complete scene, still in HDR and still at the
-     * internal render resolution — this is where a full-screen effect that should be tonemapped
-     * along with the scene belongs, and it is where an extension drawing into the scene belongs
-     * unless it has a reason to be on the far side of the upscale.
-     */
-    AfterTransparency: 3,
-
-    /**
-     * The end of the post chain, immediately before tonemapping, and after the upscale: still HDR,
-     * at output resolution. An extension here is the last one whose output goes through the
-     * tonemapper.
-     *
-     * {@link GBufferTextures} is still carried and is now a different size from the colour beside
-     * it; {@link FrameContext.describe} is how a pass working across that boundary learns the ratio.
-     */
-    BeforePresent: 4,
-
-    /**
-     * After tonemapping, drawing onto the canvas in display space. Nothing further processes this,
-     * which is what makes it the right phase for interface: overlays, gizmos, a minimap blit.
-     *
-     * **The canvas is written here and cannot be read.** A texture may not be a render attachment
-     * and a sampled source in the same pass, so anything that needs the finished image as *input* —
-     * a full-screen re-composite, a colour grade, fog over the whole frame — belongs at
-     * {@link BeforePresent}. That is why {@link SceneColor} is not carried here and
-     * {@link PresentTarget} is a different record with one field: there is no colour to be tempted
-     * by, and an extension that wanted one finds out at `get` time.
-     */
-    Overlay: 5,
-};
-
-/**
- * @type {string[]}
- */
-const NAMES = Object.keys(FramePhase);
-
-/**
- * Name of a phase, for a diagnostic that has to say which one it means.
- *
- * @param {FramePhase} phase
- * @returns {string}
- */
-export function frame_phase_name(phase) {
-    return NAMES[phase];
-}
+/**
+ * Points in a frame at which a {@link RenderExtension} records into the frame's graph.
+ *
+ * A frame is otherwise a closed sequence, and working around a closed pipeline is precisely what
+ * made the engine this one replaces awkward. These are the sanctioned way in: each names a moment
+ * where a specific set of frame records exists and is stable, and an extension registered against
+ * one is handed exactly those.
+ *
+ * The order below is the order they occur in.
+ *
+ * **The upscale is a phase boundary, and saying so is part of what a phase means.**
+ * {@link AfterGBuffer}, {@link AfterLighting} and {@link AfterTransparency} are before it and run at
+ * the internal render resolution; TAA and NSS upscale to the output resolution, so
+ * {@link BeforePresent} and {@link Overlay} are after it. With `feature_taa_enabled === false` the
+ * upscale does not happen at all and the two sides are the same size. Nothing here is a constant an
+ * extension may rely on: {@link FrameContext.resolution} is derived from the live handle and is
+ * right in every configuration, which is what the single `resolution` field it replaces was not.
+ *
+ * **Before the upscale is the common case, and the design leans on it.** An extension drawing into
+ * the scene belongs at {@link AfterTransparency}: its work is then temporally resolved, upscaled and
+ * sharpened along with everything else, and it draws at internal resolution.
+ * {@link BeforePresent} is the deliberate other choice — full output resolution, still HDR — and it
+ * is a trade rather than an upgrade: work there gets no temporal history and costs full-resolution
+ * pixels.
+ *
+ * @enum {number}
+ */
+export const FramePhase = {
+    /**
+     * The view is updated and nothing has been rasterized. There are no frame records yet — the
+     * view is all there is — so this is the phase for per-frame GPU compute that later phases
+     * depend on: a visibility grid update, a custom cull, a procedural buffer build.
+     *
+     * It exists so that such work has somewhere to go that is inside the graph. Bolted onto a draw
+     * pass at a later phase it sits in the wrong place in the graph and is mis-attributed in a
+     * capture; done outside the graph it is invisible to aliasing and lifetime reasoning entirely.
+     */
+    FrameStart: 0,
+
+    /**
+     * The G-buffer is resolved — albedo, normal, PBR and emissive are written and readable — and
+     * nothing has been lit yet. {@link GBufferTextures} and {@link ViewTextures} are carried; there
+     * is no scene colour, which is what makes this the phase for surface work.
+     *
+     * **This is the one phase where the G-buffer may be published into.** A pass reads the targets,
+     * writes replacements and publishes their handles, and the rest of the frame carries those.
+     * Replacing rather than writing in place is not a preference: two of the four targets are
+     * integer formats and cannot be blended, and no texture may be a render attachment and a
+     * sampled source in the same pass.
+     */
+    AfterGBuffer: 1,
+
+    /**
+     * Opaque surfaces are lit and composited, and volumetrics are over them. Transparency has not
+     * run, so anything drawn here is something transparent surfaces should blend over.
+     */
+    AfterLighting: 2,
+
+    /**
+     * Transparency is resolved. The colour is the complete scene, still in HDR and still at the
+     * internal render resolution — this is where a full-screen effect that should be tonemapped
+     * along with the scene belongs, and it is where an extension drawing into the scene belongs
+     * unless it has a reason to be on the far side of the upscale.
+     */
+    AfterTransparency: 3,
+
+    /**
+     * The end of the post chain, immediately before tonemapping, and after the upscale: still HDR,
+     * at output resolution. An extension here is the last one whose output goes through the
+     * tonemapper.
+     *
+     * {@link GBufferTextures} is still carried and is now a different size from the colour beside
+     * it; {@link FrameContext.describe} is how a pass working across that boundary learns the ratio.
+     */
+    BeforePresent: 4,
+
+    /**
+     * After tonemapping, drawing onto the canvas in display space. Nothing further processes this,
+     * which is what makes it the right phase for interface: overlays, gizmos, a minimap blit.
+     *
+     * **The canvas is written here and cannot be read.** A texture may not be a render attachment
+     * and a sampled source in the same pass, so anything that needs the finished image as *input* —
+     * a full-screen re-composite, a colour grade, fog over the whole frame — belongs at
+     * {@link BeforePresent}. That is why {@link SceneColor} is not carried here and
+     * {@link PresentTarget} is a different record with one field: there is no colour to be tempted
+     * by, and an extension that wanted one finds out at `get` time.
+     */
+    Overlay: 5,
+};
+
+/**
+ * @type {string[]}
+ */
+const NAMES = Object.keys(FramePhase);
+
+/**
+ * Name of a phase, for a diagnostic that has to say which one it means.
+ *
+ * @param {FramePhase} phase
+ * @returns {string}
+ */
+export function frame_phase_name(phase) {
+    return NAMES[phase];
+}

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

@@ -1,126 +1,126 @@
-import { assert } from "../../../core/assert.js";
-import { frame_phase_name } from "./FramePhase.js";
-
-/**
- * A typed bundle of frame-graph handles that the frame carries from one phase to the next.
- *
- * This is the whole channel between an extension and the rest of the frame. An extension reads a
- * handle out of a record and writes a replacement back, and **writing a field is publication**:
- * everything after it carries what was left there. There is no return value from `record()` and no
- * privileged resource — the scene colour is published exactly the way a G-buffer target is, and
- * exactly the way an extension's own record is.
- *
- * Subclasses are plain classes with named fields. The vocabulary is open: an extension declares a
- * record of its own by extending this and calling {@link FrameContext.create}, which costs no edit
- * to Shade. Such a record is carried at every phase, because nothing about the frame's structure
- * says otherwise.
- *
- * **Publication is not the dependency edge.** `FramePassBuilder.write` renames a written resource
- * into a versioned clone and records the read, so "this pass consumed the colour as it stood and
- * produced a new one" is already a graph fact. Publication is the *naming* step — which handle
- * currently means "the scene colour".
- */
-export class FrameRecord {
-    /**
-     * Phases at which the frame carries this record. Asked before an instance exists, which is what
-     * lets {@link FrameContext.get} say where a record *is* carried rather than only that it is not
-     * here.
-     *
-     * @param {FramePhase} phase
-     * @returns {boolean}
-     */
-    static is_present_at(phase) {
-        return true;
-    }
-
-    /**
-     * Phases at which a field of this record may be published into. Never wider than
-     * {@link is_present_at}: a record that is not carried cannot be written.
-     *
-     * A record that is carried but not writable is *frozen*, and the G-buffer after shading is the
-     * case that matters — reading it late is legitimate and publishing into it is meaningless.
-     *
-     * @param {FramePhase} phase
-     * @returns {boolean}
-     */
-    static is_writable_at(phase) {
-        return this.is_present_at(phase);
-    }
-
-    /**
-     * The frame this record belongs to. Records are per-frame, so a record held across frames is a
-     * retained handle by another name, and both reading and publishing say so.
-     *
-     * @type {FrameContext|null}
-     */
-    #frame = null;
-
-    /**
-     * @returns {FrameContext}
-     */
-    get frame() {
-        return this.#frame;
-    }
-
-    /**
-     * Bind this record to the frame carrying it. Called by {@link FrameContext.create}; not part of
-     * the surface an extension uses.
-     *
-     * @param {FrameContext} frame
-     */
-    link(frame) {
-        assert.defined(frame, 'frame');
-        assert.isNull(this.#frame, `${this.constructor.name} is already linked to a frame`);
-
-        this.#frame = frame;
-    }
-
-    /**
-     * The guard every field's getter goes through. Not something an extension calls.
-     *
-     * @param {number} handle
-     * @returns {number} `handle`
-     */
-    read(handle) {
-        const frame = this.#frame;
-
-        assert.notNull(frame, `${this.constructor.name} was read without belonging to a frame`);
-        assert.equal(frame.is_open, true, `${this.constructor.name} belongs to a frame that has finished, so the handles in it name resources of a graph that is gone`);
-        assert.isNonNegativeInteger(handle, `${this.constructor.name} field read before the frame put a handle in it`);
-
-        return handle;
-    }
-
-    /**
-     * The guard every field's setter goes through — the three checks publication asserts. Not
-     * something an extension calls.
-     *
-     * The `is_valid_resource` check exists for **attribution** rather than detection. The graph
-     * catches a superseded handle on its own, at `compile()`, and against whoever *reads* it — so
-     * that report names a built-in pass downstream and says nothing about which extension put the
-     * bad handle into the record. Checking here fails at the line that caused it.
-     *
-     * @param {number} handle
-     * @returns {number} `handle`
-     */
-    publish(handle) {
-        const frame = this.#frame;
-        const name = this.constructor.name;
-
-        assert.notNull(frame, `${name} was published into without belonging to a frame`);
-        assert.equal(frame.is_open, true, `${name} belongs to a frame that has finished; a handle from one frame cannot be published into another`);
-        assert.isNonNegativeInteger(handle, `${name} handle`);
-        assert.equal(
-            this.constructor.is_writable_at(frame.phase),
-            true,
-            `${name} is not writable at ${frame_phase_name(frame.phase)}`
-        );
-        assert.equal(
-            frame.graph.is_valid_resource(handle),
-            true,
-            `${name} was published a superseded handle — one resource entry owns one concrete resource, so an older version of it is not a snapshot of older contents`
-        );
-
-        return handle;
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { frame_phase_name } from "./FramePhase.js";
+
+/**
+ * A typed bundle of frame-graph handles that the frame carries from one phase to the next.
+ *
+ * This is the whole channel between an extension and the rest of the frame. An extension reads a
+ * handle out of a record and writes a replacement back, and **writing a field is publication**:
+ * everything after it carries what was left there. There is no return value from `record()` and no
+ * privileged resource — the scene colour is published exactly the way a G-buffer target is, and
+ * exactly the way an extension's own record is.
+ *
+ * Subclasses are plain classes with named fields. The vocabulary is open: an extension declares a
+ * record of its own by extending this and calling {@link FrameContext.create}, which costs no edit
+ * to Shade. Such a record is carried at every phase, because nothing about the frame's structure
+ * says otherwise.
+ *
+ * **Publication is not the dependency edge.** `FramePassBuilder.write` renames a written resource
+ * into a versioned clone and records the read, so "this pass consumed the colour as it stood and
+ * produced a new one" is already a graph fact. Publication is the *naming* step — which handle
+ * currently means "the scene colour".
+ */
+export class FrameRecord {
+    /**
+     * Phases at which the frame carries this record. Asked before an instance exists, which is what
+     * lets {@link FrameContext.get} say where a record *is* carried rather than only that it is not
+     * here.
+     *
+     * @param {FramePhase} phase
+     * @returns {boolean}
+     */
+    static is_present_at(phase) {
+        return true;
+    }
+
+    /**
+     * Phases at which a field of this record may be published into. Never wider than
+     * {@link is_present_at}: a record that is not carried cannot be written.
+     *
+     * A record that is carried but not writable is *frozen*, and the G-buffer after shading is the
+     * case that matters — reading it late is legitimate and publishing into it is meaningless.
+     *
+     * @param {FramePhase} phase
+     * @returns {boolean}
+     */
+    static is_writable_at(phase) {
+        return this.is_present_at(phase);
+    }
+
+    /**
+     * The frame this record belongs to. Records are per-frame, so a record held across frames is a
+     * retained handle by another name, and both reading and publishing say so.
+     *
+     * @type {FrameContext|null}
+     */
+    #frame = null;
+
+    /**
+     * @returns {FrameContext}
+     */
+    get frame() {
+        return this.#frame;
+    }
+
+    /**
+     * Bind this record to the frame carrying it. Called by {@link FrameContext.create}; not part of
+     * the surface an extension uses.
+     *
+     * @param {FrameContext} frame
+     */
+    link(frame) {
+        assert.defined(frame, 'frame');
+        assert.isNull(this.#frame, `${this.constructor.name} is already linked to a frame`);
+
+        this.#frame = frame;
+    }
+
+    /**
+     * The guard every field's getter goes through. Not something an extension calls.
+     *
+     * @param {number} handle
+     * @returns {number} `handle`
+     */
+    read(handle) {
+        const frame = this.#frame;
+
+        assert.notNull(frame, `${this.constructor.name} was read without belonging to a frame`);
+        assert.equal(frame.is_open, true, `${this.constructor.name} belongs to a frame that has finished, so the handles in it name resources of a graph that is gone`);
+        assert.isNonNegativeInteger(handle, `${this.constructor.name} field read before the frame put a handle in it`);
+
+        return handle;
+    }
+
+    /**
+     * The guard every field's setter goes through — the three checks publication asserts. Not
+     * something an extension calls.
+     *
+     * The `is_valid_resource` check exists for **attribution** rather than detection. The graph
+     * catches a superseded handle on its own, at `compile()`, and against whoever *reads* it — so
+     * that report names a built-in pass downstream and says nothing about which extension put the
+     * bad handle into the record. Checking here fails at the line that caused it.
+     *
+     * @param {number} handle
+     * @returns {number} `handle`
+     */
+    publish(handle) {
+        const frame = this.#frame;
+        const name = this.constructor.name;
+
+        assert.notNull(frame, `${name} was published into without belonging to a frame`);
+        assert.equal(frame.is_open, true, `${name} belongs to a frame that has finished; a handle from one frame cannot be published into another`);
+        assert.isNonNegativeInteger(handle, `${name} handle`);
+        assert.equal(
+            this.constructor.is_writable_at(frame.phase),
+            true,
+            `${name} is not writable at ${frame_phase_name(frame.phase)}`
+        );
+        assert.equal(
+            frame.graph.is_valid_resource(handle),
+            true,
+            `${name} was published a superseded handle — one resource entry owns one concrete resource, so an older version of it is not a snapshot of older contents`
+        );
+
+        return handle;
+    }
+}

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

@@ -1,83 +1,83 @@
-import { FramePhase } from "./FramePhase.js";
-import { FrameRecord } from "./FrameRecord.js";
-
-/**
- * Surface properties, written by the material pass.
- *
- * **In/out at {@link FramePhase.AfterGBuffer}, frozen afterwards.** An extension at that phase reads
- * these targets, writes replacements and publishes the new handles, and everything downstream —
- * shading included — carries what it left. That is what makes changing surface properties possible
- * at all: two of the four targets are integer formats and cannot be blended, and no texture may be
- * a render attachment and a sampled source in the same pass.
- *
- * It stays carried through {@link FramePhase.BeforePresent}, because outline and selection effects
- * legitimately read it late. Publishing into it there is meaningless — shading has run — so it is
- * frozen and the assert says so. At `BeforePresent` it is also on the far side of the upscale from
- * the scene colour and therefore a **different size**; {@link FrameContext.describe} is how a pass
- * working across that boundary learns the ratio.
- */
-export class GBufferTextures extends FrameRecord {
-    #albedo = -1;
-    #normal = -1;
-    #pbr = -1;
-    #emissive = -1;
-
-    static is_present_at(phase) {
-        return phase === FramePhase.AfterGBuffer
-            || phase === FramePhase.AfterLighting
-            || phase === FramePhase.AfterTransparency
-            || phase === FramePhase.BeforePresent;
-    }
-
-    static is_writable_at(phase) {
-        return phase === FramePhase.AfterGBuffer;
-    }
-
-    /**
-     * Base colour, with ambient occlusion in the alpha channel.
-     *
-     * @returns {number}
-     */
-    get albedo() {
-        return this.read(this.#albedo);
-    }
-
-    set albedo(handle) {
-        this.#albedo = this.publish(handle);
-    }
-
-    /**
-     * @returns {number}
-     */
-    get normal() {
-        return this.read(this.#normal);
-    }
-
-    set normal(handle) {
-        this.#normal = this.publish(handle);
-    }
-
-    /**
-     * Roughness, metalness and what else the standard material carries.
-     *
-     * @returns {number}
-     */
-    get pbr() {
-        return this.read(this.#pbr);
-    }
-
-    set pbr(handle) {
-        this.#pbr = this.publish(handle);
-    }
-
-    /**
-     * @returns {number}
-     */
-    get emissive() {
-        return this.read(this.#emissive);
-    }
-
-    set emissive(handle) {
-        this.#emissive = this.publish(handle);
-    }
-}
+import { FramePhase } from "./FramePhase.js";
+import { FrameRecord } from "./FrameRecord.js";
+
+/**
+ * Surface properties, written by the material pass.
+ *
+ * **In/out at {@link FramePhase.AfterGBuffer}, frozen afterwards.** An extension at that phase reads
+ * these targets, writes replacements and publishes the new handles, and everything downstream —
+ * shading included — carries what it left. That is what makes changing surface properties possible
+ * at all: two of the four targets are integer formats and cannot be blended, and no texture may be
+ * a render attachment and a sampled source in the same pass.
+ *
+ * It stays carried through {@link FramePhase.BeforePresent}, because outline and selection effects
+ * legitimately read it late. Publishing into it there is meaningless — shading has run — so it is
+ * frozen and the assert says so. At `BeforePresent` it is also on the far side of the upscale from
+ * the scene colour and therefore a **different size**; {@link FrameContext.describe} is how a pass
+ * working across that boundary learns the ratio.
+ */
+export class GBufferTextures extends FrameRecord {
+    #albedo = -1;
+    #normal = -1;
+    #pbr = -1;
+    #emissive = -1;
+
+    static is_present_at(phase) {
+        return phase === FramePhase.AfterGBuffer
+            || phase === FramePhase.AfterLighting
+            || phase === FramePhase.AfterTransparency
+            || phase === FramePhase.BeforePresent;
+    }
+
+    static is_writable_at(phase) {
+        return phase === FramePhase.AfterGBuffer;
+    }
+
+    /**
+     * Base colour, with ambient occlusion in the alpha channel.
+     *
+     * @returns {number}
+     */
+    get albedo() {
+        return this.read(this.#albedo);
+    }
+
+    set albedo(handle) {
+        this.#albedo = this.publish(handle);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get normal() {
+        return this.read(this.#normal);
+    }
+
+    set normal(handle) {
+        this.#normal = this.publish(handle);
+    }
+
+    /**
+     * Roughness, metalness and what else the standard material carries.
+     *
+     * @returns {number}
+     */
+    get pbr() {
+        return this.read(this.#pbr);
+    }
+
+    set pbr(handle) {
+        this.#pbr = this.publish(handle);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get emissive() {
+        return this.read(this.#emissive);
+    }
+
+    set emissive(handle) {
+        this.#emissive = this.publish(handle);
+    }
+}