@needle-tools/gltf-progressive 3.3.5 → 3.4.0-beta

package/lib/extension.js

@@ -493,7 +493,7 @@ export class NEEDLE_progressive {
         const key = ext.guid;
         NEEDLE_progressive.assignLODInformation(url, tex, key, level, index);
         NEEDLE_progressive.lodInfos.set(key, ext);
-        NEEDLE_progressive.lowresCache.set(key, tex);
+        NEEDLE_progressive.lowresCache.set(key, new WeakRef(tex));
     };
     /**
      * Register a mesh with LOD information
@@ -511,12 +511,15 @@ export class NEEDLE_progressive {
             console.log("> Progressive: register mesh " + mesh.name, { index, uuid: mesh.uuid }, ext, mesh);
         NEEDLE_progressive.assignLODInformation(url, geometry, key, level, index);
         NEEDLE_progressive.lodInfos.set(key, ext);
-        let existing = NEEDLE_progressive.lowresCache.get(key);
-        if (existing)
+        const existingRef = NEEDLE_progressive.lowresCache.get(key);
+        let existing = existingRef?.deref();
+        if (existing) {
             existing.push(mesh.geometry);
-        else
+        }
+        else {
             existing = [mesh.geometry];
-        NEEDLE_progressive.lowresCache.set(key, existing);
+        }
+        NEEDLE_progressive.lowresCache.set(key, new WeakRef(existing));
         if (level > 0 && !getRaycastMesh(mesh)) {
             registerRaycastMesh(mesh, geometry);
         }
@@ -524,12 +527,107 @@ export class NEEDLE_progressive {
             plugin.onRegisteredNewMesh?.(mesh, ext);
         }
     };
+    /**
+     * Dispose cached resources to free memory.
+     * Call this when a model is removed from the scene to allow garbage collection of its LOD resources.
+     * Calls three.js `.dispose()` on cached Textures and BufferGeometries to free GPU memory.
+     * @param guid Optional GUID to dispose resources for a specific model. If omitted, all cached resources are cleared.
+     */
+    static dispose(guid) {
+        if (guid) {
+            this.lodInfos.delete(guid);
+            // Dispose lowres cache entries (original proxy resources)
+            const lowresRef = this.lowresCache.get(guid);
+            if (lowresRef) {
+                const lowres = lowresRef.deref();
+                if (lowres) {
+                    if (lowres.isTexture) {
+                        lowres.dispose();
+                    }
+                    else if (Array.isArray(lowres)) {
+                        for (const geo of lowres)
+                            geo.dispose();
+                    }
+                }
+                this.lowresCache.delete(guid);
+            }
+            // Dispose previously loaded LOD entries
+            for (const [key, entry] of this.cache) {
+                if (key.includes(guid)) {
+                    this._disposeCacheEntry(entry);
+                    this.cache.delete(key);
+                }
+            }
+        }
+        else {
+            this.lodInfos.clear();
+            for (const [, entryRef] of this.lowresCache) {
+                const entry = entryRef.deref();
+                if (entry) {
+                    if (entry.isTexture) {
+                        entry.dispose();
+                    }
+                    else if (Array.isArray(entry)) {
+                        for (const geo of entry)
+                            geo.dispose();
+                    }
+                }
+            }
+            this.lowresCache.clear();
+            for (const [, entry] of this.cache) {
+                this._disposeCacheEntry(entry);
+            }
+            this.cache.clear();
+        }
+    }
+    /** Dispose a single cache entry's three.js resource(s) to free GPU memory. */
+    static _disposeCacheEntry(entry) {
+        if (entry instanceof WeakRef) {
+            // Single resource — deref and dispose if still alive
+            const resource = entry.deref();
+            resource?.dispose();
+        }
+        else {
+            // Promise — may be in-flight or already resolved.
+            // Attach disposal to run after resolution.
+            entry.then(resource => {
+                if (resource) {
+                    if (Array.isArray(resource)) {
+                        for (const geo of resource)
+                            geo.dispose();
+                    }
+                    else {
+                        resource.dispose();
+                    }
+                }
+            }).catch(() => { });
+        }
+    }
     /** A map of key = asset uuid and value = LOD information */
     static lodInfos = new Map();
