@needle-tools/gltf-progressive 3.4.0-beta → 3.4.0-beta.2

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
@@ -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
+     */
+    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)
@@ -565,7 +587,9 @@ export class NEEDLE_progressive {
                 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)
@@ -578,6 +602,8 @@ export class NEEDLE_progressive {
                 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. */
@@ -585,7 +611,13 @@ 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.
@@ -597,6 +629,10 @@ export class NEEDLE_progressive {
                             geo.dispose();
                     }
                     else {
+                        // Clear ref count for textures
+                        if (resource.isTexture) {
+                            this.textureRefCounts.delete(resource.uuid);
+                        }
                         resource.dispose();
                     }
                 }
@@ -609,6 +645,8 @@ export class NEEDLE_progressive {
     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.
@@ -616,18 +654,72 @@ export class NEEDLE_progressive {
      */
     static _resourceRegistry = new FinalizationRegistry((cacheKey) => {
         const entry = NEEDLE_progressive.cache.get(cacheKey);
-        if (debug)
-            console.debug(`[gltf-progressive] Resource GC'd\n${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)
-                    console.log(`[gltf-progressive] Cache entry auto-cleaned (GC'd): ${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) {
@@ -964,8 +1056,7 @@ export class NEEDLE_progressive {
         }
         return null;
     }
-    static maxConcurrent = 50;
-    static queue = new PromiseQueue(NEEDLE_progressive.maxConcurrent, { debug: debug != false });
+    static queue = new PromiseQueue(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-beta",
+  "version": "3.4.0-beta.2",
   "description": "three.js support for loading glTF or GLB files that contain progressive loading data",
   "homepage": "https://needle.tools",
   "author": {