@needle-tools/gltf-progressive 3.5.0-rc → 3.6.0-alpha.1

package/lib/lods.manager.d.ts

@@ -1,4 +1,4 @@
-import { Camera, Material, Object3D, Scene, Texture, Vector3, WebGLRenderer } from "three";
+import { Camera, Color, Material, Object3D, Scene, Texture, Vector3, WebGLRenderer } from "three";
 import { NEEDLE_progressive_plugin } from "./plugins/plugin.js";
 import { PromiseGroupOptions } from "./lods.promise.js";
 export type LODManagerContext = {
@@ -8,6 +8,7 @@ export declare type LOD_Results = {
     mesh_lod: number;
     texture_lod: number;
 };
+export declare const lodDebugColors: number[];
 declare type LODChangedEventListener = (args: {
     type: "mesh" | "texture";
     level: number;
@@ -98,7 +99,31 @@ export declare class LODsManager {
     private readonly _newPromiseGroups;
     private _promiseGroupIds;
     /**
-     * Call to await LODs loading during the next render cycle.
+     * Returns a promise that resolves once all LOD requests initiated during the next render cycles have finished loading.
+     * This is useful for hiding low-resolution placeholders (e.g. with a loading overlay or CSS blur) until high-quality assets are ready.
+     *
+     * By default, the returned promise captures LOD loading requests for 2 frames and resolves when all of them complete.
+     * Use `waitForFirstCapture` if no LOD requests may happen immediately (e.g. after a scene switch).
+     *
+     * @param opts - Optional configuration for how long to capture and what to wait for. See {@link PromiseGroupOptions}.
+     * @returns A promise that resolves with `{ cancelled, awaited_count, resolved_count }` once all captured LOD loads complete (or the signal aborts).
+     *
+     * @example
+     * ```ts
+     * // Wait for initial LODs to finish loading, then remove a blur overlay
+     * const result = await lodsManager.awaitLoading({
+     *     frames: 5,
+     *     signal: AbortSignal.timeout(10_000),
+     * });
+     * console.log(`Loaded ${result.resolved_count} of ${result.awaited_count} LODs`);
+     * document.querySelector('.blur-overlay')?.remove();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Wait until at least one LOD starts loading before resolving
+     * await lodsManager.awaitLoading({ waitForFirstCapture: true });
+     * ```
      */
     awaitLoading(opts?: PromiseGroupOptions): Promise<{
         cancelled: boolean;
@@ -107,8 +132,29 @@ export declare class LODsManager {
     }>;
     private _postprocessPromiseGroups;
     private readonly _lodchangedlisteners;
-    addEventListener(evt: "changed", listener: LODChangedEventListener): void;
-    removeEventListener(evt: "changed", listener: LODChangedEventListener): void;
+    /**
+     * Register a listener that is called whenever a mesh or texture LOD level has finished loading and has been applied.
+     * The listener receives the type of asset (`"mesh"` or `"texture"`), the new LOD level, and the affected object.
+     *
+     * @param evt - The event type. Currently only `"changed"` is supported.
+     * @param listener - Callback invoked after a LOD swap completes.
+     * @return A function to unregister the listener.
+     *
+     * @example
+     * ```ts
+     * lodsManager.addEventListener("changed", ({ type, level, object }) => {
+     *     console.log(`${type} LOD changed to level ${level}`, object);
+     * });
+     * ```
+     */
+    addEventListener(evt: "changed", listener: LODChangedEventListener): () => void;
+    /**
+     * Remove a previously registered `"changed"` event listener.
+     * @param evt - The event type (`"changed"`).
+     * @param listener - The listener to remove.
+     * @return `true` if the listener was found and removed, `false` otherwise.
+     */
+    removeEventListener(evt: "changed", listener: LODChangedEventListener): boolean;
     private constructor();
     private _fpsBuffer;
     /**
@@ -116,6 +162,21 @@ export declare class LODsManager {
      */
     enable(): void;
     disable(): void;
+    /**
+     * Manually trigger a LOD update for a scene and camera.
+     * Only needed when {@link manual} is set to `true` — otherwise LOD updates happen automatically on each render call.
+     *
+     * @param scene - The scene containing objects with progressive LODs.
+     * @param camera - The camera used to determine screen coverage and LOD levels.
+     *
+     * @example
+     * ```ts
+     * const lodsManager = LODsManager.get(renderer);
+     * lodsManager.manual = true;
+     * // ... later, trigger an update at a specific point:
+     * lodsManager.update(scene, camera);
+     * ```
+     */
     update(scene: Scene, camera: Camera): void;
     private onAfterRender;
     /**
@@ -162,4 +223,5 @@ declare class LOD_state {
     readonly lastScreenspaceVolume: Vector3;
     lastCentrality: number;
 }
+export declare function getLODColor(level: number, target: Color): Color;
 export {};

package/lib/lods.manager.js

@@ -1,4 +1,4 @@
-import { Box3, Clock, Matrix4, Mesh, MeshStandardMaterial, Sphere, Vector3 } from "three";
+import { Box3, Clock, Color, Matrix4, Mesh, Sphere, Vector3 } from "three";
 import { NEEDLE_progressive } from "./extension.js";
 import { createLoaders } from "./loaders.js";
 import { getParam, isDevelopmentServer, isMobileDevice } from "./utils.internal.js";
@@ -7,11 +7,47 @@ import { getRaycastMesh } from "./utils.js";
 import { applyDebugSettings, debug, debug_OverrideLodLevel } from "./lods.debug.js";
 import { PromiseGroup } from "./lods.promise.js";
 const debugProgressiveLoading = getParam("debugprogressive");
+const debugProgressiveLODColors = debugProgressiveLoading === "colors";
 const suppressProgressiveLoading = getParam("noprogressive");
 const $lodsManager = Symbol("Needle:LODSManager");
 const $lodstate = Symbol("Needle:LODState");
 const $currentLOD = Symbol("Needle:CurrentLOD");
 const levels = { mesh_lod: -1, texture_lod: -1 };
+const debugLODColor = new Color();
+export const lodDebugColors = [
+    0x35d05f,
+    0xa8d83a,
+    0xf3d13b,
+    0xf29332,
+    0xf0523b,
+    0xa856f0,
+    0x49a7f2,
+    0x32d7c4,
+    0xff6b9d,
+    0x6f7df7,
+    0xd66fd2,
+    0x35a853,
+    0xb7a51f,
+    0xe05d2f,
+    0x3c78d8,
+    0x00a6a6,
+    0xd7263d,
+    0x7f52ff,
+    0x46b450,
+    0xf7a531,
+    0x2f9be0,
+    0xb84592,
+    0x8a9a2a,
+    0x1f6f8b,
+    0xf05a9d,
+    0x9b5de5,
+    0x00bbf9,
+    0x00f5d4,
+    0xfee440,
+    0xf15bb5,
+    0x4d908e,
+    0x555555,
+];
 /**
  * The LODsManager class is responsible for managing the LODs and progressive assets in the scene. It will automatically update the LODs based on the camera position, screen coverage and mesh density of the objects.
  * It must be enabled by calling the `enable` method.
@@ -116,7 +152,31 @@ export class LODsManager {
     _newPromiseGroups = [];
     _promiseGroupIds = 0;
     /**
-     * Call to await LODs loading during the next render cycle.
+     * Returns a promise that resolves once all LOD requests initiated during the next render cycles have finished loading.
+     * This is useful for hiding low-resolution placeholders (e.g. with a loading overlay or CSS blur) until high-quality assets are ready.
+     *
+     * By default, the returned promise captures LOD loading requests for 2 frames and resolves when all of them complete.
+     * Use `waitForFirstCapture` if no LOD requests may happen immediately (e.g. after a scene switch).
+     *
+     * @param opts - Optional configuration for how long to capture and what to wait for. See {@link PromiseGroupOptions}.
+     * @returns A promise that resolves with `{ cancelled, awaited_count, resolved_count }` once all captured LOD loads complete (or the signal aborts).
+     *
+     * @example
+     * ```ts
+     * // Wait for initial LODs to finish loading, then remove a blur overlay
+     * const result = await lodsManager.awaitLoading({
+     *     frames: 5,
+     *     signal: AbortSignal.timeout(10_000),
+     * });
+     * console.log(`Loaded ${result.resolved_count} of ${result.awaited_count} LODs`);
+     * document.querySelector('.blur-overlay')?.remove();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Wait until at least one LOD starts loading before resolving
+     * await lodsManager.awaitLoading({ waitForFirstCapture: true });
+     * ```
      */
     awaitLoading(opts) {
         const id = this._promiseGroupIds++;
@@ -145,17 +205,46 @@ export class LODsManager {
         }
     }
     _lodchangedlisteners = [];
+    /**
+     * Register a listener that is called whenever a mesh or texture LOD level has finished loading and has been applied.
+     * The listener receives the type of asset (`"mesh"` or `"texture"`), the new LOD level, and the affected object.
+     *
+     * @param evt - The event type. Currently only `"changed"` is supported.
+     * @param listener - Callback invoked after a LOD swap completes.
+     * @return A function to unregister the listener.
+     *
+     * @example
+     * ```ts
+     * lodsManager.addEventListener("changed", ({ type, level, object }) => {
+     *     console.log(`${type} LOD changed to level ${level}`, object);
+     * });
+     * ```
+     */
     addEventListener(evt, listener) {
         if (evt === "changed") {
             this._lodchangedlisteners.push(listener);
+            return () => {
+                this.removeEventListener(evt, listener);
+            };
         }
+        return () => { };
     }
+    /**
+     * Remove a previously registered `"changed"` event listener.
+     * @param evt - The event type (`"changed"`).
+     * @param listener - The listener to remove.
+     * @return `true` if the listener was found and removed, `false` otherwise.
+     */
     removeEventListener(evt, listener) {
+        let removed = false;
         if (evt === "changed") {
             const index = this._lodchangedlisteners.indexOf(listener);
-            if (index >= 0)
+            if (index >= 0) {
                 this._lodchangedlisteners.splice(index, 1);
+                removed = true;
+            }
         }
+        return removed;
     }
     // readonly plugins: NEEDLE_progressive_plugin[] = [];
     constructor(renderer, context) {
@@ -217,6 +306,21 @@ export class LODsManager {
         this.renderer.render = this.#originalRender;
         this.#originalRender = undefined;
     }
+    /**
+     * Manually trigger a LOD update for a scene and camera.
+     * Only needed when {@link manual} is set to `true` — otherwise LOD updates happen automatically on each render call.
+     *
+     * @param scene - The scene containing objects with progressive LODs.
+     * @param camera - The camera used to determine screen coverage and LOD levels.
+     *
+     * @example
+     * ```ts
+     * const lodsManager = LODsManager.get(renderer);
+     * lodsManager.manual = true;
+     * // ... later, trigger an update at a specific point:
+     * lodsManager.update(scene, camera);
+     * ```
+     */
     update(scene, camera) {
         this.internalUpdate(scene, camera);
     }
@@ -306,16 +410,6 @@ export class LODsManager {
                 case "MeshDepthMaterial":
                     continue;
             }
-            if (debugProgressiveLoading === "color") {
-                if (entry.material) {
-                    if (!entry.object["progressive_debug_color"]) {
-                        entry.object["progressive_debug_color"] = true;
-                        const randomColor = Math.random() * 0xffffff;
-                        const newMaterial = new MeshStandardMaterial({ color: randomColor });
-                        entry.object.material = newMaterial;
-                    }
-                }
-            }
             const object = entry.object;
             if (object instanceof Mesh || (object.isMesh)) {
                 this.updateLODs(scene, camera, object, desiredDensity);
@@ -374,6 +468,9 @@ export class LODsManager {
         if (debug && object.material && !object["isGizmo"]) {
             applyDebugSettings(object.material);
         }
+        if (debugProgressiveLODColors && object.material && !object["isGizmo"] && !object["isBatchedMesh"]) {
+            applyLODColor(object.material, levels.mesh_lod);
+        }
         for (const plugin of plugins) {
             plugin.onAfterUpdatedLOD?.(this.renderer, scene, camera, object, levels);
         }
@@ -390,7 +487,7 @@ export class LODsManager {
             return;
         if (Array.isArray(material)) {
             for (const mat of material) {
-                this.loadProgressiveTextures(mat, level);
+                this.loadProgressiveTextures(mat, level, overrideLodLevel);
             }
             return;
         }
@@ -403,13 +500,15 @@ export class LODsManager {
         else if (level < material[$currentLOD]) {
             update = true;
         }
-        if (overrideLodLevel !== undefined && overrideLodLevel >= 0) {
+        const forceExactTextureLOD = overrideLodLevel !== undefined && overrideLodLevel >= 0;
+        if (forceExactTextureLOD) {
             update = material[$currentLOD] != overrideLodLevel;
             level = overrideLodLevel;
         }
         if (update) {
             material[$currentLOD] = level;
-            const promise = NEEDLE_progressive.assignTextureLOD(material, level).then(_ => {
+            const options = forceExactTextureLOD ? { force: true } : undefined;
+            const promise = NEEDLE_progressive.assignTextureLOD(material, level, options).then(_ => {
                 this._lodchangedlisteners.forEach(l => l({ type: "texture", level, object: material }));
             });
             PromiseGroup.addPromise("texture", material, promise, this._newPromiseGroups);
@@ -745,3 +844,21 @@ class LOD_state {
     lastScreenspaceVolume = new Vector3();
     lastCentrality = 0;
 }
+function applyLODColor(material, level) {
+    if (level < 0)
+        return;
+    if (Array.isArray(material)) {
+        for (const mat of material) {
+            applyLODColor(mat, level);
+        }
+        return;
+    }
+    if ("color" in material && material.color instanceof Color) {
+        material.color.copy(getLODColor(level, debugLODColor));
+        material.needsUpdate = true;
+    }
+}
+export function getLODColor(level, target) {
+    const index = Math.max(0, Math.min(lodDebugColors.length - 1, Math.floor(level)));
+    return target.setHex(lodDebugColors[index]);
+}

package/lib/lods.promise.js

@@ -77,7 +77,7 @@ export class PromiseGroup {
         }
         if (this._maxPromisesPerObject >= 1) {
             if (this._seen.has(object)) {
-                let count = this._seen.get(object);
+                const count = this._seen.get(object);
                 if (count >= this._maxPromisesPerObject) {
                     if (debug)
                         console.warn(`PromiseGroup: Already awaiting object ignoring new promise for it.`);

package/lib/plugins/modelviewer.js

@@ -108,7 +108,7 @@ function _patchModelViewer(modelviewer) {
         function renderFrames() {
             if (needsRender) {
                 let forcedFrames = 0;
-                let interval = setInterval(() => {
+                const interval = setInterval(() => {
                     if (forcedFrames++ > 5) {
                         clearInterval(interval);
                         return;

package/lib/version.js

@@ -1,4 +1,4 @@
 // replaced at build time
-export const version = "3.5.0-rc";
+export const version = "3.6.0-alpha.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.5.0-rc",
+  "version": "3.6.0-alpha.1",
   "description": "three.js support for loading glTF or GLB files that contain progressive loading data",
   "homepage": "https://needle.tools",
   "author": {
@@ -12,6 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/needle-tools/gltf-progressive"
   },
+  "license": "MIT",
   "readme": "README.md",
   "keywords": [
     "three.js",
@@ -41,7 +42,8 @@
     "gltf-progressive.js",
     "gltf-progressive.min.js",
     "gltf-progressive.umd.cjs",
-    "NEEDLE_progressive"
+    "NEEDLE_progressive",
+    "LICENSE"
   ],
   "watch": {
     "build:lib": {