@needle-tools/gltf-progressive 3.4.0-next.a9f46ea → 3.4.0-next.ed30751

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, isMobileDevice, 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
@@ -309,6 +310,16 @@ export class NEEDLE_progressive {
         }
         return Promise.resolve(null);
     }
+    /**
+     * Set the maximum number of concurrent loading tasks for LOD resources. This limits how many LOD resources (meshes or textures) can be loaded at the same time to prevent overloading the network or GPU. If the limit is reached, additional loading requests will be queued and processed as previous ones finish.
+     * @default 50 on desktop, 20 on mobile devices
+     */
+    static set maxConcurrentLoadingTasks(value) {
+        NEEDLE_progressive.queue.maxConcurrent = value;
+    }
+    static get maxConcurrentLoadingTasks() {
+        return NEEDLE_progressive.queue.maxConcurrent;
+    }
     // #region INTERNAL
     static assignTextureLODForSlot(current, level, material, slot) {
         if (current?.isTexture !== true) {
@@ -334,29 +345,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;
@@ -531,6 +550,7 @@ export class NEEDLE_progressive {
      * 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) {
@@ -542,7 +562,9 @@ export class NEEDLE_progressive {
                 const lowres = lowresRef.deref();
                 if (lowres) {
                     if (lowres.isTexture) {
-                        lowres.dispose();
+                        const tex = lowres;
+                        this.textureRefCounts.delete(tex.uuid); // Clear ref count
+                        tex.dispose();
                     }
                     else if (Array.isArray(lowres)) {
                         for (const geo of lowres)
@@ -552,20 +574,24 @@ export class NEEDLE_progressive {
                 this.lowresCache.delete(guid);
             }
             // Dispose previously loaded LOD entries
-            for (const [key, entry] of this.previouslyLoaded) {
+            for (const [key, entry] of this.cache) {
                 if (key.includes(guid)) {
                     this._disposeCacheEntry(entry);
-                    this.previouslyLoaded.delete(key);
+                    this.cache.delete(key);
                 }
             }
         }
         else {
+            // Invalidate requests waiting for a queue slot as well as active loads.
+            this.cacheGeneration++;
             this.lodInfos.clear();
             for (const [, entryRef] of this.lowresCache) {
                 const entry = entryRef.deref();
                 if (entry) {
                     if (entry.isTexture) {
-                        entry.dispose();
+                        const tex = entry;
+                        this.textureRefCounts.delete(tex.uuid); // Clear ref count
+                        tex.dispose();
                     }
                     else if (Array.isArray(entry)) {
                         for (const geo of entry)
@@ -574,10 +600,12 @@ export class NEEDLE_progressive {
                 }
             }
             this.lowresCache.clear();
-            for (const [, entry] of this.previouslyLoaded) {
+            for (const [, entry] of this.cache) {
                 this._disposeCacheEntry(entry);
             }
-            this.previouslyLoaded.clear();
+            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. */
@@ -585,11 +613,18 @@ export class NEEDLE_progressive {
         if (entry instanceof WeakRef) {
             // Single resource — deref and dispose if still alive
             const resource = entry.deref();
-            resource?.dispose();
+            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.
+            this.disposedRequests.add(entry);
             entry.then(resource => {
                 if (resource) {
                     if (Array.isArray(resource)) {
@@ -597,6 +632,10 @@ export class NEEDLE_progressive {
                             geo.dispose();
                     }
                     else {
+                        // Clear ref count for textures
+                        if (resource.isTexture) {
+                            this.textureRefCounts.delete(resource.uuid);
+                        }
                         resource.dispose();
                     }
                 }
@@ -606,30 +645,90 @@ export class NEEDLE_progressive {
     /** A map of key = asset uuid and value = LOD information */
     static lodInfos = new Map();
     /** cache of already loaded mesh lods. Uses WeakRef for single resources to allow garbage collection when unused. */
-    static previouslyLoaded = new Map();
+    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.previouslyLoaded.get(cacheKey);
-        console.debug(`[gltf-progressive] FinalizationRegistry cleanup: Resource GC'd for ${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.previouslyLoaded.delete(cacheKey);
-                if (debug)
-                    console.log(`[gltf-progressive] Cache entry auto-cleaned (GC'd): ${cacheKey}`);
+                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 cacheGeneration = 0;
+    static disposedRequests = new WeakSet();
     static _workersIndex = 0;
     static async getOrLoadLOD(current, level) {
+        const generation = this.cacheGeneration;
         const debugverbose = debug == "verbose";
         /** this key is used to lookup the LOD information */
         const LOD = this.getAssignedLODInformation(current);
@@ -699,8 +798,10 @@ 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);
+                if (generation !== this.cacheGeneration)
+                    return null;
                 // check if the requested file is currently being loaded or was previously loaded
-                const existing = this.previouslyLoaded.get(KEY);
+                const existing = this.cache.get(KEY);
                 if (existing !== undefined) {
                     if (debugverbose)
                         console.log(`LOD ${level} was already loading/loaded: ${KEY}`);
@@ -728,7 +829,7 @@ export class NEEDLE_progressive {
                             }
                         }
                         // Resource was garbage collected or disposed — remove stale entry and re-load
-                        this.previouslyLoaded.delete(KEY);
+                        this.cache.delete(KEY);
                         if (debug)
                             console.log(`[gltf-progressive] Re-loading GC'd/disposed resource: ${KEY}`);
                     }
@@ -738,6 +839,8 @@ export class NEEDLE_progressive {
                             console.error(`Error loading LOD ${level} from ${lod_url}\n`, err);
                             return null;
                         });
+                        if (generation !== this.cacheGeneration || this.disposedRequests.has(existing))
+                            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)
@@ -751,7 +854,7 @@ export class NEEDLE_progressive {
                             // if it has been disposed we need to load it again
                             else {
                                 resouceIsDisposed = true;
-                                this.previouslyLoaded.delete(KEY);
+                                this.cache.delete(KEY);
                             }
                         }
                         else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
@@ -760,7 +863,7 @@ export class NEEDLE_progressive {
                             }
                             else {
                                 resouceIsDisposed = true;
-                                this.previouslyLoaded.delete(KEY);
+                                this.cache.delete(KEY);
                             }
                         }
                         if (!resouceIsDisposed) {
@@ -912,30 +1015,36 @@ 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;
+                // dispose() cleans up removed pending entries when they resolve. Do not
+                // return those resources or overwrite a newer request for this key.
+                if (generation !== this.cacheGeneration || this.cache.get(KEY) !== request)
+                    return null;
                 // Optimize cache entry: replace loading promise with lightweight reference.
                 // This releases closure variables captured during the loading function.
                 if (res != null) {
-                    if (Array.isArray(res)) {
+                    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.
-                        // WeakRef can't be used here because callers only extract individual elements
-                        // from the array, so the array object itself would be GC'd immediately.
-                        this.previouslyLoaded.set(KEY, Promise.resolve(res));
+                        // 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 resources (Texture or BufferGeometry), use WeakRef to allow
-                        // garbage collection when the resource is no longer referenced by the scene.
-                        // The FinalizationRegistry will auto-clean this entry when the resource is GC'd.
-                        this.previouslyLoaded.set(KEY, new WeakRef(res));
-                        NEEDLE_progressive._resourceRegistry.register(res, KEY);
+                        // 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.previouslyLoaded.set(KEY, Promise.resolve(null));
+                    this.cache.set(KEY, Promise.resolve(null));
                 }
                 return res;
             }
@@ -945,6 +1054,10 @@ export class NEEDLE_progressive {
                         console.log("Load texture from uri: " + lod_url);
                     const loader = new TextureLoader();
                     const tex = await loader.loadAsync(lod_url);
+                    if (generation !== this.cacheGeneration) {
+                        tex?.dispose();
+                        return null;
+                    }
                     if (tex) {
                         tex.guid = lodInfo.guid;
                         tex.flipY = false;
@@ -961,8 +1074,7 @@ export class NEEDLE_progressive {
         }
         return null;
     }
-    static maxConcurrent = 50;
-    static queue = new PromiseQueue(NEEDLE_progressive.maxConcurrent, { debug: debug != false });
+    static queue = new PromiseQueue(isMobileDevice() ? 20 : 50, { debug: debug != false });
     static assignLODInformation(url, res, key, level, index) {
         if (!res)
             return;

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;
@@ -18,11 +19,11 @@ export type SlotReturnValue<T = any> = {
  * Use the `slot` method to request a slot for a promise with a specific key. The returned promise resolves to an object with a `use` method that can be called to add the promise to the queue.
  */
 export declare class PromiseQueue<T = any> {
-    readonly maxConcurrent: number;
+    maxConcurrent: number;
     private readonly _running;
     private readonly _queue;
     debug: boolean;
-    constructor(maxConcurrent?: number, opts?: {
+    constructor(maxConcurrent: number, opts?: {
         debug?: boolean;
     });
     private tick;
@@ -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

@@ -71,7 +71,7 @@ export class PromiseQueue {
     _running = new Map();
     _queue = [];
     debug = false;
-    constructor(maxConcurrent = 100, opts = {}) {
+    constructor(maxConcurrent, opts = {}) {
         this.maxConcurrent = maxConcurrent;
         this.debug = opts.debug ?? false;
         window.requestAnimationFrame(this.tick);
@@ -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.4.0-beta";
+export const version = "3.4.0-beta.2";
 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.4.0-next.a9f46ea",
+  "version": "3.4.0-next.ed30751",
   "description": "three.js support for loading glTF or GLB files that contain progressive loading data",
   "homepage": "https://needle.tools",
   "author": {