@woosh/meep-engine 3.53.0 → 3.55.0

package/src/engine/graphics/texture/atlas/ManagedTextureAtlas.d.ts

@@ -1,31 +1,110 @@
+/**
+ * @typedef {object} ManagedAtlasRecord
+ * @property {string} key
+ * @property {number} references
+ * @property {import("../sampler/Sampler2D.js").Sampler2D|null} sampler
+ * @property {import("./AtlasPatch.js").AtlasPatch|null} patch
+ * @property {boolean} loading
+ */
+/**
+ * Synchronous reference handle to an asynchronously loaded {@link AtlasPatch} in a
+ * {@link ManagedAtlas}.
+ *
+ * {@link getValue} is `null` while the texture is still in flight (or if loading failed or the
+ * handle was released) and returns the packed {@link AtlasPatch} once ready — or immediately on
+ * the same tick when the key hits a live or graveyard entry.
+ */
+export class ManagedAtlasReference {
+    /**
+     * @param {ManagedAtlas} owner
+     * @param {ManagedAtlasRecord} record
+     */
+    constructor(owner: ManagedAtlas, record: ManagedAtlasRecord);
+    /**
+     * @returns {import("./AtlasPatch.js").AtlasPatch|null}
+     */
+    getValue(): import("./AtlasPatch.js").AtlasPatch | null;
+    /**
+     * @returns {boolean}
+     */
+    get is_bound(): boolean;
+    /**
+     * Release this caller's claim on the patch. Idempotent.
+     */
+    release(): void;
+    #private;
+}
+/**
+ * Reference-counted, graveyard-cached texture atlas manager.
+ *
+ * Coordinates asynchronous key loading, in-memory sampler retention while a patch sits in
+ * {@link CachingTextureAtlas}'s graveyard, synchronous graveyard resurrection on re-acquire, and
+ * eviction cleanup when the underlying {@link TextureAtlas} reaps a graveyard slot.
+ */
 export class ManagedAtlas {
     /**
-     *
-     * @param {AssetManager} assetManager
-     * @constructor
+     * @param {object} [params]
+     * @param {import("../../../asset/AssetManager.js").AssetManager|null} [params.assetManager]
+     * @param {import("./TextureAtlas.js").TextureAtlas} [params.atlas]
+     * @param {((key: string) => Promise<import("../sampler/Sampler2D.js").Sampler2D>)|null} [params.load]
+     */
+    constructor({ assetManager, atlas, load }?: {
+        assetManager?: import("../../../asset/AssetManager.js").AssetManager<any> | null;
+        atlas?: import("./TextureAtlas.js").TextureAtlas;
+        load?: ((key: string) => Promise<import("../sampler/Sampler2D.js").Sampler2D>) | null;
+    });
+    /**
+     * @type {import("./TextureAtlas.js").TextureAtlas}
+     */
+    atlas: import("./TextureAtlas.js").TextureAtlas;
+    /**
+     * @type {CachingTextureAtlas}
      */
-    constructor(assetManager: AssetManager);
     __caching_atlas: CachingTextureAtlas;
     /**
-     *
-     * @type {TextureAtlas}
+     * @returns {import("../sampler/Sampler2D.js").Sampler2D}
      */
-    atlas: TextureAtlas;
-    reset(): void;
+    get sampler(): import("../sampler/Sampler2D.js").Sampler2D;
     /**
+     * @param {ManagedAtlasRecord} record
+     */
+    _release_record(record: ManagedAtlasRecord): void;
+    /**
+     * Acquire a reference-counted handle for an asynchronous texture key.
      *
      * @param {string} key
-     * @returns {Promise<Reference<AtlasPatch>>}
+     * @returns {ManagedAtlasReference}
      */
-    acquire(url: any): Promise<Reference<AtlasPatch>>;
+    acquire(key: string): ManagedAtlasReference;
     /**
+     * Acquire a reference-counted handle for an already-constructed {@link Sampler2D} (such as a
+     * shared 1x1 identity normal or ORM sampler).
      *
-     * @param {string} key
+     * @param {import("../sampler/Sampler2D.js").Sampler2D} sampler
+     * @returns {import("../../../reference/v2/Reference.js").Reference<import("./AtlasPatch.js").AtlasPatch>}
+     */
+    acquire_sampler(sampler: import("../sampler/Sampler2D.js").Sampler2D): import("../../../reference/v2/Reference.js").Reference<import("./AtlasPatch.js").AtlasPatch>;
+    /**
+     * Pack and paint any pending changes in the underlying atlas, evicting graveyard patches first
+     * if needed.
+     */
+    update(): void;
+    /**
+     * Drop all active and cached patches, invalidating any in-flight loads.
+     */
+    reset(): void;
+    /**
+     * @param {string} _key
      */
-    release(key: string): void;
+    release(_key: string): void;
     #private;
 }
