@loaders.gl/tiles 5.0.0-alpha.1 → 5.0.0-alpha.3

package/src/tileset-3d/common/tileset-cache.ts

@@ -71,24 +71,32 @@ export class TilesetCache {
     }
   }
 
-  unloadTiles(tileset, unloadCallback): void {
+  /**
+   * Unloads least-recently-used tiles until the byte-native cache target is met.
+   *
+   * Tiles touched after the frame sentinel remain protected, so {@link Tileset3D.cacheBytes} is a
+   * soft target rather than a hard cap on the visible working set. Overflow headroom affects
+   * memory-adjusted SSE, not eviction of unused tiles.
+   *
+   * @param tileset - Tileset that owns the cache and reports estimated content memory.
+   * @param unloadCallback - Callback that releases content and decrements the memory estimate.
+   */
+  unloadTiles(
+    tileset: Tileset3D,
+    unloadCallback?: (tileset: Tileset3D, tile: Tile3D) => void
+  ): void {
     const trimTiles = this._trimTiles;
     this._trimTiles = false;
 
     const list = this._list;
 
-    const maximumMemoryUsageInBytes = tileset.maximumMemoryUsage * 1024 * 1024;
-
     // Traverse the list only to the sentinel since tiles/nodes to the
     // right of the sentinel were used this frame.
     // The sub-list to the left of the sentinel is ordered from LRU to MRU.
     const sentinel = this._sentinel;
     let node = list.head;
 
-    while (
-      node !== sentinel &&
-      (tileset.gpuMemoryUsageInBytes > maximumMemoryUsageInBytes || trimTiles)
-    ) {
+    while (node !== sentinel && (tileset.gpuMemoryUsageInBytes > tileset.cacheBytes || trimTiles)) {
       // @ts-expect-error
       const tile = node.item;
       // @ts-expect-error

package/src/tileset-3d/common/tileset-source.ts

@@ -9,6 +9,7 @@ import type {Tile3D} from './tile-3d';
 import type {Tileset3D} from './tileset-3d';
 import type {FrameState} from '../helpers/frame-state';
 import type {TILESET_TYPE} from '../../constants';
+import type {TilesetSpatialReference} from '../../spatial/spatial-types';
 
 /**
  * Parsed top-level tileset payload consumed by {@link Tileset3D} or a {@link Tileset3DSource}.
@@ -69,8 +70,22 @@ export type TilesetSourceInput = TilesetJSON | TilesetSourceRequest;
 export type TileContentLoadResult = {
   /** Whether the tile content request produced usable content. */
   loaded: boolean;
+  /** All payloads loaded for a tile, in source order. */
+  contents?: any[];
   /** Nested tileset metadata to install below the loaded tile, if any. */
   nestedTileset?: TilesetJSON;
+  /** Nested tilesets found among multiple content payloads. */
+  nestedTilesets?: TilesetJSON[];
+};
+
+/** Result of a source-managed lazy child-header request. */
+export type TileChildrenLoadResult = {
+  /** Whether a subtree resource was loaded and installed. */
+  loaded: boolean;
+  /** Number of available tiles described by the subtree, including its existing root placeholder. */
+  tileCount: number;
+  /** Number of lazy child-subtree references installed at the new boundary. */
+  childSubtreeCount: number;
 };
 
 /**
@@ -118,6 +133,8 @@ export type TilesetSourceMetadata = {
   lodMetricValue: number;
   /** Root refinement mode used as fallback by runtime tiles. */
   refine: string;
+  /** Format-discovered coordinate reference system metadata. */
+  spatialReference?: TilesetSpatialReference;
 };
 
 /**
@@ -157,6 +174,17 @@ export interface Tileset3DSource {
    */
   initialize(): Promise<void>;
 
+  /**
+   * Prepares option-dependent asynchronous source state before runtime headers are constructed.
+   *
+   * I3S uses this hook to sample elevation surfaces for its root bound after `Tileset3D` has
+   * applied spatial options. Sources without asynchronous header preparation omit the hook.
+   */
+  prepareTileset?(tileset: Tileset3D): Promise<void>;
+
+  /** Releases source-local caches and prevents late asynchronous work from mutating runtime tiles. */
+  destroy?(): void;
+
   /**
    * Returns normalized source metadata after initialization completes.
    */
@@ -186,6 +214,14 @@ export interface Tileset3DSource {
    */
   loadTileContent(tile: Tile3D): Promise<TileContentLoadResult>;
 
+  /**
+   * Loads and installs a complete lazy child-header group for a runtime tile.
+   *
+   * Sources that implement this hook retain ownership of resource parsing, caching, query
+   * inheritance, and archive resolution. Traversal calls it only after visibility and LOD checks.
+   */
+  loadTileChildren?(tile: Tile3D, frameState: FrameState): Promise<TileChildrenLoadResult>;
+
   /**
    * Resolves a tile-relative path to the final request URL.
    */

package/src/tileset-3d/common/tileset-traverser.ts

@@ -35,6 +35,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> = {};
 
@@ -73,6 +75,7 @@ export class TilesetTraverser {
 
   reset() {
     this.requestedTiles = {};
+    this.deferredTiles = {};
     this.selectedTiles = {};
     this.emptyTiles = {};
     this._traversalStack.reset();
@@ -137,7 +140,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.options.skipLevelOfDetail) {
           this.selectTile(tile, frameState);
         }
       }
@@ -225,7 +230,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 +240,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 +294,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 +349,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 +358,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 +386,6 @@ export class TilesetTraverser {
         }
       }
     }
-    return root.hasEmptyContent || allDescendantsLoaded;
+    return (root.hasEmptyContent && !hasPendingLazyChildren) || allDescendantsLoaded;
   }
 }