@needle-tools/gltf-progressive 3.4.0-rc → 4.0.0-alpha.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, getSourceData, getTextureDimensions, hasPixelData, 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;
@@ -482,8 +501,7 @@ export class NEEDLE_progressive {
             return;
         }
         if (debug) {
-            const width = tex.image?.width || tex.source?.data?.width || 0;
-            const height = tex.image?.height || tex.source?.data?.height || 0;
+            const { width, height } = getTextureDimensions(tex);
             console.log(`> gltf-progressive: register texture[${index}] "${tex.name || tex.uuid}", Current: ${width}x${height}, Max: ${ext.lods[0]?.width}x${ext.lods[0]?.height}, uuid: ${tex.uuid}`, ext, tex);
         }
         // Put the extension info into the source (seems like tiled textures are cloned and the userdata etc is not properly copied BUT the source of course is not cloned)
@@ -531,6 +549,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 +561,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,10 +573,10 @@ 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);
                 }
             }
         }
@@ -565,7 +586,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)
@@ -574,10 +597,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,7 +610,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 +628,10 @@ export class NEEDLE_progressive {
                             geo.dispose();
                     }
                     else {
+                        // Clear ref count for textures
+                        if (resource.isTexture) {
+                            this.textureRefCounts.delete(resource.uuid);
+                        }
                         resource.dispose();
                     }
                 }
