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

package/lib/extension.js

@@ -1,7 +1,7 @@
 import { BufferGeometry, Mesh, Texture, TextureLoader } from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { addDracoAndKTX2Loaders } from "./loaders.js";
-import { getParam, PromiseQueue, resolveUrl } from "./utils.internal.js";
+import { determineTextureMemoryInBytes, getParam, PromiseQueue, resolveUrl } from "./utils.internal.js";
 import { getRaycastMesh, registerRaycastMesh } from "./utils.js";
 // All of this has to be removed
 // import { getRaycastMesh, setRaycastMesh } from "../../engine_physics.js";
@@ -11,6 +11,7 @@ import { debug } from "./lods.debug.js";
 import { getWorker } from "./worker/loader.mainthread.js";
 const useWorker = getParam("gltf-progressive-worker");
 const reduceMipmaps = getParam("gltf-progressive-reduce-mipmaps");
+const debugGC = getParam("gltf-progressive-gc");
 const $progressiveTextureExtension = Symbol("needle-progressive-texture");
 export const EXTENSION_NAME = "NEEDLE_progressive";
 // #region EXT
@@ -334,29 +335,37 @@ export class NEEDLE_progressive {
                             if (assignedLOD && assignedLOD?.level < level) {
                                 if (debug === "verbose")
                                     console.warn("Assigned texture level is already higher: ", assignedLOD.level, level, material, assigned, tex);
+                                // Dispose the newly loaded texture since we're not using it
+                                // (the assigned texture is higher quality, so we reject the new one)
+                                // Note: We dispose directly here (not via untrackTextureUsage) because this texture
+                                // was never tracked/used - it was rejected immediately upon loading
+                                if (tex && tex !== assigned) {
+                                    if (debug || debugGC) {
+                                        console.log(`[gltf-progressive] Disposing rejected lower-quality texture LOD ${level} (assigned is ${assignedLOD.level})`, tex.uuid);
+                                    }
+                                    tex.dispose();
+                                }
                                 return null;
                             }
                             // assigned.dispose();
                         }
-                        // Since we're switching LOD level for the texture based on distance we can avoid uploading all the mipmaps
-                        if (reduceMipmaps && tex.mipmaps) {
-                            const prevCount = tex.mipmaps.length;
-                            tex.mipmaps.length = Math.min(tex.mipmaps.length, 3);
-                            if (prevCount !== tex.mipmaps.length) {
-                                if (debug)
-                                    console.debug(`Reduced mipmap count from ${prevCount} to ${tex.mipmaps.length} for ${tex.uuid}: ${tex.image?.width}x${tex.image?.height}.`);
+                        // Track reference count for new texture
+                        this.trackTextureUsage(tex);
+                        // Untrack the old texture (may dispose if ref count hits 0)
+                        // This prevents accumulation of GPU VRAM while waiting for garbage collection
+                        if (assigned && assigned !== tex) {
+                            const wasDisposed = this.untrackTextureUsage(assigned);
+                            if (wasDisposed && (debug || debugGC)) {
+                                const assignedLOD = this.getAssignedLODInformation(assigned);
+                                console.log(`[gltf-progressive] Disposed old texture LOD ${assignedLOD?.level ?? '?'} → ${level} for ${material.name || material.type}.${slot}`, assigned.uuid);
                             }
                         }
                         material[slot] = tex;
                     }
-                    // check if the old texture is still used by other objects
-                    // if not we dispose it...
-                    // this could also be handled elsewhere and not be done immediately
-                    // const users = getResourceUserCount(current);
-                    // if (!users) {
-                    //     if (debug) console.log("Progressive: Dispose texture", current.name, current.source.data, current.uuid);
-                    //     current?.dispose();
-                    // }
+                    // Note: We use reference counting above to track texture usage across multiple materials.
+                    // When the reference count hits zero, GPU memory (VRAM) is freed immediately via gl.deleteTexture(),
+                    // not waiting for JavaScript garbage collection which may take seconds/minutes.
+                    // This handles cases where the same texture is shared across multiple materials/objects.
                 }
                 // this.onProgressiveLoadEnd(info);
                 return tex;