+export type ManagedAtlasRecord = {
+    key: string;
+    references: number;
+    sampler: import("../sampler/Sampler2D.js").Sampler2D | null;
+    patch: import("./AtlasPatch.js").AtlasPatch | null;
+    loading: boolean;
+};
 import { CachingTextureAtlas } from "./CachingTextureAtlas.js";
-import { TextureAtlas } from "./TextureAtlas.js";
-import { Reference } from "../../../reference/v2/Reference.js";
 //# sourceMappingURL=ManagedTextureAtlas.d.ts.map

package/src/engine/graphics/texture/atlas/ManagedTextureAtlas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ManagedTextureAtlas.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/atlas/ManagedTextureAtlas.js"],"names":[],"mappings":"AAUA;IAoCI;;;;OAIG;IACH,wCAiCC;IAvBG,qCAAyD;IAEzD;;;OAGG;IACH,OAFU,YAAY,CAEJ;IAwEtB,cAcC;IAED;;;;OAIG;IACH,mBAFa,QAAQ,qBAAqB,CAAC,CAe1C;IAED;;;OAGG;IACH,aAFW,MAAM,QAIhB;;CACJ;oCA/KmC,0BAA0B;6BACjC,mBAAmB;0BAJtB,oCAAoC"}
+{"version":3,"file":"ManagedTextureAtlas.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/atlas/ManagedTextureAtlas.js"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH;IAgBI;;;OAGG;IACH,mBAHW,YAAY,UACZ,kBAAkB,EAK5B;IAED;;OAEG;IACH,YAFa,OAAO,iBAAiB,EAAE,UAAU,GAAC,IAAI,CAQrD;IAED;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,gBAOC;;CACJ;AAED;;;;;;GAMG;AACH;IA0BI;;;;;OAKG;IACH;QAJ+E,YAAY,GAAhF,6DAAsD,IAAI;QACR,KAAK,GAAvD,OAAO,mBAAmB,EAAE,YAAY;QAC8C,IAAI,GAA1F,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,QAAQ,OAAO,yBAAyB,EAAE,SAAS,CAAC,CAAC,GAAC,IAAI;OAwBtF;IAfG;;OAEG;IACH,OAFU,OAAO,mBAAmB,EAAE,YAAY,CAEhC;IAElB;;OAEG;IACH,iBAFU,mBAAmB,CAE4B;IAS7D;;OAEG;IACH,2DAEC;IA6ED;;OAEG;IACH,wBAFW,kBAAkB,QAkB5B;IAED;;;;;OAKG;IACH,aAHW,MAAM,GACJ,qBAAqB,CA6BjC;IAED;;;;;;OAMG;IACH,yBAHW,OAAO,yBAAyB,EAAE,SAAS,GACzC,OAAO,oCAAoC,EAAE,SAAS,CAAC,OAAO,iBAAiB,EAAE,UAAU,CAAC,CAIxG;IAED;;;OAGG;IACH,eAEC;IAED;;OAEG;IACH,cAUC;IAED;;OAEG;IACH,cAFW,MAAM,QAIhB;;CACJ;;SAxTa,MAAM;gBACN,MAAM;aACN,OAAO,yBAAyB,EAAE,SAAS,GAAC,IAAI;WAChD,OAAO,iBAAiB,EAAE,UAAU,GAAC,IAAI;aACzC,OAAO;;oCAXe,0BAA0B"}

package/src/engine/graphics/texture/atlas/ManagedTextureAtlas.js

@@ -1,183 +1,322 @@
-import { LoadingCache } from "../../../../core/cache/LoadingCache.js";
-import { strictEquals } from "../../../../core/function/strictEquals.js";
-import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
-import { GameAssetType } from "../../../asset/GameAssetType.js";
-import { Reference } from "../../../reference/v2/Reference.js";
-import { Sampler2D } from "../sampler/Sampler2D.js";
-import { sampler2d_ensure_uint8_RGBA } from "../sampler/sampler2d_ensure_uint8_RGBA.js";
-import { CachingTextureAtlas } from "./CachingTextureAtlas.js";
-import { TextureAtlas } from "./TextureAtlas.js";
-
-export class ManagedAtlas {
-
-    /**
-     *
-     * @type {AssetManager|null}
-     */
-    #assets = null;
-
-    /**
-     *
-     * @type {Map<string, Reference>}
-     */
-    #references = new Map();
-
-    /**
-     * Pixel padding
-     * @type {number}
-     */
-    #padding = 4;
-
-    /**
-     * @type {LoadingCache<string, AtlasPatch>}
-     */
-    #patch_loader;
-
-    /**
-     *
-     * @type {Map<string, AtlasPatch>}
-     */
-    #url_patch_lookup = new Map();
-    /**
-     *
-     * @type {Map<AtlasPatch,string[]>}
-     */
-    #patch_url_lookup = new Map();
-
-    /**
-     *
-     * @param {AssetManager} assetManager
-     * @constructor
-     */
-    constructor(assetManager) {
-        this.#assets = assetManager;
-
-        /**
-         * pre-allocate space on the atlas to avoid some initial re-sizing
-         * @type {TextureAtlas}
-         */
-        const atlas = new TextureAtlas(64);
-
-
-        this.__caching_atlas = new CachingTextureAtlas({ atlas });
-
-        /**
-         *
-         * @type {TextureAtlas}
-         */
-        this.atlas = atlas;
-
-        atlas.on.removed.add(this.#remove_from_lookup, this);
-
-        this.#patch_loader = new LoadingCache({
-            keyHashFunction: computeStringHash,
-            keyEqualityFunction: strictEquals,
-            load: async (url) => {
-                const sampler = await this.#resolve_texture(url);
-
-                const patch = this.__caching_atlas.add(sampler, this.#padding);
-
-                this.#add_to_lookup(url, patch);
-
-                return patch;
-            }
-        });
-    }
-
-    /**
-     *
-     * @param {AtlasPatch} patch
-     */
-    #remove_from_lookup(patch) {
-        const urls = this.#patch_url_lookup.get(patch);
-
-        if (urls === undefined) {
-            return;
-        }
-
-        for (let i = 0; i < urls.length; i++) {
-            const url = urls[i];
-
-            this.#url_patch_lookup.delete(url);
-
-            // and the memoized loader, which would otherwise hand this patch
-            // back for that url after the atlas has stopped holding it
-            this.#patch_loader.invalidate(url);
-        }
-
-        this.#patch_url_lookup.delete(patch);
-    }
-
-    /**
-     *
-     * @param {string} url
-     * @param {AtlasPatch} patch
-     */
-    #add_to_lookup(url, patch) {
-
-        this.#url_patch_lookup.set(url, patch);
-
-        let urls = this.#patch_url_lookup.get(patch);
-        if (urls === undefined) {
-            urls = [];
-            this.#patch_url_lookup.set(patch, urls);
-        }
-        urls.push(url);
-    }
-
-    /**
-     *
-     * @param {string} url
-     * @returns {Promise<Sampler2D>}
-     */
-    async #resolve_texture(url) {
-        const asset = await this.#assets.promise(url, GameAssetType.Image);
-        const source = asset.create();
-
-        return sampler2d_ensure_uint8_RGBA(source);
-    }
-
-    reset() {
-        this.#references.clear();
-        this.__caching_atlas.reset();
-        this.#url_patch_lookup.clear();
-
-        // The loader is memoized with no time-to-live and no weigher, so
-        // nothing evicts it: a url loaded before the reset would miss the
-        // lookup cleared above, fall through to the loader and be handed back
-        // the SAME AtlasPatch — one the reset atlas no longer holds, still
-        // flagged Attached and Packed, with a uv rectangle pointing at the
-        // pre-reset packing, and never repainted. Everything drawn with it
-        // samples whatever now occupies that region.
-        this.#patch_loader.clear();
-        this.#patch_url_lookup.clear();
-    }
-
-    /**
-     *
-     * @param {string} key
-     * @returns {Promise<Reference<AtlasPatch>>}
-     */
-    async acquire(url) {
-        const reference = new Reference();
-
-        let patch = this.#url_patch_lookup.get(url);
-
-        if (patch === undefined) {
-            // patch is not active, need to load it
-            patch = await this.#patch_loader.get(url);
-        }
-
-        reference.bind(patch);
-
-        return reference;
-    }
-
-    /**
-     *
-     * @param {string} key
-     */
-    release(key) {
-        throw  new Error('Method is deprecated, use "Reference.release" instead');
-    }
-}
+import { GameAssetType } from "../../../asset/GameAssetType.js";
+import { sampler2d_ensure_uint8_RGBA } from "../sampler/sampler2d_ensure_uint8_RGBA.js";
+import { CachingTextureAtlas } from "./CachingTextureAtlas.js";
+import { ReferencedTextureAtlas } from "./ReferencedTextureAtlas.js";
+import { SpriteAtlas } from "./SpriteAtlas.js";
+import { SpriteAtlasFill } from "./SpriteAtlasFill.js";
+
+/**
+ * @typedef {object} ManagedAtlasRecord
+ * @property {string} key
+ * @property {number} references
+ * @property {import("../sampler/Sampler2D.js").Sampler2D|null} sampler
+ * @property {import("./AtlasPatch.js").AtlasPatch|null} patch
+ * @property {boolean} loading
+ */
+
+/**
+ * Synchronous reference handle to an asynchronously loaded {@link AtlasPatch} in a
+ * {@link ManagedAtlas}.
+ *
+ * {@link getValue} is `null` while the texture is still in flight (or if loading failed or the
+ * handle was released) and returns the packed {@link AtlasPatch} once ready — or immediately on
+ * the same tick when the key hits a live or graveyard entry.
+ */
+export class ManagedAtlasReference {
+    /**
+     * @type {ManagedAtlas}
+     */
+    #owner;
+
+    /**
+     * @type {ManagedAtlasRecord}
+     */
+    #record;
+
+    /**
+     * @type {boolean}
+     */
+    #released = false;
+
+    /**
+     * @param {ManagedAtlas} owner
+     * @param {ManagedAtlasRecord} record
+     */
+    constructor(owner, record) {
+        this.#owner = owner;
+        this.#record = record;
+    }
+
+    /**
+     * @returns {import("./AtlasPatch.js").AtlasPatch|null}
+     */
+    getValue() {
+        if (this.#released) {
+            return null;
+        }
+
+        return this.#record.patch;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    get is_bound() {
+        return !this.#released && this.#record.patch !== null;
+    }
+
+    /**
+     * Release this caller's claim on the patch. Idempotent.
+     */
+    release() {
+        if (this.#released) {
+            return;
+        }
+
+        this.#released = true;
+        this.#owner._release_record(this.#record);
+    }
+}
+
+/**
+ * Reference-counted, graveyard-cached texture atlas manager.
+ *
+ * Coordinates asynchronous key loading, in-memory sampler retention while a patch sits in
+ * {@link CachingTextureAtlas}'s graveyard, synchronous graveyard resurrection on re-acquire, and
+ * eviction cleanup when the underlying {@link TextureAtlas} reaps a graveyard slot.
+ */
+export class ManagedAtlas {
+    /**
+     * @type {import("../../../asset/AssetManager.js").AssetManager|null}
+     */
+    #assets = null;
+
+    /**
+     * @type {(key: string) => Promise<import("../sampler/Sampler2D.js").Sampler2D>}
+     */
+    #load;
+
+    /**
+     * @type {Map<string, ManagedAtlasRecord>}
+     */
+    #records = new Map();
+
+    /**
+     * @type {Map<import("./AtlasPatch.js").AtlasPatch, ManagedAtlasRecord>}
+     */
+    #patch_records = new Map();
+
+    /**
+     * @type {ReferencedTextureAtlas}
+     */
+    #referenced_samplers;
+
+    /**
+     * @param {object} [params]
+     * @param {import("../../../asset/AssetManager.js").AssetManager|null} [params.assetManager]
+     * @param {import("./TextureAtlas.js").TextureAtlas} [params.atlas]
+     * @param {((key: string) => Promise<import("../sampler/Sampler2D.js").Sampler2D>)|null} [params.load]
+     */
+    constructor({
+        assetManager = null,
+        atlas = new SpriteAtlas(SpriteAtlasFill.EdgeExtend, 64),
+        load = null
+    } = {}) {
+        this.#assets = assetManager;
+
+        /**
+         * @type {import("./TextureAtlas.js").TextureAtlas}
+         */
+        this.atlas = atlas;
+
+        /**
+         * @type {CachingTextureAtlas}
+         */
+        this.__caching_atlas = new CachingTextureAtlas({ atlas });
+
+        this.#referenced_samplers = new ReferencedTextureAtlas(this.__caching_atlas);
+
+        this.#load = load ?? (url => this.#resolve_texture(url));
+
+        atlas.on.removed.add(this.#handle_patch_removed, this);
+    }
+
+    /**
+     * @returns {import("../sampler/Sampler2D.js").Sampler2D}
+     */
+    get sampler() {
+        return this.atlas.sampler;
+    }
+
+    /**
+     * @param {string} url
+     * @returns {Promise<import("../sampler/Sampler2D.js").Sampler2D>}
+     */
+    async #resolve_texture(url) {
+        const asset = await this.#assets.promise(url, GameAssetType.Image);
+        const source = asset.create();
+
+        return sampler2d_ensure_uint8_RGBA(source);
+    }
+
+    /**
+     * @param { import("./AtlasPatch.js").AtlasPatch } patch
+     */
+    #handle_patch_removed(patch) {
+        const record = this.#patch_records.get(patch);
+
+        if (record === undefined) {
+            return;
+        }
+
+        this.#patch_records.delete(patch);
+
+        if (record.patch === patch) {
+            record.patch = null;
+        }
+
+        if (record.references === 0 && this.#records.get(record.key) === record) {
+            this.#records.delete(record.key);
+        }
+    }
+
+    /**
+     * @param {ManagedAtlasRecord} record
+     */
+    #start_load(record) {
+        Promise.resolve()
+            .then(() => this.#load(record.key))
+            .then(sampler => {
+                if (this.#records.get(record.key) !== record) {
+                    return;
+                }
+
+                record.loading = false;
+                record.sampler = sampler;
+
+                if (record.references <= 0) {
+                    // Every caller released while the load was in flight; do not touch the atlas.
+                    this.#records.delete(record.key);
+
+                    return;
+                }
+
+                const patch = this.__caching_atlas.add(sampler);
+
+                record.patch = patch;
+                this.#patch_records.set(patch, record);
+            })
+            .catch(error => {
+                if (this.#records.get(record.key) !== record) {
+                    return;
+                }
+
+                record.loading = false;
+
+                if (record.references <= 0) {
+                    this.#records.delete(record.key);
+
+                    return;
+                }
+
+                console.warn(`ManagedAtlas: failed to load '${record.key}'`, error);
+            });
+    }
+
+    /**
+     * @param {ManagedAtlasRecord} record
+     */
+    _release_record(record) {
+        if (this.#records.get(record.key) !== record || record.references <= 0) {
+            return;
+        }
+
+        record.references--;
+
+        if (record.references === 0) {
+            if (record.patch !== null) {
+                // Move patch to the graveyard in CachingTextureAtlas rather than erasing it from the
+                // underlying TextureAtlas immediately.
+                this.__caching_atlas.remove(record.patch);
+            } else if (!record.loading) {
+                this.#records.delete(record.key);
+            }
+        }
+    }
+
+    /**
+     * Acquire a reference-counted handle for an asynchronous texture key.
+     *
+     * @param {string} key
+     * @returns {ManagedAtlasReference}
+     */
+    acquire(key) {
+        let record = this.#records.get(key);
+
+        if (record !== undefined) {
+            if (record.references === 0 && record.patch !== null) {
+                // Graveyard hit: resurrect synchronously without reloading or repainting.
+                record.patch = this.__caching_atlas.add(record.sampler);
+                this.#patch_records.set(record.patch, record);
+            }
+
+            record.references++;
+
+            return new ManagedAtlasReference(this, record);
+        }
+
+        record = {
+            key,
+            references: 1,
+            sampler: null,
+            patch: null,
+            loading: true
+        };
+
+        this.#records.set(key, record);
+        this.#start_load(record);
+
+        return new ManagedAtlasReference(this, record);
+    }
+
+    /**
+     * Acquire a reference-counted handle for an already-constructed {@link Sampler2D} (such as a
+     * shared 1x1 identity normal or ORM sampler).
+     *
+     * @param {import("../sampler/Sampler2D.js").Sampler2D} sampler
+     * @returns {import("../../../reference/v2/Reference.js").Reference<import("./AtlasPatch.js").AtlasPatch>}
+     */
+    acquire_sampler(sampler) {
+        return this.#referenced_samplers.acquire(sampler);
+    }
+
+    /**
+     * Pack and paint any pending changes in the underlying atlas, evicting graveyard patches first
+     * if needed.
+     */
+    update() {
+        this.__caching_atlas.update();
+    }
+
+    /**
+     * Drop all active and cached patches, invalidating any in-flight loads.
+     */
+    reset() {
+        for (const record of this.#records.values()) {
+            record.references = 0;
+            record.patch = null;
+            record.loading = false;
+        }
+
+        this.#records.clear();
+        this.#patch_records.clear();
+        this.#referenced_samplers.reset();
+    }
+
+    /**
+     * @param {string} _key
+     */
+    release(_key) {
+        throw new Error('Method is deprecated, use "Reference.release" instead');
+    }
+}

