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

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 export { version as VERSION } from "./version.js";
 export * from "./extension.js";
 export * from "./plugins/index.js";
-export { LODsManager, type LOD_Results } from "./lods.manager.js";
+export { LODsManager, calculateMeshLODLevel, getLODColor, lodDebugColors, type LOD_Results, type MeshLODSelectionOptions, type MeshLODSelectionResult } from "./lods.manager.js";
 export { setDracoDecoderLocation, setKTX2TranscoderLocation, createLoaders, addDracoAndKTX2Loaders, configureLoader } from "./loaders.js";
 export { getRaycastMesh, registerRaycastMesh, useRaycastMeshes } from "./utils.js";
 import { WebGLRenderer } from "three";

package/lib/index.js

@@ -1,7 +1,7 @@
 export { version as VERSION } from "./version.js";
 export * from "./extension.js";
 export * from "./plugins/index.js";
-export { LODsManager } from "./lods.manager.js";
+export { LODsManager, calculateMeshLODLevel, getLODColor, lodDebugColors } from "./lods.manager.js";
 export { setDracoDecoderLocation, setKTX2TranscoderLocation, createLoaders, addDracoAndKTX2Loaders, configureLoader } from "./loaders.js";
 export { getRaycastMesh, registerRaycastMesh, useRaycastMeshes } from "./utils.js";
 import { addDracoAndKTX2Loaders, configureLoader, createLoaders } from "./loaders.js";

package/lib/lods.debug.js

@@ -3,7 +3,7 @@ export const debug = getParam("debugprogressive");
 let debug_RenderWireframe = undefined;
 export let debug_OverrideLodLevel = -1; // -1 is automatic
 if (debug) {
-    let maxLevel = 6;
+    const maxLevel = 6;
     function debugToggleProgressive() {
         debug_OverrideLodLevel += 1;
         if (debug_OverrideLodLevel >= maxLevel) {

package/lib/lods.manager.d.ts

@@ -1,4 +1,4 @@
-import { Camera, Material, Object3D, Scene, Texture, Vector3, WebGLRenderer } from "three";
+import { Box3, BufferGeometry, Camera, Color, Material, Matrix4, 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,29 @@ export declare type LOD_Results = {
     mesh_lod: number;
     texture_lod: number;
 };
+export declare const lodDebugColors: number[];
+export type MeshLODSelectionOptions = {
+    geometry: BufferGeometry;
+    matrixWorld: Matrix4;
+    camera: Camera;
+    projectionScreenMatrix: Matrix4;
+    desiredDensity: number;
+    canvasHeight?: number;
+    currentLevel?: number;
+    boundingBox?: Box3 | null;
+    xrEnabled?: boolean;
+    debugDrawLine?: (a: Vector3, b: Vector3, color: number) => void;
+    warnMissingPrimitiveDensities?: boolean;
+    target?: MeshLODSelectionResult;
+};
+export type MeshLODSelectionResult = {
+    level: number;
+    primitiveIndex: number;
+    screenCoverage: number;
+    screenspaceVolume: Vector3;
+    centrality: number;
+};
+export declare function calculateMeshLODLevel(options: MeshLODSelectionOptions): MeshLODSelectionResult;
 declare type LODChangedEventListener = (args: {
     type: "mesh" | "texture";
     level: number;
@@ -98,17 +121,64 @@ 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;
         awaited_count: number;
         resolved_count: number;
     }>;
+    /** Track LOD work started outside this manager so {@link awaitLoading} waits for it too. */
+    trackLoadingPromise<T>(type: "mesh" | "texture", object: object, promise: Promise<T>): Promise<T>;
     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 +186,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;
     /**
@@ -138,18 +223,7 @@ export declare class LODsManager {
      */
     private loadProgressiveMeshes;
     private readonly _sphere;
-    private readonly _tempBox;
-    private readonly _tempBox2;
-    private readonly tempMatrix;
     private readonly _tempWorldPosition;
-    private readonly _tempBoxSize;
-    private readonly _tempBox2Size;
-    private static corner0;
-    private static corner1;
-    private static corner2;
-    private static corner3;
-    private static readonly _tempPtInside;
-    private static isInside;
     private static skinnedMeshBoundsFrameOffsetCounter;
     private static $skinnedMeshBoundsOffset;
     private calculateLodLevel;
@@ -162,4 +236,5 @@ declare class LOD_state {
     readonly lastScreenspaceVolume: Vector3;
     lastCentrality: number;
 }
+export declare function getLODColor(level: number, target: Color): Color;
 export {};