-    /** cache of already loaded mesh lods */
-    static previouslyLoaded = new Map();
-    /** this contains the geometry/textures that were originally loaded */
+    /** cache of already loaded mesh lods. Uses WeakRef for single resources to allow garbage collection when unused. */
+    static cache = new Map();
+    /** this contains the geometry/textures that were originally loaded. Uses WeakRef to allow garbage collection when unused. */
     static lowresCache = new Map();
+    /**
+     * FinalizationRegistry to automatically clean up `previouslyLoaded` cache entries
+     * when their associated three.js resources are garbage collected by the browser.
+     * The held value is the cache key string used in `previouslyLoaded`.
+     */
+    static _resourceRegistry = new FinalizationRegistry((cacheKey) => {
+        const entry = NEEDLE_progressive.cache.get(cacheKey);
+        if (debug)
+            console.debug(`[gltf-progressive] Resource GC'd\n${cacheKey}`);
+        // Only delete if the entry is still a WeakRef and the resource is gone
+        if (entry instanceof WeakRef) {
+            const derefed = entry.deref();
+            if (!derefed) {
+                NEEDLE_progressive.cache.delete(cacheKey);
+                if (debug)
+                    console.log(`[gltf-progressive] Cache entry auto-cleaned (GC'd): ${cacheKey}`);
+            }
+        }
+    });
     static workers = [];
     static _workersIndex = 0;
     static async getOrLoadLOD(current, level) {
@@ -567,8 +665,18 @@ export class NEEDLE_progressive {
                     useLowRes = true;
                 }
                 if (useLowRes) {
-                    const lowres = this.lowresCache.get(LODKEY);
-                    return lowres;
+                    const lowresRef = this.lowresCache.get(LODKEY);
+                    if (lowresRef) {
+                        const lowres = lowresRef.deref();
+                        if (lowres)
+                            return lowres;
+                        // Resource was GC'd, remove stale entry
+                        this.lowresCache.delete(LODKEY);
+                        if (debug)
+                            console.log(`[gltf-progressive] Lowres cache entry was GC'd: ${LODKEY}`);
+                    }
+                    // Fallback to current if lowres was GC'd
+                    return null;
                 }
             }
             /** the unresolved LOD url */
