@needle-tools/gltf-progressive 3.4.0-rc → 4.0.0-alpha

package/lib/extension.js

@@ -1,1041 +0,0 @@
-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 { getRaycastMesh, registerRaycastMesh } from "./utils.js";
-// All of this has to be removed
-// import { getRaycastMesh, setRaycastMesh } from "../../engine_physics.js";
-// import { PromiseAllWithErrors, resolveUrl } from "../../engine_utils.js";
-import { plugins } from "./plugins/plugin.js";
-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 $progressiveTextureExtension = Symbol("needle-progressive-texture");
-export const EXTENSION_NAME = "NEEDLE_progressive";
-// #region EXT
-/**
- * The NEEDLE_progressive extension for the GLTFLoader is responsible for loading progressive LODs for meshes and textures.
- * This extension can be used to load different resolutions of a mesh or texture at runtime (e.g. for LODs or progressive textures).
- * @example
- * ```javascript
- * const loader = new GLTFLoader();
- * loader.register(new NEEDLE_progressive());
- * loader.load("model.glb", (gltf) => {
- *    const mesh = gltf.scene.children[0] as Mesh;
- *   NEEDLE_progressive.assignMeshLOD(context, sourceId, mesh, 1).then(mesh => {
- *     console.log("Mesh with LOD level 1 loaded", mesh);
- *  });
- * });
- * ```
- */
-export class NEEDLE_progressive {
-    /** The name of the extension */
-    get name() {
-        return EXTENSION_NAME;
-    }
-    // #region PUBLIC API
-    static getMeshLODExtension(geo) {
-        const info = this.getAssignedLODInformation(geo);
-        if (info?.key) {
-            return this.lodInfos.get(info.key);
-        }
-        return null;
-    }
-    static getPrimitiveIndex(geo) {
-        const index = this.getAssignedLODInformation(geo)?.index;
-        if (index === undefined || index === null)
-            return -1;
-        return index;
-    }
-    static getMaterialMinMaxLODsCount(material, minmax) {
-        const self = this;
-        // we can cache this material min max data because it wont change at runtime
-        const cacheKey = "LODS:minmax";
-        const cached = material[cacheKey];
-        if (cached != undefined)
-            return cached;
-        if (!minmax) {
-            minmax = {
-                min_count: Infinity,
-                max_count: 0,
-                lods: [],
-            };
-        }
-        if (Array.isArray(material)) {
-            for (const mat of material) {
-                this.getMaterialMinMaxLODsCount(mat, minmax);
-            }
-            material[cacheKey] = minmax;
-            return minmax;
-        }
-        if (debug === "verbose")
-            console.log("getMaterialMinMaxLODsCount", material);
-        if (material.type === "ShaderMaterial" || material.type === "RawShaderMaterial") {
-            const mat = material;
-            for (const slot of Object.keys(mat.uniforms)) {
-                const val = mat.uniforms[slot].value;
-                if (val?.isTexture === true) {
-                    processTexture(val, minmax);
-                }
-            }
-        }
-        else if (material.isMaterial) {
-            for (const slot of Object.keys(material)) {
-                const val = material[slot];
-                if (val?.isTexture === true) {
-                    processTexture(val, minmax);
-                }
-            }
-        }
-        else {
-            if (debug)
-                console.warn(`[getMaterialMinMaxLODsCount] Unsupported material type: ${material.type}`);
-        }
-        material[cacheKey] = minmax;
-        return minmax;
-        function processTexture(tex, minmax) {
-            const info = self.getAssignedLODInformation(tex);
-            if (info) {
-                const model = self.lodInfos.get(info.key);
-                if (model && model.lods) {
-                    minmax.min_count = Math.min(minmax.min_count, model.lods.length);
-                    minmax.max_count = Math.max(minmax.max_count, model.lods.length);
-                    for (let i = 0; i < model.lods.length; i++) {
-                        const lod = model.lods[i];
-                        if (lod.width) {
-                            minmax.lods[i] = minmax.lods[i] || { min_height: Infinity, max_height: 0 };
-                            minmax.lods[i].min_height = Math.min(minmax.lods[i].min_height, lod.height);
-                            minmax.lods[i].max_height = Math.max(minmax.lods[i].max_height, lod.height);
-                        }
-                    }
-                }
-            }
-        }
-    }
-    /** Check if a LOD level is available for a mesh or a texture
-     * @param obj the mesh or texture to check
-     * @param level the level of detail to check for (0 is the highest resolution). If undefined, the function checks if any LOD level is available
-     * @returns true if the LOD level is available (or if any LOD level is available if level is undefined)
-     */
-    static hasLODLevelAvailable(obj, level) {
-        if (Array.isArray(obj)) {
-            for (const mat of obj) {
-                if (this.hasLODLevelAvailable(mat, level))
-                    return true;
-            }
-            return false;
-        }
-        if (obj.isMaterial === true) {
-            for (const slot of Object.keys(obj)) {
-                const val = obj[slot];
-                if (val && val.isTexture) {
-                    if (this.hasLODLevelAvailable(val, level))
-                        return true;
-                }
-            }
-            return false;
-        }
-        else if (obj.isGroup === true) {
-            for (const child of obj.children) {
-                if (child.isMesh === true) {
-                    if (this.hasLODLevelAvailable(child, level))
-                        return true;
-                }
-            }
-        }
-        let lodObject;
-        let lodInformation;
-        if (obj.isMesh) {
-            lodObject = obj.geometry;
-        }
-        else if (obj.isBufferGeometry) {
-            lodObject = obj;
-        }
-        else if (obj.isTexture) {
-            lodObject = obj;
-        }
-        if (lodObject) {
-            if (lodObject?.userData?.LODS) {
-                const lods = lodObject.userData.LODS;
-                lodInformation = this.lodInfos.get(lods.key);
-                if (level === undefined)
-                    return lodInformation != undefined;
-                if (lodInformation) {
-                    if (Array.isArray(lodInformation.lods)) {
-                        return level < lodInformation.lods.length;
-                    }
-                    return level === 0;
-                }
-            }
-        }
-        return false;
-    }
-    /** Load a different resolution of a mesh (if available)
-     * @param context the context
-     * @param source the sourceid of the file from which the mesh is loaded (this is usually the component's sourceId)
-     * @param mesh the mesh to load the LOD for
-     * @param level the level of detail to load (0 is the highest resolution)
-     * @returns a promise that resolves to the mesh with the requested LOD level
-     * @example
-     * ```javascript
-     * const mesh = this.gameObject as Mesh;
-     * NEEDLE_progressive.assignMeshLOD(context, sourceId, mesh, 1).then(mesh => {
-     *    console.log("Mesh with LOD level 1 loaded", mesh);
-     * });
-     * ```
-     */
-    static assignMeshLOD(mesh, level) {
-        if (!mesh)
-            return Promise.resolve(null);
-        if (mesh instanceof Mesh || mesh.isMesh === true) {
-            const currentGeometry = mesh.geometry;
-            const lodinfo = this.getAssignedLODInformation(currentGeometry);
-            if (!lodinfo) {
-                return Promise.resolve(null);
-            }
-            for (const plugin of plugins) {
-                plugin.onBeforeGetLODMesh?.(mesh, level);
-            }
-            // const info = this.onProgressiveLoadStart(context, source, mesh, null);
-            mesh["LOD:requested level"] = level;
-            return NEEDLE_progressive.getOrLoadLOD(currentGeometry, level).then(geo => {
-                if (Array.isArray(geo)) {
-                    const index = lodinfo.index || 0;
-                    geo = geo[index];
-                }
-                if (mesh["LOD:requested level"] === level) {
-                    delete mesh["LOD:requested level"];
-                    if (geo && currentGeometry != geo) {
-                        const isGeometry = geo?.isBufferGeometry;
-                        // if (debug == "verbose") console.log("Progressive Mesh " + mesh.name + " loaded", currentGeometry, "→", geo, "\n", mesh)
-                        if (isGeometry) {
-                            mesh.geometry = geo;
-                        }
-                        else if (debug) {
-                            console.error("Invalid LOD geometry", geo);
-                        }
-                    }
-                }
-                // this.onProgressiveLoadEnd(info);
-                return geo;
-            }).catch(err => {
-                // this.onProgressiveLoadEnd(info);
-                console.error("Error loading mesh LOD", mesh, err);
-                return null;
-            });
-        }
-        else if (debug) {
-            console.error("Invalid call to assignMeshLOD: Request mesh LOD but the object is not a mesh", mesh);
-        }
-        return Promise.resolve(null);
-    }
-    static assignTextureLOD(materialOrTexture, level = 0) {
-        if (!materialOrTexture)
-            return Promise.resolve(null);
-        if (materialOrTexture.isMesh === true) {
-            const mesh = materialOrTexture;
-            if (Array.isArray(mesh.material)) {
-                const arr = new Array();
-                for (const mat of mesh.material) {
-                    const promise = this.assignTextureLOD(mat, level);
-                    arr.push(promise);
-                }
-                return Promise.all(arr).then(res => {
-                    const textures = new Array();
-                    for (const tex of res) {
-                        if (Array.isArray(tex)) {
-                            textures.push(...tex);
-                        }
-                    }
-                    return textures;
-                });
-            }
-            else {
-                return this.assignTextureLOD(mesh.material, level);
-            }
-        }
-        if (materialOrTexture.isMaterial === true) {
-            const material = materialOrTexture;
-            const promises = [];
-            const slots = new Array();
-            // Handle custom shaders / uniforms progressive textures. This includes support for VRM shaders
-            if (material.uniforms && (material.isRawShaderMaterial || material.isShaderMaterial === true)) {
-                // iterate uniforms of custom shaders
-                const shaderMaterial = material;
-                for (const slot of Object.keys(shaderMaterial.uniforms)) {
-                    const val = shaderMaterial.uniforms[slot].value;
-                    if (val?.isTexture === true) {
-                        const task = this.assignTextureLODForSlot(val, level, material, slot).then(res => {
-                            if (res && shaderMaterial.uniforms[slot].value != res) {
-                                shaderMaterial.uniforms[slot].value = res;
-                                shaderMaterial.uniformsNeedUpdate = true;
-                            }
-                            return res;
-                        });
-                        promises.push(task);
-                        slots.push(slot);
-                    }
-                }
-            }
-            else {
-                for (const slot of Object.keys(material)) {
-                    const val = material[slot];
-                    if (val?.isTexture === true) {
-                        const task = this.assignTextureLODForSlot(val, level, material, slot);
-                        promises.push(task);
-                        slots.push(slot);
-                    }
-                }
-            }
-            return Promise.all(promises).then(res => {
-                const textures = new Array();
-                for (let i = 0; i < res.length; i++) {
-                    const tex = res[i];
-                    const slot = slots[i];
-                    if (tex && tex.isTexture === true) {
-                        textures.push({ material, slot, texture: tex, level });
-                    }
-                    else {
-                        textures.push({ material, slot, texture: null, level });
-                    }
-                }
-                return textures;
-            });
-        }
-        if (materialOrTexture instanceof Texture || materialOrTexture.isTexture === true) {
-            const texture = materialOrTexture;
-            return this.assignTextureLODForSlot(texture, level, null, null);
-        }
-        return Promise.resolve(null);
-    }
-    // #region INTERNAL
-    static assignTextureLODForSlot(current, level, material, slot) {
-        if (current?.isTexture !== true) {
-            return Promise.resolve(null);
-        }
-        if (slot === "glyphMap") {
-            return Promise.resolve(current);
-        }
-        return NEEDLE_progressive.getOrLoadLOD(current, level).then(tex => {
-            // this can currently not happen
-            if (Array.isArray(tex)) {
-                console.warn("Progressive: Got an array of textures for a texture slot, this should not happen...");
-                return null;
-            }
-            if (tex?.isTexture === true) {
-                if (tex != current) {
-                    if (material && slot) {
-                        const assigned = material[slot];
-                        // Check if the assigned texture LOD is higher quality than the current LOD
-                        // This is necessary for cases where e.g. a texture is updated via an explicit call to assignTextureLOD
-                        if (assigned && !debug) {
-                            const assignedLOD = this.getAssignedLODInformation(assigned);
-                            if (assignedLOD && assignedLOD?.level < level) {
-                                if (debug === "verbose")
-                                    console.warn("Assigned texture level is already higher: ", assignedLOD.level, level, material, assigned, tex);
-                                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}.`);
-                            }
-                        }
-                        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();
-                    // }
-                }
-                // this.onProgressiveLoadEnd(info);
-                return tex;
-            }
-            else if (debug == "verbose") {
-                console.warn("No LOD found for", current, level);
-            }
-            // this.onProgressiveLoadEnd(info);
-            return null;
-        }).catch(err => {
-            // this.onProgressiveLoadEnd(info);
-            console.error("Error loading LOD", current, err);
-            return null;
-        });
-    }
-    parser;
-    url;
-    constructor(parser) {
-        const url = parser.options.path;
-        if (debug)
-            console.log("Progressive extension registered for", url);
-        this.parser = parser;
-        this.url = url;
-    }
-    _isLoadingMesh;
-    loadMesh = (meshIndex) => {
-        if (this._isLoadingMesh)
-            return null;
-        const ext = this.parser.json.meshes[meshIndex]?.extensions?.[EXTENSION_NAME];
-        if (!ext)
-            return null;
-        this._isLoadingMesh = true;
-        return this.parser.getDependency("mesh", meshIndex).then(mesh => {
-            this._isLoadingMesh = false;
-            if (mesh) {
-                NEEDLE_progressive.registerMesh(this.url, ext.guid, mesh, ext.lods?.length, 0, ext);
-            }
-            return mesh;
-        });
-    };
-    // private _isLoadingTexture;
-    // loadTexture = (textureIndex: number) => {
-    //     if (this._isLoadingTexture) return null;
-    //     const ext = this.parser.json.textures[textureIndex]?.extensions?.[EXTENSION_NAME] as NEEDLE_ext_progressive_texture;
-    //     if (!ext) return null;
-    //     this._isLoadingTexture = true;
-    //     return this.parser.getDependency("texture", textureIndex).then(tex => {
-    //         this._isLoadingTexture = false;
-    //         if (tex) {
-    //             NEEDLE_progressive.registerTexture(this.url, tex as Texture, ext.lods?.length, textureIndex, ext);
-    //         }
-    //         return tex;
-    //     });
-    // }
-    afterRoot(gltf) {
-        if (debug)
-            console.log("AFTER", this.url, gltf);
-        this.parser.json.textures?.forEach((textureInfo, index) => {
-            if (textureInfo?.extensions) {
-                const ext = textureInfo?.extensions[EXTENSION_NAME];
-                if (ext) {
-                    if (!ext.lods) {
-                        if (debug)
-                            console.warn("Texture has no LODs", ext);
-                        return;
-                    }
-                    let found = false;
-                    for (const key of this.parser.associations.keys()) {
-                        if (key.isTexture === true) {
-                            const val = this.parser.associations.get(key);
-                            if (val?.textures === index) {
-                                found = true;
-                                NEEDLE_progressive.registerTexture(this.url, key, ext.lods?.length, index, ext);
-                            }
-                        }
-                    }
-                    // If textures aren't used there are no associations - we still want to register the LOD info so we create one instance
-                    if (!found) {
-                        this.parser.getDependency("texture", index).then(tex => {
-                            if (tex) {
-                                NEEDLE_progressive.registerTexture(this.url, tex, ext.lods?.length, index, ext);
-                            }
-                        });
-                    }
-                }
-            }
-        });
-        this.parser.json.meshes?.forEach((meshInfo, index) => {
-            if (meshInfo?.extensions) {
-                const ext = meshInfo?.extensions[EXTENSION_NAME];
-                if (ext && ext.lods) {
-                    let found = false;
-                    for (const entry of this.parser.associations.keys()) {
-                        if (entry.isMesh) {
-                            const val = this.parser.associations.get(entry);
-                            if (val?.meshes === index) {
-                                found = true;
-                                NEEDLE_progressive.registerMesh(this.url, ext.guid, entry, ext.lods.length, val.primitives, ext);
-                            }
-                        }
-                    }
-                    // Note: we use loadMesh rather than this method so the mesh is surely registered at the right time when the mesh is created
-                    // // If meshes aren't used there are no associations - we still want to register the LOD info so we create one instance
-                    // if (!found) {
-                    //     this.parser.getDependency("mesh", index).then(mesh => {
-                    //         if (mesh) {
-                    //             NEEDLE_progressive.registerMesh(this.url, ext.guid, mesh as Mesh, ext.lods.length, undefined, ext);
-                    //         }
-                    //     });
-                    // }
-                }
-            }
-        });
-        return null;
-    }
-    /**
-     * Register a texture with LOD information
-     */
-    static registerTexture = (url, tex, level, index, ext) => {
-        if (!tex) {
-            if (debug)
-                console.error("!! gltf-progressive: Called register texture without texture");
-            return;
-        }
-        if (debug) {
-            const width = tex.image?.width || tex.source?.data?.width || 0;
-            const height = tex.image?.height || tex.source?.data?.height || 0;
-            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)
-        // see https://github.com/needle-tools/needle-engine-support/issues/133
-        if (tex.source)
-            tex.source[$progressiveTextureExtension] = ext;
-        const key = ext.guid;
-        NEEDLE_progressive.assignLODInformation(url, tex, key, level, index);
-        NEEDLE_progressive.lodInfos.set(key, ext);
-        NEEDLE_progressive.lowresCache.set(key, new WeakRef(tex));
-    };
-    /**
-     * Register a mesh with LOD information
-     */
-    static registerMesh = (url, key, mesh, level, index, ext) => {
-        const geometry = mesh.geometry;
-        if (!geometry) {
-            if (debug)
-                console.warn("gltf-progressive: Register mesh without geometry");
-            return;
-        }
-        if (!geometry.userData)
-            geometry.userData = {};
-        if (debug)
-            console.log("> Progressive: register mesh " + mesh.name, { index, uuid: mesh.uuid }, ext, mesh);
-        NEEDLE_progressive.assignLODInformation(url, geometry, key, level, index);
-        NEEDLE_progressive.lodInfos.set(key, ext);
-        const existingRef = NEEDLE_progressive.lowresCache.get(key);
-        let existing = existingRef?.deref();
-        if (existing) {
-            existing.push(mesh.geometry);
-        }
-        else {
-            existing = [mesh.geometry];
-        }
-        NEEDLE_progressive.lowresCache.set(key, new WeakRef(existing));
-        if (level > 0 && !getRaycastMesh(mesh)) {
-            registerRaycastMesh(mesh, geometry);
-        }
-        for (const plugin of plugins) {
-            plugin.onRegisteredNewMesh?.(mesh, ext);
-        }
-    };
-    /**
-     * Dispose cached resources to free memory.
-     * Call this when a model is removed from the scene to allow garbage collection of its LOD resources.
-     * Calls three.js `.dispose()` on cached Textures and BufferGeometries to free GPU memory.
-     * @param guid Optional GUID to dispose resources for a specific model. If omitted, all cached resources are cleared.
-     */
-    static dispose(guid) {
-        if (guid) {
-            this.lodInfos.delete(guid);
-            // Dispose lowres cache entries (original proxy resources)
-            const lowresRef = this.lowresCache.get(guid);
-            if (lowresRef) {
-                const lowres = lowresRef.deref();
-                if (lowres) {
-                    if (lowres.isTexture) {
-                        lowres.dispose();
-                    }
-                    else if (Array.isArray(lowres)) {
-                        for (const geo of lowres)
-                            geo.dispose();
-                    }
-                }
-                this.lowresCache.delete(guid);
-            }
-            // Dispose previously loaded LOD entries
-            for (const [key, entry] of this.previouslyLoaded) {
-                if (key.includes(guid)) {
-                    this._disposeCacheEntry(entry);
-                    this.previouslyLoaded.delete(key);
-                }
-            }
-        }
-        else {
-            this.lodInfos.clear();
-            for (const [, entryRef] of this.lowresCache) {
-                const entry = entryRef.deref();
-                if (entry) {
-                    if (entry.isTexture) {
-                        entry.dispose();
-                    }
-                    else if (Array.isArray(entry)) {
-                        for (const geo of entry)
-                            geo.dispose();
-                    }
-                }
-            }
-            this.lowresCache.clear();
-            for (const [, entry] of this.previouslyLoaded) {
-                this._disposeCacheEntry(entry);
-            }
-            this.previouslyLoaded.clear();
-        }
-    }
-    /** Dispose a single cache entry's three.js resource(s) to free GPU memory. */
-    static _disposeCacheEntry(entry) {
-        if (entry instanceof WeakRef) {
-            // Single resource — deref and dispose if still alive
-            const resource = entry.deref();
-            resource?.dispose();
-        }
-        else {
-            // Promise — may be in-flight or already resolved.
-            // Attach disposal to run after resolution.
-            entry.then(resource => {
-                if (resource) {
-                    if (Array.isArray(resource)) {
-                        for (const geo of resource)
-                            geo.dispose();
-                    }
-                    else {
-                        resource.dispose();
-                    }
-                }
-            }).catch(() => { });
-        }
-    }
-    /** 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();
-    /** this contains the geometry/textures that were originally loaded. Uses WeakRef to allow garbage collection when unused. */
-    static lowresCache = 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}.`);
-        // 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}`);
-            }
-        }
-    });
-    static workers = [];
-    static _workersIndex = 0;
-    static async getOrLoadLOD(current, level) {
-        const debugverbose = debug == "verbose";
-        /** this key is used to lookup the LOD information */
-        const LOD = this.getAssignedLODInformation(current);
-        if (!LOD) {
-            if (debug)
-                console.warn(`[gltf-progressive] No LOD information found: ${current.name}, uuid: ${current.uuid}, type: ${current.type}`, current);
-            return null;
-        }
-        const LODKEY = LOD?.key;
-        let lodInfo;
-        const isTextureRequest = current.isTexture === true;
-        // See https://github.com/needle-tools/needle-engine-support/issues/133
-        if (isTextureRequest) {
-            const tex = current;
-            if (tex.source && tex.source[$progressiveTextureExtension])
-                lodInfo = tex.source[$progressiveTextureExtension];
-        }
-        if (!lodInfo)
-            lodInfo = NEEDLE_progressive.lodInfos.get(LODKEY);
-        if (!lodInfo) {
-            if (debug)
-                console.warn(`Can not load LOD ${level}: no LOD info found for \"${LODKEY}\" ${current.name}`, current.type, NEEDLE_progressive.lodInfos);
-        }
-        else {
-            if (level > 0) {
-                let useLowRes = false;
-                const hasMultipleLevels = Array.isArray(lodInfo.lods);
-                if (hasMultipleLevels && level >= lodInfo.lods.length) {
-                    useLowRes = true;
-                }
-                else if (!hasMultipleLevels) {
-                    useLowRes = true;
-                }
-                if (useLowRes) {
-                    const lowresRef = this.lowresCache.get(LODKEY);
-                    if (lowresRef) {
-                        const lowres = lowresRef.deref();
-                        if (lowres)
-                            return lowres;
-                        // Resource was GC'd, remove stale entry
-                        this.lowresCache.delete(LODKEY);
-                        if (debug)
-                            console.log(`[gltf-progressive] Lowres cache entry was GC'd: ${LODKEY}`);
-                    }
-                    // Fallback to current if lowres was GC'd
-                    return null;
-                }
-            }
-            /** the unresolved LOD url */
-            const unresolved_lod_url = Array.isArray(lodInfo.lods) ? lodInfo.lods[level]?.path : lodInfo.lods;
-            // check if we have a uri
-            if (!unresolved_lod_url) {
-                if (debug && !lodInfo["missing:uri"]) {
-                    lodInfo["missing:uri"] = true;
-                    console.warn("Missing uri for progressive asset for LOD " + level, lodInfo);
-                }
-                return null;
-            }
-            /** the resolved LOD url */
-            const lod_url = resolveUrl(LOD.url, unresolved_lod_url);
-            // check if the requested file needs to be loaded via a GLTFLoader
-            if (lod_url.endsWith(".glb") || lod_url.endsWith(".gltf")) {
-                if (!lodInfo.guid) {
-                    console.warn("missing pointer for glb/gltf texture", lodInfo);
-                    return null;
-                }
-                // check if the requested file has already been loaded
-                const KEY = lod_url + "_" + lodInfo.guid;
-                const slot = await this.queue.slot(lod_url);
-                // check if the requested file is currently being loaded or was previously loaded
-                const existing = this.previouslyLoaded.get(KEY);
-                if (existing !== undefined) {
-                    if (debugverbose)
-                        console.log(`LOD ${level} was already loading/loaded: ${KEY}`);
-                    if (existing instanceof WeakRef) {
-                        // Previously resolved resource — check if still alive in memory
-                        const derefed = existing.deref();
-                        if (derefed) {
-                            let res = derefed;
-                            let resourceIsDisposed = false;
-                            if (res instanceof Texture && current instanceof Texture) {
-                                if (res.image?.data || res.source?.data) {
-                                    res = this.copySettings(current, res);
-                                }
-                                else {
-                                    resourceIsDisposed = true;
-                                }
-                            }
-                            else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
-                                if (!res.attributes.position?.array) {
-                                    resourceIsDisposed = true;
-                                }
-                            }
-                            if (!resourceIsDisposed) {
-                                return res;
-                            }
-                        }
-                        // Resource was garbage collected or disposed — remove stale entry and re-load
-                        this.previouslyLoaded.delete(KEY);
-                        if (debug)
-                            console.log(`[gltf-progressive] Re-loading GC'd/disposed resource: ${KEY}`);
-                    }
-                    else {
-                        // Promise — loading in progress or previously completed
-                        let res = await existing.catch(err => {
-                            console.error(`Error loading LOD ${level} from ${lod_url}\n`, err);
-                            return null;
-                        });
-                        let resouceIsDisposed = false;
-                        if (res == null) {
-                            // if the resource is null the last loading result didnt succeed (maybe because the url doesnt exist)
-                            // in which case we don't attempt to load it again
-                        }
-                        else if (res instanceof Texture && current instanceof Texture) {
-                            // check if the texture has been disposed or not
-                            if (res.image?.data || res.source?.data) {
-                                res = this.copySettings(current, res);
-                            }
-                            // if it has been disposed we need to load it again
-                            else {
-                                resouceIsDisposed = true;
-                                this.previouslyLoaded.delete(KEY);
-                            }
-                        }
-                        else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
-                            if (res.attributes.position?.array) {
-                                // the geometry is OK
-                            }
-                            else {
-                                resouceIsDisposed = true;
-                                this.previouslyLoaded.delete(KEY);
-                            }
-                        }
-                        if (!resouceIsDisposed) {
-                            return res;
-                        }
-                    }
-                }
-                // #region loading
-                if (!slot.use) {
-                    if (debug)
-                        console.log(`LOD ${level} was aborted: ${lod_url}`);
-                    return null; // the request was aborted, we don't load it again
-                }
-                const ext = lodInfo;
-                const request = new Promise(async (resolve, _) => {
-                    // const useWorker = true;
-                    if (useWorker) {
-                        const worker = await getWorker({});
-                        const res = await worker.load(lod_url);
-                        if (res.textures.length > 0) {
-                            // const textures = new Array<Texture>();
-                            for (const entry of res.textures) {
-                                let texture = entry.texture;
-                                NEEDLE_progressive.assignLODInformation(LOD.url, texture, LODKEY, level, undefined);
-                                if (current instanceof Texture) {
-                                    texture = this.copySettings(current, texture);
-                                }
-                                if (texture)
-                                    texture.guid = ext.guid;
-                                // textures.push(texture);
-                                return resolve(texture);
-                            }
-                            // if (textures.length > 0) {
-                            //     return resolve(textures);
-                            // }
-                        }
-                        if (res.geometries.length > 0) {
-                            const geometries = new Array();
-                            for (const entry of res.geometries) {
-                                const newGeo = entry.geometry;
-                                NEEDLE_progressive.assignLODInformation(LOD.url, newGeo, LODKEY, level, entry.primitiveIndex);
-                                geometries.push(newGeo);
-                            }
-                            return resolve(geometries);
-                        }
-                        return resolve(null);
-                    }
-                    // Old loading
-                    const loader = new GLTFLoader();
-                    addDracoAndKTX2Loaders(loader);
-                    if (debug) {
-                        await new Promise(resolve => setTimeout(resolve, 1000));
-                        if (debugverbose)
-                            console.warn("Start loading (delayed) " + lod_url, ext.guid);
-                    }
-                    let url = lod_url;
-                    if (ext && Array.isArray(ext.lods)) {
-                        const lodinfo = ext.lods[level];
-                        if (lodinfo.hash) {
-                            url += "?v=" + lodinfo.hash;
-                        }
-                    }
-                    const gltf = await loader.loadAsync(url).catch(err => {
-                        console.error(`Error loading LOD ${level} from ${lod_url}\n`, err);
-                        return resolve(null);
-                    });
-                    if (!gltf) {
-                        return resolve(null);
-                    }
-                    const parser = gltf.parser;
-                    if (debugverbose)
-                        console.log("Loading finished " + lod_url, ext.guid);
-                    let index = 0;
-                    if (gltf.parser.json.textures) {
-                        let found = false;
-                        for (const tex of gltf.parser.json.textures) {
-                            // find the texture index
-                            if (tex?.extensions) {
-                                const other = tex?.extensions[EXTENSION_NAME];
-                                if (other?.guid) {
-                                    if (other.guid === ext.guid) {
-                                        found = true;
-                                        break;
-                                    }
-                                }
-                            }
-                            index++;
-                        }
-                        if (found) {
-                            let tex = await parser.getDependency("texture", index);
-                            if (tex) {
-                                NEEDLE_progressive.assignLODInformation(LOD.url, tex, LODKEY, level, undefined);
-                            }
-                            if (debugverbose)
-                                console.log("change \"" + current.name + "\" → \"" + tex.name + "\"", lod_url, index, tex, KEY);
-                            if (current instanceof Texture)
-                                tex = this.copySettings(current, tex);
-                            if (tex) {
-                                tex.guid = ext.guid;
-                            }
-                            return resolve(tex);
-                        }
-                        else if (debug) {
-                            console.warn("Could not find texture with guid", ext.guid, gltf.parser.json);
-                        }
-                    }
-                    index = 0;
-                    if (gltf.parser.json.meshes) {
-                        let found = false;
-                        for (const mesh of gltf.parser.json.meshes) {
-                            // find the mesh index
-                            if (mesh?.extensions) {
-                                const other = mesh?.extensions[EXTENSION_NAME];
-                                if (other?.guid) {
-                                    if (other.guid === ext.guid) {
-                                        found = true;
-                                        break;
-                                    }
-                                }
-                            }
-                            index++;
-                        }
-                        if (found) {
-                            const mesh = await parser.getDependency("mesh", index);
-                            if (debugverbose)
-                                console.log(`Loaded Mesh \"${mesh.name}\"`, lod_url, index, mesh, KEY);
-                            if (mesh.isMesh === true) {
-                                const geo = mesh.geometry;
-                                NEEDLE_progressive.assignLODInformation(LOD.url, geo, LODKEY, level, 0);
-                                return resolve(geo);
-                            }
-                            else {
-                                const geometries = new Array();
-                                for (let i = 0; i < mesh.children.length; i++) {
-                                    const child = mesh.children[i];
-                                    if (child.isMesh === true) {
-                                        const geo = child.geometry;
-                                        NEEDLE_progressive.assignLODInformation(LOD.url, geo, LODKEY, level, i);
-                                        geometries.push(geo);
-                                    }
-                                }
-                                return resolve(geometries);
-                            }
-                        }
-                        else if (debug) {
-                            console.warn("Could not find mesh with guid", ext.guid, gltf.parser.json);
-                        }
-                    }
-                    // we could not find a texture or mesh with the given guid
-                    return resolve(null);
-                });
-                this.previouslyLoaded.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)) {
-                        // 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));
-                    }
-                    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);
-                    }
-                }
-                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));
-                }
-                return res;
-            }
-            else {
-                if (current instanceof Texture) {
-                    if (debugverbose)
-                        console.log("Load texture from uri: " + lod_url);
-                    const loader = new TextureLoader();
-                    const tex = await loader.loadAsync(lod_url);
-                    if (tex) {
-                        tex.guid = lodInfo.guid;
-                        tex.flipY = false;
-                        tex.needsUpdate = true;
-                        tex.colorSpace = current.colorSpace;
-                        if (debugverbose)
-                            console.log(lodInfo, tex);
-                    }
-                    else if (debug)
-                        console.warn("failed loading", lod_url);
-                    return tex;
-                }
-            }
-        }
-        return null;
-    }
-    static maxConcurrent = 50;
-    static queue = new PromiseQueue(NEEDLE_progressive.maxConcurrent, { debug: debug != false });
-    static assignLODInformation(url, res, key, level, index) {
-        if (!res)
-            return;
-        if (!res.userData)
-            res.userData = {};
-        const info = new LODInformation(url, key, level, index);
-        res.userData.LODS = info;
-        if ("source" in res && typeof res.source === "object")
-            res.source.LODS = info; // for tiled textures
-    }
-    static getAssignedLODInformation(res) {
-        if (!res)
-            return null;
-        if (res.userData?.LODS)
-            return res.userData.LODS;
-        if ("source" in res && res.source?.LODS)
-            return res.source.LODS;
-        return null;
-    }
-    // private static readonly _copiedTextures: WeakMap<Texture, Texture> = new Map();
-    static copySettings(source, target) {
-        if (!target) {
-            return source;
-        }
-        // const existingCopy = source["LODS:COPY"];
-        // don't copy again if the texture was processed before
-        // we clone the source if it's animated
-        // const existingClone = this._copiedTextures.get(source);
-        // if (existingClone) {
-        //     return existingClone;
-        // }
-        // We need to clone e.g. when the same texture is used multiple times (but with e.g. different wrap settings)
-        // This is relatively cheap since it only stores settings
-        {
-            if (debug === "verbose")
-                console.debug("Copy texture settings\n", source.uuid, "\n", target.uuid);
-            target = target.clone();
-        }
-        // else {
-        //     source = existingCopy;
-        // }
-        // this._copiedTextures.set(original, target);
-        // we re-use the offset and repeat settings because it might be animated
-        target.offset = source.offset;
-        target.repeat = source.repeat;
-        target.colorSpace = source.colorSpace;
-        target.magFilter = source.magFilter;
-        target.minFilter = source.minFilter;
-        target.wrapS = source.wrapS;
-        target.wrapT = source.wrapT;
-        target.flipY = source.flipY;
-        target.anisotropy = source.anisotropy;
-        if (!target.mipmaps)
-            target.generateMipmaps = source.generateMipmaps;
-        // if (!target.userData) target.userData = {};
-        // target["LODS:COPY"] = source;
-        // related: NE-4937
-        return target;
-    }
-}
-class LODInformation {
-    url;
-    /** the key to lookup the LOD information */
-    key;
-    level;
-    /** For multi objects (e.g. a group of meshes) this is the index of the object */
-    index;
-    constructor(url, key, level, index) {
-        this.url = url;
-        this.key = key;
-        this.level = level;
-        if (index != undefined)
-            this.index = index;
-    }
-}
-;