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

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [4.0.0-alpha] - 2026-03-30
 - three.js 183
 
+## [3.6.0-beta.1] - 2026-06-09
+- Fix: texture LOD selection regressed for meshes that only have texture LODs (no mesh LODs); screen coverage is now computed unconditionally so texture LODs update with camera distance again.
+
+## [3.6.0-alpha.3] - 2026-05-27
+- Fix: stale progressive mesh and texture LOD requests no longer overwrite newer explicit targets, while still allowing useful intermediate LODs to apply during rapid target changes.
+- Fix: progressive worker/debug imports no longer assume `window` exists, and texture LOD selection now uses the renderer pixel ratio so main-thread and worker/offscreen renderers can make matching LOD decisions.
+
+## [3.6.0-alpha.2] - 2026-05-26
+- Add: mesh LOD selection can now be reused by renderers that manage their own batching, keeping progressive instanced meshes on independent LOD levels.
+- Add: `assignMeshLOD` can delegate applying a loaded geometry, so batched renderers can update one instance without changing every mesh that shares the source geometry.
+- Add: externally scheduled LOD loading work can be tracked by `LODsManager.awaitLoading`, keeping loading screens in sync with progressive instanced assets.
+
+## [3.6.0-alpha.1] - 2026-05-25
+- Improve: progressive texture loading now tracks material texture slots more carefully, keeping shared textures alive while they are still used and disposing them once the last tracked slot moves away.
+- Improve: concurrent progressive texture requests for the same material slot now share the same in-flight work, avoiding duplicate loads for heavily instanced scenes.
+- Improve: cached progressive resources are checked before and after waiting for a load slot, reducing duplicate network and GPU work when many instances request the same LOD at once.
+- Improve: `assignTextureLOD` now uses an explicit `{ force: true }` option for debug or explicit LOD overrides, while normal calls keep the best already-loaded texture LOD.
+- Improve: `debugprogressive=colors` and instancing LOD debug colors now use the same expanded LOD color palette.
+- Fix: shared progressive textures are no longer repeatedly loaded and disposed while cloned or instanced objects are still using them.
+
 ## [3.4.0-beta.3] - 2026-03-24
 - Add: `NEEDLE_progressive.maxConcurrentLoadingTasks` property to control how many LOD meshes and textures are allowed to be fetched concurrently. Defaults to `50`
 
@@ -248,4 +268,4 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - fix: LOD mesh assignment for multi-material meshes (meshes with multiple primitives)
 
 ## [1.0.0-alpha.5] - 2023-04-30
-- initial version
+- initial version

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Needle Tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -26,6 +26,8 @@ useNeedleProgressive(gltf_loader, webgl_renderer)
 
 Examples are in the `/examples` directory. Live versions can be found in the links below.  
 