@@ -592,42 +700,73 @@ export class NEEDLE_progressive {
                 // check if the requested file has already been loaded
                 const KEY = lod_url + "_" + lodInfo.guid;
                 const slot = await this.queue.slot(lod_url);
-                // check if the requested file is currently being loaded
-                const existing = this.previouslyLoaded.get(KEY);
+                // check if the requested file is currently being loaded or was previously loaded
+                const existing = this.cache.get(KEY);
                 if (existing !== undefined) {
                     if (debugverbose)
                         console.log(`LOD ${level} was already loading/loaded: ${KEY}`);
-                    let res = await existing.catch(err => {
-                        console.error(`Error loading LOD ${level} from ${lod_url}\n`, err);
-                        return null;
-                    });
-                    let resouceIsDisposed = false;
-                    if (res == null) {
-                        // if the resource is null the last loading result didnt succeed (maybe because the url doesnt exist)
-                        // in which case we don't attempt to load it again
-                    }
-                    else if (res instanceof Texture && current instanceof Texture) {
-                        // check if the texture has been disposed or not
-                        if (res.image?.data || res.source?.data) {
-                            res = this.copySettings(current, res);
-                        }
-                        // if it has been disposed we need to load it again
-                        else {
-                            resouceIsDisposed = true;
-                            this.previouslyLoaded.delete(KEY);
+                    if (existing instanceof WeakRef) {
+                        // Previously resolved resource — check if still alive in memory
+                        const derefed = existing.deref();
+                        if (derefed) {
+                            let res = derefed;
+                            let resourceIsDisposed = false;
+                            if (res instanceof Texture && current instanceof Texture) {
+                                if (res.image?.data || res.source?.data) {
+                                    res = this.copySettings(current, res);
+                                }
+                                else {
+                                    resourceIsDisposed = true;
+                                }
+                            }
+                            else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
+                                if (!res.attributes.position?.array) {
+                                    resourceIsDisposed = true;
+                                }
+                            }
+                            if (!resourceIsDisposed) {
+                                return res;
+                            }
                         }
+                        // Resource was garbage collected or disposed — remove stale entry and re-load
+                        this.cache.delete(KEY);
+                        if (debug)
+                            console.log(`[gltf-progressive] Re-loading GC'd/disposed resource: ${KEY}`);
                     }
-                    else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
-                        if (res.attributes.position?.array) {
-                            // the geometry is OK
+                    else {
+                        // Promise — loading in progress or previously completed
+                        let res = await existing.catch(err => {
+                            console.error(`Error loading LOD ${level} from ${lod_url}\n`, err);
+                            return null;
+                        });
+                        let resouceIsDisposed = false;
+                        if (res == null) {
+                            // if the resource is null the last loading result didnt succeed (maybe because the url doesnt exist)
+                            // in which case we don't attempt to load it again
                         }
-                        else {
-                            resouceIsDisposed = true;
-                            this.previouslyLoaded.delete(KEY);
+                        else if (res instanceof Texture && current instanceof Texture) {
+                            // check if the texture has been disposed or not
+                            if (res.image?.data || res.source?.data) {
+                                res = this.copySettings(current, res);
+                            }
+                            // if it has been disposed we need to load it again
+                            else {
+                                resouceIsDisposed = true;
+                                this.cache.delete(KEY);
+                            }
+                        }
+                        else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
+                            if (res.attributes.position?.array) {
+                                // the geometry is OK
+                            }
+                            else {
+                                resouceIsDisposed = true;
+                                this.cache.delete(KEY);
+                            }
+                        }
+                        if (!resouceIsDisposed) {
+                            return res;
                         }
-                    }
-                    if (!resouceIsDisposed) {
-                        return res;
                     }
                 }
                 // #region loading
@@ -774,9 +913,33 @@ export class NEEDLE_progressive {
                     // we could not find a texture or mesh with the given guid
                     return resolve(null);
                 });
-                this.previouslyLoaded.set(KEY, request);
+                this.cache.set(KEY, request);
                 slot.use(request);
                 const res = await request;
+                // Optimize cache entry: replace loading promise with lightweight reference.
+                // This releases closure variables captured during the loading function.
+                if (res != null) {
+                    if (res instanceof Texture) {
+                        // For Texture resources, use WeakRef to allow garbage collection.
+                        // The FinalizationRegistry will auto-clean this entry when the resource is GC'd.
+                        this.cache.set(KEY, new WeakRef(res));
+                        NEEDLE_progressive._resourceRegistry.register(res, KEY);
+                    }
+                    else if (Array.isArray(res)) {
+                        // For BufferGeometry[] (multi-primitive meshes), use a resolved promise.
+                        // This keeps geometries in memory as they should not be GC'd (mesh LODs stay cached).
+                        this.cache.set(KEY, Promise.resolve(res));
+                    }
+                    else {
+                        // For single BufferGeometry, keep in memory (don't use WeakRef)
+                        this.cache.set(KEY, Promise.resolve(res));
+                    }
+                }
+                else {
+                    // Failed load — replace with clean resolved promise to release loading closure.
+                    // Keeping the entry prevents retrying (existing behavior).
+                    this.cache.set(KEY, Promise.resolve(null));
+                }
                 return res;
             }
             else {

package/lib/version.js

@@ -1,4 +1,4 @@
 // replaced at build time
-export const version = "3.3.5";
+export const version = "3.4.0-beta";
 globalThis["GLTF_PROGRESSIVE_VERSION"] = version;
 console.debug(`[gltf-progressive] version ${version || "-"}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/gltf-progressive",
-  "version": "3.3.5",
+  "version": "3.4.0-beta",
   "description": "three.js support for loading glTF or GLB files that contain progressive loading data",
   "homepage": "https://needle.tools",
   "author": {