@needle-tools/gltf-progressive 4.0.0-alpha.1 → 4.0.0-alpha.2

package/lib/loaders.js

@@ -116,7 +116,9 @@ function prepareLoaders() {
         dracoLoader = new DRACOLoader();
         dracoLoader[$dracoDecoderPath] = DEFAULT_DRACO_DECODER_LOCATION;
         dracoLoader.setDecoderPath(DEFAULT_DRACO_DECODER_LOCATION);
-        dracoLoader.setDecoderConfig({ type: 'js' });
+        // three r185+ auto-selects WASM (preferred) or JS based on platform support, and
+        // setDecoderConfig is deprecated (removed in r194). The gstatic decoder path hosts both
+        // decoders, so dropping the forced-JS config lets it use the faster WASM decoder.
         dracoLoader.preload();
     }
     if (!ktx2Loader) {
@@ -143,8 +145,8 @@ const originalLoadFunction = GLTFLoader.prototype.load;
 function onLoad(...args) {
     const config = gltfLoaderConfigurations.get(this);
     let url_str = args[0];
-    const url = new URL(url_str, window.location.href);
-    if (url.hostname.endsWith("needle.tools")) {
+    const url = tryResolveUrl(url_str);
+    if (url?.hostname.endsWith("needle.tools")) {
         const progressive = config?.progressive !== undefined ? config.progressive : true;
         const usecase = config?.usecase ? config.usecase : "default";
         if (progressive) {
@@ -160,3 +162,15 @@ function onLoad(...args) {
     return res;
 }
 GLTFLoader.prototype.load = onLoad;
+function tryResolveUrl(url) {
+    try {
+        if (url instanceof URL) {
+            return url;
+        }
+        const base = globalThis.location?.href;
+        return base ? new URL(url, base) : new URL(url);
+    }
+    catch {
+        return null;
+    }
+}

package/lib/lods.debug.js

@@ -2,8 +2,8 @@ import { getParam } from "./utils.internal.js";
 export const debug = getParam("debugprogressive");
 let debug_RenderWireframe = undefined;
 export let debug_OverrideLodLevel = -1; // -1 is automatic
-if (debug) {
-    let maxLevel = 6;
+if (debug && typeof window !== "undefined") {
+    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;
@@ -52,6 +75,8 @@ export declare class LODsManager {
     static getObjectLODState(object: Object3D): LOD_state | undefined;
     static addPlugin(plugin: NEEDLE_progressive_plugin): void;
     static removePlugin(plugin: NEEDLE_progressive_plugin): void;
+    /** Read-only snapshot of the currently registered plugins, for inspection. Use {@link addPlugin} / {@link removePlugin} to modify the registry. */
+    static getPlugins(): readonly NEEDLE_progressive_plugin[];
     /**
      * Gets the LODsManager for the given renderer. If the LODsManager does not exist yet, it will be created.
      * @param renderer The renderer to get the LODsManager for.
@@ -98,17 +123,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,12 +188,28 @@ 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;
     /**
      * Update LODs in a scene
      */
     private internalUpdate;
+    private getRenderList;
     /** Update the LOD levels for the renderer. */
     private updateLODs;
     /** Load progressive textures for the given material
@@ -138,18 +226,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 +239,5 @@ declare class LOD_state {
     readonly lastScreenspaceVolume: Vector3;
     lastCentrality: number;
 }
+export declare function getLODColor(level: number, target: Color): Color;
 export {};