@loaders.gl/tiles 4.5.3 → 5.0.0-alpha.10

package/src/{tileset → tileset-3d/common}/tileset-traverser.ts

@@ -3,13 +3,21 @@
 // Copyright (c) vis.gl contributors
 
 import type {Tile3D} from './tile-3d';
-import {ManagedArray} from '../utils/managed-array';
-import {TILE_REFINEMENT} from '../constants';
-import {FrameState} from './helpers/frame-state';
+import {ManagedArray} from '../../utils/managed-array';
+import {TILE_REFINEMENT} from '../../constants';
+import {FrameState} from '../helpers/frame-state';
 
 export type TilesetTraverserProps = {
   loadSiblings?: boolean;
   skipLevelOfDetail?: boolean;
+  /** SSE above which tiles remain part of the non-skipping base traversal. */
+  baseScreenSpaceError?: number;
+  /** Required SSE reduction from the nearest requested or loaded ancestor before loading a tile. */
+  skipScreenSpaceErrorFactor?: number;
+  /** Minimum hierarchy levels between requested tiles during skip-LOD traversal. */
+  skipLevels?: number;
+  /** Requests only final tiles that meet the active SSE target when skip-LOD is enabled. */
+  immediatelyLoadDesiredLevelOfDetail?: boolean;
   updateTransforms?: boolean;
   onTraversalEnd?: (frameState) => any;
   viewportTraversersMap?: Record<string, any>;
@@ -19,6 +27,10 @@ export type TilesetTraverserProps = {
 export const DEFAULT_PROPS: Required<TilesetTraverserProps> = {
   loadSiblings: false,
   skipLevelOfDetail: false,
+  baseScreenSpaceError: 1024,
+  skipScreenSpaceErrorFactor: 16,
+  skipLevels: 1,
+  immediatelyLoadDesiredLevelOfDetail: false,
   updateTransforms: true,
   onTraversalEnd: () => {},
   viewportTraversersMap: {},
@@ -28,6 +40,9 @@ export const DEFAULT_PROPS: Required<TilesetTraverserProps> = {
 export class TilesetTraverser {
   options: Required<TilesetTraverserProps>;
 
+  /** Whether loaded content has disabled skip-LOD traversal for this tileset. */
+  disableSkipLevelOfDetail: boolean = false;
+
   // fulfill in traverse call
   root: any = null;
 
@@ -35,6 +50,8 @@ export class TilesetTraverser {
   selectedTiles: Record<string, Tile3D> = {};
   // tiles should be loaded from server
   requestedTiles: Record<string, Tile3D> = {};
+  /** Tiles intentionally held until the camera has remained still for the configured delay. */
+  deferredTiles: Record<string, Tile3D> = {};
   // tiles does not have render content
   emptyTiles: Record<string, Tile3D> = {};
 
@@ -56,6 +73,11 @@ export class TilesetTraverser {
     this.options = {...DEFAULT_PROPS, ...options};
   }
 
+  /** Returns whether skip-LOD traversal is enabled and supported by the loaded content. */
+  isSkipLevelOfDetailEnabled(): boolean {
+    return this.options.skipLevelOfDetail && !this.disableSkipLevelOfDetail;
+  }
+
   // tiles should be visible
   traverse(root, frameState, options) {
     this.root = root; // for root screen space error
@@ -73,6 +95,7 @@ export class TilesetTraverser {
 
   reset() {
     this.requestedTiles = {};
+    this.deferredTiles = {};
     this.selectedTiles = {};
     this.emptyTiles = {};
     this._traversalStack.reset();
@@ -137,7 +160,9 @@ export class TilesetTraverser {
         // Always load tiles in the base traversal
         // Select tiles that can't refine further
         this.loadTile(tile, frameState);
-        if (stoppedRefining) {
+        // Skip-LOD keeps a ready ancestor selected while descendants stream in. This prevents
+        // replacement holes when traversal jumps over one or more hierarchy levels.
+        if (stoppedRefining || this.isSkipLevelOfDetailEnabled()) {
           this.selectTile(tile, frameState);
         }
       }
@@ -149,6 +174,11 @@ export class TilesetTraverser {
       tile._shouldRefine = shouldRefine && parentRefines;
     }
 
+    this.completeTraversal(frameState);
+  }
+
+  /** Notifies the owning tileset when traversal is complete or its debounce interval expires. */
+  protected completeTraversal(frameState: FrameState): void {
     const newTime = new Date().getTime();
     if (this.traversalFinished(frameState) || newTime - this.lastUpdate > this.updateDebounceTime) {
       this.lastUpdate = newTime;
@@ -165,7 +195,8 @@ export class TilesetTraverser {
 
   /* eslint-disable complexity, max-statements */
   updateAndPushChildren(tile: Tile3D, frameState: FrameState, stack, depth): boolean {
-    const {loadSiblings, skipLevelOfDetail} = this.options;
+    const {loadSiblings} = this.options;
+    const skipLevelOfDetail = this.isSkipLevelOfDetailEnabled();
 
     const children = tile.children;
 
@@ -188,9 +219,10 @@ export class TilesetTraverser {
         }
         stack.push(child);
         hasVisibleChild = true;
-      } else if (checkRefines || loadSiblings) {
-        // Keep non-visible children loaded since they are still needed before the parent can refine.
-        // Or loadSiblings is true so always load tiles regardless of visibility.
+      } else if ((checkRefines || loadSiblings) && child._inRequestVolume) {
+        // Keep non-visible children loaded when they are inside their viewer request volume;
+        // they may still be needed before a replacement parent can refine. The request-volume
+        // check intentionally applies to sibling loading as well, preventing off-volume work.
         this.loadTile(child, frameState);
         this.touchTile(child, frameState);
       }
@@ -225,7 +257,7 @@ export class TilesetTraverser {
 
   // tile to render in the browser
   selectTile(tile: Tile3D, frameState: FrameState): void {
-    if (this.shouldSelectTile(tile)) {
+    if (this.shouldSelectTile(tile, frameState)) {
       // The tile can be selected right away and does not require traverseAndSelect
       tile._selectedFrame = frameState.frameNumber;
       this.selectedTiles[tile.id] = tile;
@@ -235,12 +267,30 @@ export class TilesetTraverser {
   // tile to load from server
   loadTile(tile: Tile3D, frameState: FrameState): void {
     if (this.shouldLoadTile(tile)) {
+      if (this.shouldDeferTileRequest(tile)) {
+        this.deferredTiles[tile.id] = tile;
+        return;
+      }
       tile._requestedFrame = frameState.frameNumber;
       tile._priority = tile._getPriority();
       this.requestedTiles[tile.id] = tile;
     }
   }
 
+  /**
+   * Returns whether an eligible peripheral request should wait for camera motion to settle.
+   *
+   * Eligibility and the current time window are calculated together when tile visibility updates.
+   * Keeping the active state on the tile also lets a queued scheduler callback cancel work that
+   * became deferred after its original traversal.
+   *
+   * @param tile - Tile considered for loading.
+   * @returns `true` when the request should be retried after the remaining delay.
+   */
+  shouldDeferTileRequest(tile: Tile3D): boolean {
+    return tile.priorityDeferred;
+  }
+
   // cache tile
   touchTile(tile: Tile3D, frameState: FrameState): void {
     tile.tileset._cache.touch(tile);
@@ -271,10 +321,13 @@ export class TilesetTraverser {
     return tile.hasUnloadedContent || tile.contentExpired;
   }
 
-  shouldSelectTile(tile: Tile3D): boolean {
-    // if select tile is in current frame
-    // and content available
-    return tile.contentAvailable && !this.options.skipLevelOfDetail;
+  /**
+   * Returns whether a tile's content is available and visible for rendering.
+   * @param tile Tile considered for rendering.
+   * @param frameState Current culling state.
+   */
+  shouldSelectTile(tile: Tile3D, frameState: FrameState): boolean {
+    return tile.contentAvailable && tile.contentVisibility(frameState) !== 'outside';
   }
 
   /** Decide if tile LoD (level of detail) is not sufficient under current viewport */
@@ -323,6 +376,7 @@ export class TilesetTraverser {
   // Ignores visibility.
   executeEmptyTraversal(root: Tile3D, frameState: FrameState): boolean {
     let allDescendantsLoaded = true;
+    let hasPendingLazyChildren = false;
     const stack = this._emptyTraversalStack;
     stack.push(root);
 
@@ -331,6 +385,12 @@ export class TilesetTraverser {
 
       const traverse = !tile.hasRenderContent && this.canTraverse(tile, frameState);
       const emptyLeaf = !tile.hasRenderContent && tile.children.length === 0;
+      if (tile.header.implicitSubtree) {
+        // An unresolved implicit boundary is not a proven empty leaf. Treating it as loaded would
+        // allow REPLACE traversal to drop its ancestor before availability and content are known.
+        hasPendingLazyChildren = true;
+        allDescendantsLoaded = false;
+      }
 
       // Traversal stops but the tile does not have content yet
       // There will be holes if the parent tries to refine to its children, so don't refine
@@ -353,6 +413,6 @@ export class TilesetTraverser {
         }
       }
     }
-    return root.hasEmptyContent || allDescendantsLoaded;
+    return (root.hasEmptyContent && !hasPendingLazyChildren) || allDescendantsLoaded;
   }
 }