@@ -493,7 +502,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 +520,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 +536,180 @@ 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.
+     * Also clears reference counts for disposed textures.
+     * @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) {
+                        const tex = lowres;
+                        this.textureRefCounts.delete(tex.uuid); // Clear ref count
+                        tex.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) {
+                        const tex = entry;
+                        this.textureRefCounts.delete(tex.uuid); // Clear ref count
+                        tex.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();
+            // Clear all texture reference counts when disposing everything
+            this.textureRefCounts.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();
+            if (resource) {
+                // Clear ref count for textures
+                if (resource.isTexture) {
+                    this.textureRefCounts.delete(resource.uuid);
+                }
+                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 {
+                        // Clear ref count for textures
+                        if (resource.isTexture) {
+                            this.textureRefCounts.delete(resource.uuid);
+                        }
+                        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();
+    /** Reference counting for textures to track usage across multiple materials/objects */
+    static textureRefCounts = 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 || debugGC)
+            console.debug(`[gltf-progressive] Memory: 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 || debugGC)
+                    console.log(`[gltf-progressive] ↪ Cache entry deleted (GC)`);
+            }
+        }
+    });
+    /**
+     * Track texture usage by incrementing reference count
+     */
+    static trackTextureUsage(texture) {
+        const uuid = texture.uuid;
+        const count = this.textureRefCounts.get(uuid) || 0;
+        this.textureRefCounts.set(uuid, count + 1);
+        if (debug === "verbose") {
+            console.log(`[gltf-progressive] Track texture ${uuid}, refCount: ${count} → ${count + 1}`);
+        }
+    }
+    /**
+     * Untrack texture usage by decrementing reference count.
+     * Automatically disposes the texture when reference count reaches zero.
+     * @returns true if the texture was disposed, false otherwise
+     */
+    static untrackTextureUsage(texture) {
+        const uuid = texture.uuid;
+        const count = this.textureRefCounts.get(uuid);
+        if (!count) {
+            // Texture wasn't tracked, dispose immediately (safe fallback)
+            if (debug === "verbose" || debugGC) {
+                logDebugInfo(`[gltf-progressive] Memory: Untrack untracked texture (dispose immediately)`, 0);
+            }
+            texture.dispose();
+            return true;
+        }
+        const newCount = count - 1;
+        if (newCount <= 0) {
+            this.textureRefCounts.delete(uuid);
+            if (debug || debugGC) {
+                logDebugInfo(`[gltf-progressive] Memory: Dispose texture`, newCount);
+            }
+            texture.dispose();
+            return true;
+        }
+        else {
+            this.textureRefCounts.set(uuid, newCount);
+            if (debug === "verbose") {
+                logDebugInfo(`[gltf-progressive] Memory: Untrack texture`, newCount);
+            }
+            return false;
+        }
+        function logDebugInfo(prefix, newCount) {
+            let width = texture.image?.width || texture.source?.data?.width || 0;
+            let height = texture.image?.height || texture.source?.data?.height || 0;
+            const textureSize = width && height ? `${width}x${height}` : "N/A";
+            let memorySize = "N/A";
+            if (width && height) {
+                memorySize = `~${(determineTextureMemoryInBytes(texture) / (1024 * 1024)).toFixed(2)} MB`;
+            }
+            console.log(`${prefix} — ${texture.name} ${textureSize} (${memorySize}), refCount: ${count} → ${newCount}\n${uuid}`);
+        }
+    }
     static workers = [];
     static _workersIndex = 0;
     static async getOrLoadLOD(current, level) {
@@ -567,8 +747,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 +782,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 +995,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/utils.internal.d.ts

@@ -1,3 +1,4 @@
+import { Texture } from "three";
 export declare function isDebugMode(): string | boolean;
 export declare function getParam(name: string): boolean | string;
 export declare function resolveUrl(source: string | undefined, uri: string): string;
@@ -33,3 +34,8 @@ export declare class PromiseQueue<T = any> {
     private add;
     private internalUpdate;
 }
+export declare function determineTextureMemoryInBytes(texture: Texture): number;
+/**
+ * Detect the GPU memory of the current device. This is a very rough estimate based on the renderer information, and may not be accurate. It returns the estimated memory in MB, or `undefined` if it cannot be detected.
+ */
+export declare function detectGPUMemory(): number | undefined;

package/lib/utils.internal.js

@@ -115,3 +115,95 @@ export class PromiseQueue {
         }
     }
 }
+// #region Texture Memory
+export function determineTextureMemoryInBytes(texture) {
+    const width = texture.image?.width ?? 0;
+    const height = texture.image?.height ?? 0;
+    const depth = texture.image?.depth ?? 1;
+    const mipLevels = Math.floor(Math.log2(Math.max(width, height, depth))) + 1;
+    const bytesPerPixel = getBytesPerPixel(texture);
+    const totalBytes = (width * height * depth * bytesPerPixel * (1 - Math.pow(0.25, mipLevels))) / (1 - 0.25);
+    return totalBytes;
+}
+function getBytesPerPixel(texture) {
+    // Determine channel count from format
+    let channels = 4; // Default RGBA
+    const format = texture.format;
+    if (format === 1024)
+        channels = 1; // RedFormat
+    else if (format === 1025)
+        channels = 1; // RedIntegerFormat
+    else if (format === 1026)
+        channels = 2; // RGFormat
+    else if (format === 1027)
+        channels = 2; // RGIntegerFormat
+    else if (format === 1022)
+        channels = 3; // RGBFormat
+    else if (format === 1029)
+        channels = 3; // RGBIntegerFormat
+    else if (format === 1023)
+        channels = 4; // RGBAFormat
+    else if (format === 1033)
+        channels = 4; // RGBAIntegerFormat
+    // Determine bytes per channel from type
+    let bytesPerChannel = 1; // UnsignedByteType default
+    const type = texture.type;
+    if (type === 1009)
+        bytesPerChannel = 1; // UnsignedByteType
+    else if (type === 1010)
+        bytesPerChannel = 1; // ByteType
+    else if (type === 1011)
+        bytesPerChannel = 2; // ShortType
+    else if (type === 1012)
+        bytesPerChannel = 2; // UnsignedShortType
+    else if (type === 1013)
+        bytesPerChannel = 4; // IntType
+    else if (type === 1014)
+        bytesPerChannel = 4; // UnsignedIntType
+    else if (type === 1015)
+        bytesPerChannel = 4; // FloatType
+    else if (type === 1016)
+        bytesPerChannel = 2; // HalfFloatType
+    const bytesPerPixel = channels * bytesPerChannel;
+    return bytesPerPixel;
+}
+// #region GPU
+let rendererInfo;
+/**
+ * Detect the GPU memory of the current device. This is a very rough estimate based on the renderer information, and may not be accurate. It returns the estimated memory in MB, or `undefined` if it cannot be detected.
+ */
+export function detectGPUMemory() {
+    if (rendererInfo !== undefined) {
+        return rendererInfo?.estimatedMemory;
+    }
+    const canvas = document.createElement('canvas');
+    const powerPreference = "high-performance";
+    const gl = canvas.getContext('webgl', { powerPreference }) || canvas.getContext('experimental-webgl', { powerPreference });
+    if (!gl) {
+        return undefined;
+    }
+    if ("getExtension" in gl) {
+        const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
+        if (debugInfo) {
+            const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);
+            const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
+            // Estimate memory based on renderer information (this is a very rough estimate)
+            let estimatedMemory = 512;
+            if (/NVIDIA/i.test(renderer)) {
+                estimatedMemory = 2048;
+            }
+            else if (/AMD/i.test(renderer)) {
+                estimatedMemory = 1024;
+            }
+            else if (/Intel/i.test(renderer)) {
+                estimatedMemory = 512;
+            }
+            rendererInfo = { vendor, renderer, estimatedMemory };
+            return estimatedMemory;
+        }
+    }
+    else {
+        rendererInfo = null;
+    }
+    return undefined;
+}

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.1";
 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.1",
   "description": "three.js support for loading glTF or GLB files that contain progressive loading data",
   "homepage": "https://needle.tools",
   "author": {