@needle-tools/gltf-progressive 3.6.0-alpha.3 → 3.6.0-beta.1

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';
@@ -142,8 +143,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) {
@@ -159,3 +160,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,7 +2,7 @@ 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) {
+if (debug && typeof window !== "undefined") {
     const maxLevel = 6;
     function debugToggleProgressive() {
         debug_OverrideLodLevel += 1;

package/lib/lods.manager.d.ts

@@ -75,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.
@@ -207,6 +209,7 @@ export declare class LODsManager {
      * 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

package/lib/lods.manager.js

@@ -1,4 +1,5 @@
-import { Box3, Clock, Color, Matrix4, Mesh, Sphere, Vector3 } from "three";
+import * as THREE from "three";
+import { Box3, 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";
@@ -12,6 +13,7 @@ const suppressProgressiveLoading = getParam("noprogressive");
 const $lodsManager = Symbol("Needle:LODSManager");
 const $lodstate = Symbol("Needle:LODState");
 const $currentLOD = Symbol("Needle:CurrentLOD");
+const ThreeRuntime = THREE;
 const levels = { mesh_lod: -1, texture_lod: -1 };
 const debugLODColor = new Color();
 export const lodDebugColors = [
@@ -48,6 +50,10 @@ export const lodDebugColors = [
     0x4d908e,
     0x555555,
 ];
+function createLODTimer() {
+    const Timer = ThreeRuntime.Timer || ThreeRuntime.Clock;
+    return new Timer();
+}
 const _meshLODWorldBox = new Box3();
 const _meshLODProjectedBox = new Box3();
 const _meshLODCameraSpaceBox = new Box3();
@@ -82,8 +88,10 @@ export function calculateMeshLODLevel(options) {
     result.screenCoverage = 0;
     result.screenspaceVolume.set(0, 0, 0);
     result.centrality = 1;
-    if (!meshLods?.length)
-        return result;
+    // Note: we intentionally do NOT early-return when there are no mesh LODs.
+    // The screen coverage / screenspace volume computed below is also consumed by
+    // the texture LOD selection, which must keep working for meshes that only have
+    // texture LODs (no mesh LODs). Only the mesh LOD-level selection loop is skipped.
     let boundingBox = options.boundingBox ?? geometry.boundingBox;
     if (!boundingBox) {
         geometry.computeBoundingBox();
@@ -159,16 +167,18 @@ export function calculateMeshLODLevel(options) {
         debugDrawLine(_meshLODCorner1, _meshLODCorner3, 0x0000ff);
         debugDrawLine(_meshLODCorner2, _meshLODCorner3, 0x0000ff);
     }
-    for (let i = 0; i < meshLods.length; i++) {
-        const lod = meshLods[i];
-        const density = lod.densities?.[primitiveIndex] || lod.density || .00001;
-        if (primitiveIndex > 0 && warnMissingPrimitiveDensities && isDevelopmentServer() && !lod.densities && !globalThis["NEEDLE:MISSING_LOD_PRIMITIVE_DENSITIES"]) {
-            globalThis["NEEDLE:MISSING_LOD_PRIMITIVE_DENSITIES"] = true;
-            console.warn(`[Needle Progressive] Detected usage of mesh without primitive densities. This might cause incorrect LOD level selection: Consider re-optimizing your model by updating your Needle Integration, Needle glTF Pipeline or running optimization again on Needle Cloud.`);
-        }
-        if (density / screenCoverage < desiredDensity) {
-            result.level = i;
-            break;
+    if (meshLods?.length) {
+        for (let i = 0; i < meshLods.length; i++) {
+            const lod = meshLods[i];
+            const density = lod.densities?.[primitiveIndex] || lod.density || .00001;
+            if (primitiveIndex > 0 && warnMissingPrimitiveDensities && isDevelopmentServer() && !lod.densities && !globalThis["NEEDLE:MISSING_LOD_PRIMITIVE_DENSITIES"]) {
+                globalThis["NEEDLE:MISSING_LOD_PRIMITIVE_DENSITIES"] = true;
+                console.warn(`[Needle Progressive] Detected usage of mesh without primitive densities. This might cause incorrect LOD level selection: Consider re-optimizing your model by updating your Needle Integration, Needle glTF Pipeline or running optimization again on Needle Cloud.`);
+            }
+            if (density / screenCoverage < desiredDensity) {
+                result.level = i;
+                break;
+            }
         }
     }
     return result;
@@ -219,6 +229,10 @@ export class LODsManager {
         if (index >= 0)
             plugins.splice(index, 1);
     }
+    /** Read-only snapshot of the currently registered plugins, for inspection. Use {@link addPlugin} / {@link removePlugin} to modify the registry. */
+    static getPlugins() {
+        return plugins;
+    }
     /**
      * 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.
@@ -390,11 +404,11 @@ export class LODsManager {
         // })
     }
     #originalRender;
-    #clock = new Clock();
     #frame = 0;
     #delta = 0;
     #time = 0;
     #fps = 0;
+    #clock = createLODTimer();
     _fpsBuffer = [60, 60, 60, 60, 60];
     /**
      * Enable the LODsManager. This will replace the render method of the renderer with a method that updates the LODs.
@@ -416,7 +430,8 @@ export class LODsManager {
             if (renderTarget == null || ("isXRRenderTarget" in renderTarget && renderTarget.isXRRenderTarget)) {
                 stack = 0;
                 self.#frame += 1;
-                self.#delta = self.#clock.getDelta();
+                self.#clock.update?.();
+                self.#delta = Math.max(self.#clock.getDelta(), 1 / 1000);
                 self.#time += self.#delta;
                 self._fpsBuffer.shift();
                 self._fpsBuffer.push(1 / self.#delta);
@@ -457,7 +472,9 @@ export class LODsManager {
     onAfterRender(scene, camera, _stack) {
         if (this.pause)
             return;
-        const renderList = this.renderer.renderLists.get(scene, 0);
+        const renderList = this.getRenderList(scene, camera, _stack);
+        if (!renderList)
+            return;
         const opaque = renderList.opaque;
         let updateLODs = true;
         // check if we're rendering a postprocessing pass
@@ -514,7 +531,9 @@ export class LODsManager {
      * Update LODs in a scene
      */
     internalUpdate(scene, camera) {
-        const renderList = this.renderer.renderLists.get(scene, 0);
+        const renderList = this.getRenderList(scene, camera, 0);
+        if (!renderList)
+            return;
         const opaque = renderList.opaque;
         this.projectionScreenMatrix.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
         const desiredDensity = this.targetTriangleDensity;
@@ -560,6 +579,30 @@ export class LODsManager {
             }
         }
     }
+    getRenderList(scene, camera, stack) {
+        const renderer = this.renderer;
+        let renderList = null;
+        if (renderer.isWebGPURenderer === true) {
+            const renderLists = renderer._renderLists;
+            if (!renderLists)
+                return null;
+            renderList = renderLists.get(scene, camera);
+        }
+        else if (renderer.isWebGLRenderer === true) {
+            const renderLists = renderer.renderLists;
+            if (!renderLists)
+                return null;
+            renderList = renderLists.get(scene, stack);
+        }
+        if (!renderList)
+            return null;
+        return {
+            opaque: renderList.opaque || [],
+            transparent: renderList.transparent || [],
+            transmissive: renderList.transmissive || renderList.transparentDoublePass || [],
+            transparentDoublePass: renderList.transparentDoublePass || [],
+        };
+    }
     /** Update the LOD levels for the renderer. */
     updateLODs(scene, camera, object, desiredDensity) {
         if (!object.userData) {
@@ -820,7 +863,8 @@ export class LODsManager {
                 if (this.context?.engine === "model-viewer") {
                     factor *= 1.5;
                 }
-                const screenSize = canvasHeight / window.devicePixelRatio;
+                const devicePixelRatio = this.renderer.getPixelRatio?.() || globalThis.devicePixelRatio || 1;
+                const screenSize = canvasHeight / devicePixelRatio;
                 const pixelSizeOnScreen = screenSize * factor;
                 let foundLod = false;
                 for (let i = texture_lods_minmax.lods.length - 1; i >= 0; i--) {

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,4 +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;

package/lib/utils.internal.js

@@ -1,11 +1,41 @@
+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;
 }
 export function getParam(name) {
-    if (typeof window === "undefined")
+    const href = globalThis.location?.href;
+    if (!href)
         return false;
-    const url = new URL(window.location.href);
+    const url = new URL(href);
     const param = url.searchParams.get(name);
     if (param == null || param === "0" || param === "false")
         return false;
@@ -44,7 +74,8 @@ export function resolveUrl(source, uri) {
 export function isMobileDevice() {
     if (_ismobile !== undefined)
         return _ismobile;
-    _ismobile = /iPhone|iPad|iPod|Android|IEMobile/i.test(navigator.userAgent);
+    const userAgent = globalThis.navigator?.userAgent || "";
+    _ismobile = /iPhone|iPad|iPod|Android|IEMobile/i.test(userAgent);
     if (getParam("debugprogressive"))
         console.log("[glTF Progressive]: isMobileDevice", _ismobile);
     return _ismobile;
@@ -55,9 +86,10 @@ let _ismobile;
  * @returns `true` if we are running in a development server (localhost or ip address).
  */
 export function isDevelopmentServer() {
-    if (typeof window === "undefined")
+    const href = globalThis.location?.href;
+    if (!href)
         return false;
-    const url = new URL(window.location.href);
+    const url = new URL(href);
     const isLocalhostOrIpAddress = url.hostname === "localhost" || /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(url.hostname);
     const isDevelopment = url.hostname === "127.0.0.1" || isLocalhostOrIpAddress;
     return isDevelopment;
@@ -74,8 +106,14 @@ export class PromiseQueue {
     constructor(maxConcurrent, opts = {}) {
         this.maxConcurrent = maxConcurrent;
         this.debug = opts.debug ?? false;
-        if (typeof window !== "undefined")
-            window.requestAnimationFrame(this.tick);
+        // Dedicated workers can have requestAnimationFrame when they are owned by a window.
+        // Other worker-like scopes do not, so keep the frame-based tick when available and fall back to timers otherwise.
+        if (typeof globalThis.requestAnimationFrame === "function") {
+            globalThis.requestAnimationFrame(this.tick);
+        }
+        else {
+            setTimeout(this.tick, 0);
+        }
     }
     tick = () => {
         this.internalUpdate();
@@ -118,9 +156,10 @@ export class PromiseQueue {
 }
 // #region Texture Memory
 export function determineTextureMemoryInBytes(texture) {
-    const width = texture.image?.width ?? 0;
-    const height = texture.image?.height ?? 0;
-    const depth = texture.image?.depth ?? 1;
+    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);
@@ -130,22 +169,22 @@ function getBytesPerPixel(texture) {
     // Determine channel count from format
     let channels = 4; // Default RGBA
     const format = texture.format;
-    if (format === 1024)
-        channels = 1; // RedFormat
-    else if (format === 1025)
-        channels = 1; // RedIntegerFormat
-    else if (format === 1026)
-        channels = 2; // RGFormat
-    else if (format === 1027)
-        channels = 2; // RGIntegerFormat
-    else if (format === 1022)
-        channels = 3; // RGBFormat
+    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
-    else if (format === 1023)
-        channels = 4; // RGBAFormat
-    else if (format === 1033)
-        channels = 4; // RGBAIntegerFormat
+        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;
@@ -177,6 +216,10 @@ export function detectGPUMemory() {
     if (rendererInfo !== undefined) {
         return rendererInfo?.estimatedMemory;
     }
+    if (typeof document === "undefined") {
+        rendererInfo = null;
+        return undefined;
+    }
     const canvas = document.createElement('canvas');
     const powerPreference = "high-performance";
     const gl = canvas.getContext('webgl', { powerPreference }) || canvas.getContext('experimental-webgl', { powerPreference });

package/lib/version.js

@@ -1,4 +1,4 @@
 // replaced at build time
-export const version = "3.6.0-alpha.3";
+export const version = "3.6.0-beta.1";
 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;
@@ -51,7 +51,10 @@ class GLTFLoaderWorker {
             url = URL.createObjectURL(new Blob([url]));
         }
         else if (!url.startsWith("blob:") && !url.startsWith("http:") && !url.startsWith("https:")) {
-            url = new URL(url, window.location.href).toString();
+            const base = globalThis.location?.href;
+            if (base) {
+                url = new URL(url, base).toString();
+            }
         }
         const options = {
             type: "load",
@@ -152,8 +155,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/gltf-progressive",
-  "version": "3.6.0-alpha.3",
+  "version": "3.6.0-beta.1",
   "description": "three.js support for loading glTF or GLB files that contain progressive loading data",
   "homepage": "https://needle.tools",
   "author": {
@@ -59,10 +59,13 @@
     "three": ">= 0.160.0"
   },
   "devDependencies": {
+    "@needle-tools/engine": "^5.1.0-alpha.6",
+    "@needle-tools/three-test-matrix": "^0.1.0",
     "@stylistic/eslint-plugin-ts": "^1.5.4",
-    "@types/three": "0.169.0",
+    "@types/three": "0.183.1",
     "@typescript-eslint/eslint-plugin": "^6.2.0",
     "@typescript-eslint/parser": "^6.2.0",
+    "@vitest/browser-playwright": "^4.1.8",
     "eslint": "^8.56.0",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-no-secrets": "^0.8.9",
@@ -71,8 +74,10 @@
     "eslint-plugin-xss": "^0.1.12",
     "nodemon": "^3.1.4",
     "npm-watch": "^0.13.0",
+    "playwright": "^1.60.0",
     "three": ">= 0.160.0",
-    "vite": "7"
+    "vite": "7",
+    "vitest": "^4.1.8"
   },
   "types": "./lib/index.d.ts"
 }