@woosh/meep-engine 3.11.3 → 3.13.0

package/src/engine/graphics3/DecalSystem.js

@@ -0,0 +1,441 @@
+import { assert } from "../../core/assert.js";
+import { LoadingCache } from "../../core/cache/LoadingCache.js";
+import { strictEquals } from "../../core/function/strictEquals.js";
+import { computeStringHash } from "../../core/primitives/strings/computeStringHash.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { TerrainExtension } from "./TerrainSystem.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { GameAssetType } from "../asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { Decal } from "../graphics/ecs/decal/v2/Decal.js";
+import { ReferencedTextureAtlas } from "../graphics/texture/atlas/ReferencedTextureAtlas.js";
+import { sampler2d_ensure_uint8_RGBA } from "../graphics/texture/sampler/sampler2d_ensure_uint8_RGBA.js";
+import { DecalAtlas } from "./decal/DecalAtlas.js";
+import { DecalAtlasFill } from "./decal/DecalAtlasFill.js";
+import { decal_atlas_max_lod } from "./decal/decal_atlas_border.js";
+import {
+    decal_identity_normal,
+    decal_identity_orm,
+    decal_pack_orm
+} from "./decal/decal_material_samplers.js";
+import { DECAL_RECORD_WORD_COUNT } from "./decal/DECAL_GPU_RECORD.js";
+import { sort_decals_by_priority, write_decal_record } from "./decal/decal_gpu_records.js";
+import { GPUDecalRenderer } from "./decal/GPUDecalRenderer.js";
+
+/**
+ * Paints the game's decals into the G-buffer under Shade.
+ *
+ * **A decal is a surface override, not a tint** (D22): it carries albedo, a tangent-space normal,
+ * roughness, metalness and emission, and it writes them into the G-buffer before anything is lit —
+ * so ambient occlusion, screen-space reflection and shading all see a decal exactly as they see the
+ * surface it is painted on. The renderer this replaces could only lerp diffuse colour inside a
+ * forward shader.
+ *
+ * **Decals reach opaque surfaces only, by construction.** The G-buffer is all they touch and
+ * transparency composites later, so a decal will never appear on water.
+ *
+ * The records are rebuilt every frame. That sounds wasteful and is the cheaper arrangement: the
+ * froxel binning depends on the camera and so has to run every frame regardless, and rebuilding the
+ * records alongside it means nothing has to watch a decal's colour for changes — which matters,
+ * because the signal that would be watched does not fire for alpha-only edits.
+ */
+export class DecalSystem extends System {
+    dependencies = [Decal, Transform];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {AssetManager}
+     */
+    #assets;
+
+    /**
+     * @type {GPUDecalRenderer}
+     */
+    #renderer = new GPUDecalRenderer();
+
+    /**
+     * Three atlases, because their contents want different mip filters and different border fills —
+     * and because albedo is sRGB while the other two are not.
+     *
+     * @type {DecalAtlas}
+     */
+    #atlas_albedo = new DecalAtlas(DecalAtlasFill.PremultipliedCoverage);
+
+    /**
+     * @type {DecalAtlas}
+     */
+    #atlas_normal = new DecalAtlas(DecalAtlasFill.EdgeExtend);
+
+    /**
+     * @type {DecalAtlas}
+     */
+    #atlas_orm = new DecalAtlas(DecalAtlasFill.EdgeExtend);
+
+    /**
+     * @type {ReferencedTextureAtlas}
+     */
+    #referenced_albedo = new ReferencedTextureAtlas(this.#atlas_albedo);
+
+    /**
+     * @type {ReferencedTextureAtlas}
+     */
+    #referenced_normal = new ReferencedTextureAtlas(this.#atlas_normal);
+
+    /**
+     * @type {ReferencedTextureAtlas}
+     */
+    #referenced_orm = new ReferencedTextureAtlas(this.#atlas_orm);
+
+    /**
+     * What every decal authoring no maps of its own shares. One patch each, packed once.
+     *
+     * @type {Sampler2D}
+     */
+    #identity_normal = decal_identity_normal();
+
+    /**
+     * @type {Sampler2D}
+     */
+    #identity_orm = decal_identity_orm();
+
+    /**
+     * @type {LoadingCache<string, Sampler2D>}
+     */
+    #textures;
+
+    /**
+     * The decals to draw, in link order until {@link update} sorts them into draw order.
+     *
+     * @type {Array<{entity: number, decal: Decal, transform: Transform, patches: object, listener: Function}>}
+     */
+    #entries = [];
+
+    /**
+     * @type {Map<number, object>}
+     */
+    #by_entity = new Map();
+
+    /**
+     * @type {Float32Array}
+     */
+    #records = new Float32Array(0);
+
+    /**
+     * @type {number}
+     */
+    #record_count = 0;
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * What the pass draws. Read-only — the decals follow the entities.
+     *
+     * @returns {Array}
+     */
+    get decals() {
+        return this.#entries;
+    }
+
+    /**
+     * @returns {number} decals packed for the GPU by the last update
+     */
+    get record_count() {
+        return this.#record_count;
+    }
+
+    /**
+     * What was packed, for a gate that wants to see it. Read-only.
+     *
+     * @returns {Float32Array}
+     */
+    get records() {
+        return this.#records;
+    }
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {AssetManager} assets
+     */
+    constructor(graphics, assets) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(assets, 'assets');
+
+        this.#graphics = graphics;
+        this.#assets = assets;
+
+        this.#textures = new LoadingCache({
+            load: key => this.#assets.promise(key, GameAssetType.Image)
+                .then(asset => sampler2d_ensure_uint8_RGBA(asset.create())),
+            keyHashFunction: computeStringHash,
+            keyEqualityFunction: strictEquals
+        });
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        const assets = this.#assets;
+
+        if (!assets.hasLoaderForType(GameAssetType.Image)) {
+            await assets.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
+        }
+
+        this.#extension = this.#graphics.add_extension(new DecalExtension(this));
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        this.#renderer.destroy();
+
+        this.#entries.length = 0;
+        this.#by_entity.clear();
+        this.#record_count = 0;
+    }
+
+    /**
+     * @param {Decal} decal
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(decal, transform, entity) {
+        const entry = {
+            entity,
+            decal,
+            transform,
+            /**
+             * Atlas patches, acquired as the textures arrive. A decal whose albedo has not loaded
+             * yet is not packed at all — there is nothing to draw with, and drawing it with the
+             * identity patch would put a white square on the ground until the image landed.
+             */
+            patches: { albedo: null, normal: null, orm: null }
+        };
+
+        this.#entries.push(entry);
+        this.#by_entity.set(entity, entry);
+
+        this.#acquire(entry);
+    }
+
+    /**
+     * @param {Decal} decal
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(decal, transform, entity) {
+        const entry = this.#by_entity.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#release(entry);
+
+        const index = this.#entries.indexOf(entry);
+
+        if (index !== -1) {
+            this.#entries.splice(index, 1);
+        }
+
+        this.#by_entity.delete(entity);
+    }
+
+    /**
+     * @param {object} entry
+     */
+    #release(entry) {
+        const patches = entry.patches;
+
+        if (patches.albedo !== null) {
+            patches.albedo.release();
+            patches.albedo = null;
+        }
+
+        if (patches.normal !== null) {
+            patches.normal.release();
+            patches.normal = null;
+        }
+
+        if (patches.orm !== null) {
+            patches.orm.release();
+            patches.orm = null;
+        }
+    }
+
+    /**
+     * Fetch this decal's textures and take a reference on the atlas patch each lands in.
+     *
+     * Reference counted, because combat spawns a footprint decal per step and every one of them
+     * names the same file: packing a patch per footprint would repack three atlases and regenerate
+     * their mip chains several times a second.
+     *
+     * @param {object} entry
+     */
+    #acquire(entry) {
+        const decal = entry.decal;
+
+        const albedo_uri = decal.albedo_uri;
+
+        if (albedo_uri === "") {
+            return;
+        }
+
+        this.#textures.get(albedo_uri).then(sampler => {
+            if (this.#by_entity.get(entry.entity) !== entry) {
+                // unlinked while the image was in flight
+                return;
+            }
+
+            entry.patches.albedo = this.#referenced_albedo.acquire(sampler);
+        });
+
+        if (decal.uri_normal === "") {
+            entry.patches.normal = this.#referenced_normal.acquire(this.#identity_normal);
+        } else {
+            this.#textures.get(decal.uri_normal).then(sampler => {
+                if (this.#by_entity.get(entry.entity) !== entry) {
+                    return;
+                }
+
+                entry.patches.normal = this.#referenced_normal.acquire(sampler);
+            });
+        }
+
+        if (decal.uri_orm === "" && decal.uri_emissive === "") {
+            entry.patches.orm = this.#referenced_orm.acquire(this.#identity_orm);
+
+            return;
+        }
+
+        Promise.all([
+            decal.uri_orm === "" ? null : this.#textures.get(decal.uri_orm),
+            decal.uri_emissive === "" ? null : this.#textures.get(decal.uri_emissive)
+        ]).then(([orm, emissive]) => {
+            if (this.#by_entity.get(entry.entity) !== entry) {
+                return;
+            }
+
+            entry.patches.orm = this.#referenced_orm.acquire(decal_pack_orm(orm, emissive));
+        });
+    }
+
+    update(timeDelta) {
+        const entries = this.#entries;
+
+        sort_decals_by_priority(entries);
+
+        this.#atlas_albedo.update();
+        this.#atlas_normal.update();
+        this.#atlas_orm.update();
+
+        const required = entries.length * DECAL_RECORD_WORD_COUNT;
+
+        if (this.#records.length < required) {
+            this.#records = new Float32Array(required);
+        }
+
+        const records = this.#records;
+
+        let count = 0;
+
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            const patches = entry.patches;
+
+            if (patches.albedo === null || patches.normal === null || patches.orm === null) {
+                // still waiting on an image; a decal is packed once it can be drawn properly
+                continue;
+            }
+
+            const albedo = patches.albedo.getValue();
+            const normal = patches.normal.getValue();
+            const orm = patches.orm.getValue();
+
+            write_decal_record(
+                records,
+                count * DECAL_RECORD_WORD_COUNT,
+                entry.decal,
+                entry.transform.matrix,
+                { albedo: albedo.uv, normal: normal.uv, orm: orm.uv },
+                {
+                    albedo: decal_atlas_max_lod(albedo.padding),
+                    normal: decal_atlas_max_lod(normal.padding),
+                    orm: decal_atlas_max_lod(orm.padding)
+                }
+            );
+
+            count++;
+        }
+
+        this.#record_count = count;
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        if (this.#record_count === 0) {
+            /*
+             Nothing to paint, so the frame keeps the G-buffer it already had. Skipping is what makes
+             the replacement design free when no decal is on screen — the pass reads and rewrites
+             every pixel when it runs.
+            */
+            return;
+        }
+
+        this.#renderer.graph_draw({
+            frame,
+            records: this.#records,
+            record_count: this.#record_count,
+            atlas_albedo: this.#atlas_albedo.sampler,
+            atlas_normal: this.#atlas_normal.sampler,
+            atlas_orm: this.#atlas_orm.sampler
+        });
+    }
+}
+
+/**
+ * **After the terrain**, because the decal composite has to see the textured ground rather than
+ * precede it. That requirement used to be met by putting a registration call above an `await` and
+ * writing a comment about it; here it is the declaration below.
+ */
+export class DecalExtension extends RenderExtension {
+    name = "decals";
+
+    phase = FramePhase.AfterGBuffer;
+
+    after = [TerrainExtension];
+
+    /**
+     * @type {DecalSystem}
+     */
+    #system;
+
+    /**
+     * @param {DecalSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}

package/src/engine/graphics3/DecalSystem3.d.ts

@@ -1,81 +1,10 @@
 /**
- * Paints the game's decals into the G-buffer under Shade.
+ * @deprecated Renamed to {@link DecalSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **A decal is a surface override, not a tint** (D22): it carries albedo, a tangent-space normal,
- * roughness, metalness and emission, and it writes them into the G-buffer before anything is lit —
- * so ambient occlusion, screen-space reflection and shading all see a decal exactly as they see the
- * surface it is painted on. The renderer this replaces could only lerp diffuse colour inside a
- * forward shader.
- *
- * **Decals reach opaque surfaces only, by construction.** The G-buffer is all they touch and
- * transparency composites later, so a decal will never appear on water.
- *
- * The records are rebuilt every frame. That sounds wasteful and is the cheaper arrangement: the
- * froxel binning depends on the camera and so has to run every frame regardless, and rebuilding the
- * records alongside it means nothing has to watch a decal's colour for changes — which matters,
- * because the signal that would be watched does not fire for alpha-only edits.
- */
-export class DecalSystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {AssetManager} assets
-     */
-    constructor(graphics: GraphicsEngine3, assets: AssetManager);
-    dependencies: (typeof Transform | typeof Decal)[];
-    /**
-     * What the pass draws. Read-only — the decals follow the entities.
-     *
-     * @returns {Array}
-     */
-    get decals(): any[];
-    /**
-     * @returns {number} decals packed for the GPU by the last update
-     */
-    get record_count(): number;
-    /**
-     * What was packed, for a gate that wants to see it. Read-only.
-     *
-     * @returns {Float32Array}
-     */
-    get records(): Float32Array;
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {Decal} decal
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(decal: Decal, transform: Transform, entity: number): void;
-    /**
-     * @param {Decal} decal
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(decal: Decal, transform: Transform, entity: number): void;
-    update(timeDelta: any): void;
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame: FrameContext): void;
-    #private;
-}
-/**
- * **After the terrain**, because the decal composite has to see the textured ground rather than
- * precede it. That requirement used to be met by putting a registration call above an `await` and
- * writing a comment about it; here it is the declaration below.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class DecalExtension extends RenderExtension {
-    /**
-     * @param {DecalSystem3} system
-     */
-    constructor(system: DecalSystem3);
-    after: (typeof TerrainExtension)[];
-    record(frame: any): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { Decal } from "../graphics/ecs/decal/v2/Decal.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { TerrainExtension } from "./TerrainSystem3.js";
+export const DecalSystem3: typeof DecalSystem;
+import { DecalSystem } from "./DecalSystem.js";
 //# sourceMappingURL=DecalSystem3.d.ts.map

package/src/engine/graphics3/DecalSystem3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DecalSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/DecalSystem3.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;GAgBG;AACH;IAwHI;;;OAGG;IACH,6DAeC;IA1ID,kDAAkC;IA8FlC;;;;OAIG;IACH,oBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,4BAEC;IAuBD,2CAUC;IAED,4CAYC;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,SAAS,UACT,MAAM,QAmBhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,SAAS,UACT,MAAM,QAkBhB;IAiFD,6BAiDC;IAED;;OAEG;IACH,kCAkBC;;CACJ;AAED;;;;GAIG;AACH;IAYI;;OAEG;IACH,oBAFW,YAAY,EAMtB;IAdD,mCAA2B;IAgB3B,yBAEC;;CACJ;uBA/asB,kBAAkB;0BACf,+BAA+B;sBACnC,mCAAmC;gCALzB,mDAAmD;iCADlD,qBAAqB"}
+{"version":3,"file":"DecalSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/DecalSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,8CAAwC;4BATZ,kBAAkB"}