+To view the examples locally with the current checkout's runtime, run `npm run examples:serve` and open the printed examples index URL.
+
 - [Loading comparisons](https://stackblitz.com/edit/gltf-progressive-comparison?file=package.json,index.html)
 - [Vanilla three.js](https://engine.needle.tools/demos/gltf-progressive/threejs/) - multiple models and animations
 - [React Three Fiber](https://engine.needle.tools/demos/gltf-progressive/r3f/)
@@ -34,6 +36,9 @@ Examples are in the `/examples` directory. Live versions can be found in the lin
   - [multiple \<model-viewer> elements](https://engine.needle.tools/demos/gltf-progressive/modelviewer-multiple)
 - [Needle Engine](https://stackblitz.com/edit/needle-engine-gltf-progressive?file=src%2Fmain.ts)
 - [Needle Cloud](https://cloud.needle.tools/view?file=Z23hmXBZN45qJ-ZN45qJ-world)
+- `examples/webgpu` - WebGPU renderer
+- `examples/offscreen` - main-thread OffscreenCanvas rendering
+- `examples/worker-rendering` - OffscreenCanvas rendering in a Worker
 
 **Interactive Examples**:
 - [Stackblitz](https://stackblitz.com/@marwie/collections/gltf-progressive)
@@ -74,10 +79,10 @@ gltfLoader.load(url, gltf => {
     <script type="importmap">
     {
         "imports": {
-            "three": "https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js",
-            "three/addons/": "https://cdn.jsdelivr.net/npm/three@latest/examples/jsm/",
-            "three/examples/": "https://cdn.jsdelivr.net/npm/three@latest/examples/",
-            "@needle-tools/gltf-progressive": "https://cdn.jsdelivr.net/npm/@needle-tools/gltf-progressive/gltf-progressive.min.js"
+            "three": "https://cdn.jsdelivr.net/npm/three@0.184.0/build/three.module.js",
+            "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.184.0/examples/jsm/",
+            "three/examples/": "https://cdn.jsdelivr.net/npm/three@0.184.0/examples/",
+            "@needle-tools/gltf-progressive": "https://cdn.jsdelivr.net/npm/@needle-tools/gltf-progressive@3.6.0-canary.5401de9/gltf-progressive.min.js"
         }
     }
     </script>
@@ -85,7 +90,7 @@ gltfLoader.load(url, gltf => {
 ```
 
 
-## react three fiber
+## React Three Fiber
 
 Full react-three-fiber example at: `examples/react-three-fiber`
 
@@ -100,7 +105,7 @@ function MyModel() {
 }
 ```
 
-## google \<model-viewer\>
+## Google \<model-viewer\>
 
 Full model-viewer example at: `examples/modelviewer.html`
 
@@ -110,13 +115,13 @@ Full model-viewer example at: `examples/modelviewer.html`
     <script type="importmap">
         {
             "imports": {
-                "three": "https://unpkg.com/three/build/three.module.js",
-                "three/": "https://unpkg.com/three/"
+                "three": "https://unpkg.com/three@0.184.0/build/three.module.js",
+                "three/": "https://unpkg.com/three@0.184.0/"
             }
         }
     </script>
     <!-- Include gltf-progressive -->
-    <script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/gltf-progressive/gltf-progressive.min.js"></script>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/gltf-progressive@3.6.0-canary.5401de9/gltf-progressive.min.js"></script>
     <!-- Include model-viewer -->
     <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.4.0/model-viewer.min.js"></script>
 </head>
@@ -129,7 +134,7 @@ Full model-viewer example at: `examples/modelviewer.html`
 
 ## Needle Engine
 
-[Needle Engine](https://needle.tools) natively supports progressive loading of these glTF files! See [docs.needle.tools](https://docs.needle.tools) for more information. 
+[Needle Engine](https://needle.tools) natively supports progressive loading of these glTF files! See [docs.needle.tools/gltf-progressive](https://engine.needle.tools/docs/gltf-progressive/) for more information. 
 
 
 # How can I generate assets for progressive loading
@@ -144,6 +149,36 @@ Create a new class extending `NEEDLE_progressive_plugin` and add your plugin by
 ### Wait for LODs being loaded
 Call `lodsManager.awaitLoading(<opts?>)` to receive a promise that will resolve when all object LODs that start loading during the next frame have finished to update. Use the optional options parameter to e.g. wait for more frames.
 
+### Worker loading and device pixel ratio
+Progressive mesh and texture LOD files can be loaded in a worker by enabling the `gltf-progressive-worker` URL parameter.
+
+```txt
+https://example.test/viewer?gltf-progressive-worker
+```
+
+LOD selection uses the renderer pixel ratio. For matching results across main-thread, worker, or offscreen rendering, configure the renderer with the same device pixel ratio before calling `useNeedleProgressive` or `LODsManager.get`.
+
+```ts
+const renderer = new WebGLRenderer({ canvas });
+renderer.setPixelRatio(devicePixelRatio);
+
+useNeedleProgressive(gltfLoader, renderer);
+```
+
+In a worker or offscreen renderer, pass the display DPR from the main thread and apply it to the renderer there as well.
+
+```ts
+// main thread
+worker.postMessage({ type: "init", devicePixelRatio: window.devicePixelRatio });
+
+// worker / offscreen renderer
+const renderer = new WebGLRenderer({ canvas: offscreenCanvas });
+renderer.setPixelRatio(message.devicePixelRatio);
+useNeedleProgressive(gltfLoader, renderer);
+```
+
+If the renderer does not expose a pixel ratio, gltf-progressive falls back to `globalThis.devicePixelRatio` and then `1`.
+
 ### Global LOD level override
 
 ### LOD Manager settings
@@ -174,10 +209,11 @@ Call `getRaycastMesh(<your_mesh_object>)`
 # Extension
 Read more about the [NEEDLE_progressive extension](./NEEDLE_progressive/README.md)
 
+# Documentation
+Read more about Needle Progressive GLTF loading in the [Needle Engine documentation](https://docs.needle.tools/engine/gltf-progressive/)
 
 # Contact ✒️
 <b>[🌵 needle — tools for creators](https://needle.tools)</b> • 
 [Twitter](https://twitter.com/NeedleTools) • 
 [Discord](https://discord.needle.tools) • 
 [Forum](https://forum.needle.tools)
-

package/examples/modelviewer-multiple.html

@@ -13,13 +13,13 @@
     <script type="importmap">
         {
             "imports": {
-                "three": "https://unpkg.com/three/build/three.module.js",
-                "three/": "https://unpkg.com/three/"
+                "three": "https://unpkg.com/three@0.184.0/build/three.module.js",
+                "three/": "https://unpkg.com/three@0.184.0/"
             }
         }
     </script>
     <script type="module"
-        src="https://cdn.jsdelivr.net/npm/@needle-tools/gltf-progressive/gltf-progressive.min.js"></script>
+        src="https://cdn.jsdelivr.net/npm/@needle-tools/gltf-progressive@3.6.0-canary.5401de9/gltf-progressive.min.js"></script>
     <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.4.0/model-viewer.min.js"></script>
 </head>
 
@@ -123,4 +123,4 @@
     }
 </style>
 
-</html>
+</html>

package/examples/modelviewer.html

@@ -7,14 +7,14 @@
     <script type="importmap">
         {
             "imports": {
-                "three": "https://unpkg.com/three/build/three.module.js",
-                "three/": "https://unpkg.com/three/"
+                "three": "https://unpkg.com/three@0.184.0/build/three.module.js",
+                "three/": "https://unpkg.com/three@0.184.0/"
             }
         }
     </script>
     <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.4.0/model-viewer.min.js"></script>
     <script type="module"
-        src="https://cdn.jsdelivr.net/npm/@needle-tools/gltf-progressive/gltf-progressive.min.js"></script>
+        src="https://cdn.jsdelivr.net/npm/@needle-tools/gltf-progressive@3.6.0-canary.5401de9/gltf-progressive.min.js"></script>
 </head>
 
 <model-viewer src="https://engine.needle.tools/demos/gltf-progressive/assets/church/model.glb" ar shadow-intensity="1"
@@ -31,4 +31,4 @@
     }
 </style>
 
-</html>
+</html>

package/examples/offscreen/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="icon" href="data:,">
+    <link rel="stylesheet" href="../shared/example.css">
+    <title>glTF Progressive Offscreen Rendering</title>
+</head>
+<body>
+    <canvas id="view"></canvas>
+    <div id="status" class="example-status">loading</div>
+    <script type="module" src="./main.js"></script>
+</body>
+</html>

package/examples/offscreen/main.js

@@ -0,0 +1,98 @@
+import { loadRuntime } from "../shared/runtime.js";
+import {
+    addLoadedScene,
+    createOrbitControls,
+    createExampleState,
+    createSceneChangeButton,
+    getInitialSceneIndex,
+    getModelUrl,
+    markError,
+    markReady,
+    markSceneLoaded,
+    markSceneLoading,
+    normalizeSceneIndex,
+    resizeRenderer,
+    setupScene,
+    setupRoomEnvironment,
+    trackLODChanges,
+} from "../shared/example-utils.js";
+
+const state = createExampleState("offscreen");
+const params = new URLSearchParams(location.search);
+
+try {
+    if (!globalThis.OffscreenCanvas) throw new Error("OffscreenCanvas is not available in this browser.");
+
+    const runtime = await loadRuntime();
+    const THREE = runtime.THREE;
+    const visibleCanvas = document.getElementById("view");
+    const visibleContext = visibleCanvas.getContext("bitmaprenderer");
+    if (!visibleContext) throw new Error("bitmaprenderer is not available in this browser.");
+
+    let width = window.innerWidth;
+    let height = window.innerHeight;
+    let pixelRatio = window.devicePixelRatio || 1;
+    const offscreenCanvas = new OffscreenCanvas(Math.max(1, width * pixelRatio), Math.max(1, height * pixelRatio));
+    const renderer = new THREE.WebGLRenderer({ canvas: offscreenCanvas, antialias: true });
+    const { scene, camera } = setupScene(THREE, width, height);
+    setupRoomEnvironment(THREE, runtime.RoomEnvironment, renderer, scene);
+    const controls = createOrbitControls(runtime.OrbitControls, camera, visibleCanvas);
+    let root = null;
+    let sceneIndex = getInitialSceneIndex(params);
+    let loadToken = 0;
+
+    function resize() {
+        width = window.innerWidth;
+        height = window.innerHeight;
+        pixelRatio = window.devicePixelRatio || 1;
+        visibleCanvas.width = Math.max(1, Math.floor(width * pixelRatio));
+        visibleCanvas.height = Math.max(1, Math.floor(height * pixelRatio));
+        resizeRenderer(renderer, camera, width, height, pixelRatio);
+    }
+    resize();
+
+    const firstLoader = new runtime.GLTFLoader();
+    const lodsManager = runtime.useNeedleProgressive(firstLoader, renderer);
+    trackLODChanges(lodsManager, state);
+
+    async function loadScene(nextIndex) {
+        const token = ++loadToken;
+        sceneIndex = normalizeSceneIndex(nextIndex);
+        const url = getModelUrl(params, sceneIndex);
+        markSceneLoading(state, sceneIndex, url);
+
+        const loader = token === 1 ? firstLoader : new runtime.GLTFLoader();
+        if (token !== 1) runtime.useNeedleProgressive(loader, renderer);
+
+        const nextRoot = await new Promise((resolve, reject) => {
+            loader.load(url, gltf => resolve(addLoadedScene(THREE, scene, gltf, { camera, controls })), undefined, reject);
+        });
+
+        if (token !== loadToken) {
+            nextRoot.removeFromParent();
+            return;
+        }
+
+        root?.removeFromParent();
+        root = nextRoot;
+        markSceneLoaded(state, runtime, root);
+        markReady(state, "offscreen-webgl");
+    }
+
+    window.addEventListener("resize", resize);
+    createSceneChangeButton(() => loadScene(sceneIndex + 1).catch(error => markError(state, error)));
+
+    function render() {
+        state.frames += 1;
+        controls.update();
+        renderer.render(scene, camera);
+        visibleContext.transferFromImageBitmap(offscreenCanvas.transferToImageBitmap());
+        requestAnimationFrame(render);
+    }
+
+    await loadScene(sceneIndex);
+    render();
+}
+catch (error) {
+    markError(state, error);
+}

package/examples/react-three-fiber/index.html

@@ -14,11 +14,11 @@
   <meta property="og:image" content="" />
 
   <meta name="robots" content="index,follow">
-  <link rel="stylesheet" href="./src/style.css">
+  <link rel="stylesheet" href="./src/styles.css">
 </head>
 
 <body>
   <script type="module" src="./src/index.tsx"></script>
   <div id="root" style="width:100vw; height:100vh;"></div>
 </body>
-</html>
+</html>