@@ -606,27 +641,83 @@ 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, height } = getTextureDimensions(texture);
+            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) {
@@ -700,7 +791,7 @@ export class NEEDLE_progressive {
                 const KEY = lod_url + "_" + lodInfo.guid;
                 const slot = await this.queue.slot(lod_url);
                 // 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}`);
@@ -711,7 +802,7 @@ export class NEEDLE_progressive {
                             let res = derefed;
                             let resourceIsDisposed = false;
                             if (res instanceof Texture && current instanceof Texture) {
-                                if (res.image?.data || res.source?.data) {
+                                if (hasPixelData(res.image) || getSourceData(res)) {
                                     res = this.copySettings(current, res);
                                 }
                                 else {
@@ -728,7 +819,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}`);
                     }
@@ -745,13 +836,13 @@ export class NEEDLE_progressive {
                         }
                         else if (res instanceof Texture && current instanceof Texture) {
                             // check if the texture has been disposed or not
-                            if (res.image?.data || res.source?.data) {
+                            if (hasPixelData(res.image) || getSourceData(res)) {
                                 res = this.copySettings(current, res);
                             }
                             // 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 +851,7 @@ export class NEEDLE_progressive {
                             }
                             else {
                                 resouceIsDisposed = true;
-                                this.previouslyLoaded.delete(KEY);
+                                this.cache.delete(KEY);
                             }
                         }
                         if (!resouceIsDisposed) {
@@ -912,30 +1003,32 @@ 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 (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;
             }
@@ -961,8 +1054,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/loaders.d.ts

@@ -28,14 +28,7 @@ export declare function setKTX2TranscoderLocation(location: string): void;
 export declare function createLoaders(renderer: WebGLRenderer | null): {
     dracoLoader: DRACOLoader;
     ktx2Loader: KTX2Loader;
-    meshoptDecoder: {
-        supported: boolean;
-        ready: Promise<void>;
-        decodeVertexBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array, filter?: string) => void;
-        decodeIndexBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array) => void;
-        decodeIndexSequence: (target: Uint8Array, count: number, size: number, source: Uint8Array) => void;
-        decodeGltfBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array, mode: string, filter?: string) => void;
-    };
+    meshoptDecoder: any;
 };
 export declare function addDracoAndKTX2Loaders(loader: GLTFLoader): void;
 /**

package/lib/loaders.js

@@ -1,3 +1,4 @@
+// @ts-ignore @types/three re-exports from meshoptimizer which may not resolve in all configs
 import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';

package/lib/lods.manager.js

@@ -1,4 +1,5 @@
-import { Box3, Clock, Matrix4, Mesh, MeshStandardMaterial, Sphere, Vector3 } from "three";
+// @ts-ignore Timer exists at runtime in r183 but @types/three doesn't export it from main entry yet
+import { Box3, Matrix4, Mesh, MeshStandardMaterial, Sphere, Timer, Vector3 } from "three";
 import { NEEDLE_progressive } from "./extension.js";
 import { createLoaders } from "./loaders.js";
 import { getParam, isDevelopmentServer, isMobileDevice } from "./utils.internal.js";
@@ -171,7 +172,7 @@ export class LODsManager {
         // })
     }
     #originalRender;
-    #clock = new Clock();
+    #clock = new Timer();
     #frame = 0;
     #delta = 0;
     #time = 0;
@@ -197,6 +198,7 @@ export class LODsManager {
             if (renderTarget == null || ("isXRRenderTarget" in renderTarget && renderTarget.isXRRenderTarget)) {
                 stack = 0;
                 self.#frame += 1;
+                self.#clock.update();
                 self.#delta = self.#clock.getDelta();
                 self.#time += self.#delta;
                 self._fpsBuffer.shift();

package/lib/utils.d.ts

@@ -5,7 +5,7 @@ export declare const isSSR: boolean;
  * @param obj the object to get the raycast mesh from
  * @returns the raycast mesh or null if not set
  */
-export declare function getRaycastMesh(obj: Object3D): BufferGeometry<any> | null;
+export declare function getRaycastMesh(obj: Object3D): BufferGeometry<any, any> | null;
 /**
  * Set the raycast mesh for an object.
  * The raycast mesh is a low poly version of the mesh used for raycasting. It is set when a mesh that has LOD level with more vertices is discovered for the first time

package/lib/utils.internal.d.ts

@@ -1,3 +1,31 @@
+import { Texture } from "three";
+/** Represents the possible shapes of texture image/source data in three.js.
+ * Source.data is typed as `{}` in r183 but at runtime can be ImageBitmap, HTMLImageElement, etc. */
+export type TextureImageData = {
+    width?: number;
+    height?: number;
+    depth?: number;
+    data?: ArrayBufferView | null;
+};
+/** Check if a value has image-like dimensions (width/height) */
+export declare function hasImageDimensions(value: unknown): value is {
+    width: number;
+    height: number;
+};
+/** Check if a value has pixel data (e.g. typed array from a DataTexture) */
+export declare function hasPixelData(value: unknown): value is {
+    data: ArrayBufferView;
+};
+/** Get the source data of a texture, typed for dimension/data access */
+export declare function getSourceData(tex: Texture): TextureImageData | null;
+/** Get the image of a texture, typed for dimension/data access.
+ * In r183, Texture.image is typed as `{}` but at runtime is an ImageBitmap, HTMLImageElement, etc. */
+export declare function getTextureImage(tex: Texture): TextureImageData | null;
+/** Get width/height of a texture from image or source data */
+export declare function getTextureDimensions(tex: Texture): {
+    width: number;
+    height: number;
+};
 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 +46,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 +61,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

@@ -1,3 +1,32 @@
+import { RedFormat, RedIntegerFormat, RGFormat, RGIntegerFormat, RGBFormat, RGBAFormat, RGBAIntegerFormat } from "three";
+/** Check if a value has image-like dimensions (width/height) */
+export function hasImageDimensions(value) {
+    return value != null && typeof value.width === 'number' && typeof value.height === 'number';
+}
+/** Check if a value has pixel data (e.g. typed array from a DataTexture) */
+export function hasPixelData(value) {
+    return value != null && value.data != null;
+}
+/** Get the source data of a texture, typed for dimension/data access */
+export function getSourceData(tex) {
+    const data = tex.source?.data;
+    return data != null && typeof data === 'object' ? data : null;
+}
+/** Get the image of a texture, typed for dimension/data access.
+ * In r183, Texture.image is typed as `{}` but at runtime is an ImageBitmap, HTMLImageElement, etc. */
+export function getTextureImage(tex) {
+    const img = tex.image;
+    return img != null && typeof img === 'object' ? img : null;
+}
+/** Get width/height of a texture from image or source data */
+export function getTextureDimensions(tex) {
+    const img = getTextureImage(tex);
+    const src = getSourceData(tex);
+    return {
+        width: img?.width || src?.width || 0,
+        height: img?.height || src?.height || 0,
+    };
+}
 const debug = getParam("debugprogressive");
 export function isDebugMode() {
     return debug;
@@ -71,7 +100,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 +144,96 @@ export class PromiseQueue {
         }
     }
 }
+// #region Texture Memory
+export function determineTextureMemoryInBytes(texture) {
+    const img = texture.image;
+    const width = img?.width ?? 0;
+    const height = img?.height ?? 0;
+    const depth = img?.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 === RedFormat)
+        channels = 1;
+    else if (format === RedIntegerFormat)
+        channels = 1;
+    else if (format === RGFormat)
+        channels = 2;
+    else if (format === RGIntegerFormat)
+        channels = 2;
+    else if (format === RGBFormat)
+        channels = 3;
+    else if (format === 1029)
+        channels = 3; // RGBIntegerFormat (not exported in r183)
+    else if (format === RGBAFormat)
+        channels = 4;
+    else if (format === RGBAIntegerFormat)
+        channels = 4;
+    // 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 = "4.0.0-alpha";
 globalThis["GLTF_PROGRESSIVE_VERSION"] = version;
 console.debug(`[gltf-progressive] version ${version || "-"}`);

package/lib/worker/loader.mainthread.js

@@ -1,6 +1,6 @@
 import { Box3, BufferAttribute, BufferGeometry, CompressedTexture, InterleavedBuffer, InterleavedBufferAttribute, Matrix3, Sphere, Texture, Vector3 } from "three";
 import { createLoaders, GET_LOADER_LOCATION_CONFIG } from "../loaders.js";
-import { isMobileDevice } from "../utils.internal.js";
+import { getTextureDimensions, isMobileDevice } from "../utils.internal.js";
 import { debug } from "../lods.debug.js";
 const workers = new Array();
 let getWorkerId = 0;
@@ -21,7 +21,7 @@ export function getWorker(opts) {
 class GLTFLoaderWorker {
     worker;
     static async createWorker(opts) {
-        const worker = new Worker(new URL(`./loader.worker.js`, import.meta.url), {
+        const worker = new Worker(new URL(`./gltf-progressive.worker.js`, import.meta.url), {
             type: 'module',
         });
         const instance = new GLTFLoaderWorker(worker, opts);
@@ -152,8 +152,7 @@ function processReceivedData(data) {
         let newTexture = null;
         if (texture.isCompressedTexture) {
             const mipmaps = texture.mipmaps;
-            const width = texture.image?.width || texture.source?.data?.width || -1;
-            const height = texture.image?.height || texture.source?.data?.height || -1;
+            const { width, height } = getTextureDimensions(texture);
             newTexture = new CompressedTexture(mipmaps, width, height, texture.format, texture.type, texture.mapping, texture.wrapS, texture.wrapT, texture.magFilter, texture.minFilter, texture.anisotropy, texture.colorSpace);
         }
         else {