package/src/engine/graphics/texture/atlas/ReferencedTextureAtlas.d.ts

@@ -17,6 +17,15 @@ export class ReferencedTextureAtlas extends AbstractTextureAtlas {
      */
     private __ref_counts;
     __atlas: AbstractTextureAtlas;
+    /**
+     * @returns {AbstractTextureAtlas}
+     */
+    get atlas(): AbstractTextureAtlas;
+    /**
+     * @returns {Sampler2D}
+     */
+    get sampler(): Sampler2D;
+    reset(): void;
     /**
      *
      * @param {Reference} ref

package/src/engine/graphics/texture/atlas/ReferencedTextureAtlas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReferencedTextureAtlas.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/atlas/ReferencedTextureAtlas.js"],"names":[],"mappings":"AAGA;IAeI;;;OAGG;IACH,mBAFW,oBAAoB,EAM9B;IAtBD;;;;OAIG;IACH,kBAAsB;IAEtB;;;;OAIG;IACH,qBAAyB;IASrB,8BAAoB;IAOxB;;;;;OAKG;IACH,6BAYC;IAGD;;;;OAIG;IACH,6BAFa,qBAAqB,CAyBjC;CACJ;qCAlFoC,2BAA2B;0BACtC,oCAAoC"}
+{"version":3,"file":"ReferencedTextureAtlas.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/atlas/ReferencedTextureAtlas.js"],"names":[],"mappings":"AAGA;IAeI;;;OAGG;IACH,mBAFW,oBAAoB,EAM9B;IAtBD;;;;OAIG;IACH,kBAAsB;IAEtB;;;;OAIG;IACH,qBAAyB;IASrB,8BAAoB;IAGxB;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,yBAEC;IAMD,cAOC;IAED;;;;;OAKG;IACH,6BAgBC;IAGD;;;;OAIG;IACH,6BAFa,qBAAqB,CAyBjC;CACJ;qCA7GoC,2BAA2B;0BACtC,oCAAoC"}