@needle-tools/gltf-progressive 3.4.0-beta → 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;
@@ -531,6 +540,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 +552,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 +577,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 +592,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 +601,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 +619,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 +635,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 +644,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) {

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.4.0-beta";
+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.4.0-beta",
+  "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": {