RFC(geo-layers) Share TerrainLayer tile data

docs/api-reference/geo-layers/shared-tile-2d-layer.md

@@ -1,6 +1,6 @@
 # SharedTile2DLayer (Experimental)
 
-`_SharedTile2DLayer` is an experimental composite layer for rendering 2D tiled data when multiple layer instances or viewports should reuse one tile-content cache. It is a parallel API to [`TileLayer`](./tile-layer.md), not a replacement for `TileLayer`, `MVTLayer`, or `TerrainLayer`.
+`_SharedTile2DLayer` is an experimental composite layer for rendering 2D tiled data when multiple layer instances or viewports should reuse one tile-content cache. It is a parallel API to [`TileLayer`](./tile-layer.md), not a replacement for `TileLayer` or `MVTLayer`. `TerrainLayer` can consume the same shared cache machinery through its experimental `_terrainTileset` prop.
 
 Use `_SharedTile2DLayer` when the same tiled payload should feed multiple views, such as a main map and minimap. The layer keeps selection and visibility state per viewport, while [`_SharedTileset2D`](./shared-tileset-2d.md) owns loading, request scheduling, cache eviction, stats, and TileSource metadata.
 

docs/api-reference/geo-layers/shared-tileset-2d.md

@@ -35,7 +35,7 @@ import type {
 } from '@deck.gl/geo-layers';
 
 new SharedTileset2D<TileDataT, ViewStateT>(props: SharedTileset2DProps<TileDataT, ViewStateT>);
-SharedTileset2D.fromTileSource<TileDataT>(tileSource, props);
+SharedTileset2D.fromTileSource<TileDataT, ViewStateT>(tileSource, props);
 ```
 
 Provide either `getTileData` or `tileSource`. A shared tileset also needs an adapter before traversal is used. `_SharedTile2DLayer` installs `sharedTile2DDeckAdapter` automatically for deck.gl viewport traversal; applications constructing the tileset directly should usually pass that adapter themselves.
@@ -50,10 +50,11 @@ An external `_SharedTileset2D` can be passed to one or more `_SharedTile2DLayer`
 
 ## Runtime API
 
-- `tiles`, `selectedTiles`, `visibleTiles`, `loadingTiles`, and `cacheByteSize` expose current shared cache state.
+- `tiles`, `selectedTiles`, `visibleTiles`, `loadingTiles`, `cacheByteSize`, and `tileSize` expose current shared cache state.
 - `stats` is a `@probe.gl/stats` `Stats` object with tile cache, visibility, loading, eviction, and consumer counters.
 - `setOptions()` updates effective tileset options. Pass `{replace: true}` as the second argument to replace prior caller options instead of merging them.
 - `reloadAll()` marks selected tiles stale and drops unselected cached tiles.
+- `notifyTileContentChanged(tile)` recomputes cache bytes after a retained payload mutates in place, for example when `TerrainLayer` adds a shared projection mesh variant.
 - `subscribe()` listens for tile load, tile error, tile unload, metadata/config update, metadata error, and stats change events.
 - `finalize()` aborts in-flight requests and clears the shared cache.
 

docs/api-reference/geo-layers/terrain-layer.md

@@ -151,14 +151,51 @@ When in Tiled Mode, inherits from all [TileLayer](./tile-layer.md) properties. F
 
 ### Data Options
 
-#### `elevationData` (string | string[], required) {#elevationdata}
+#### `elevationData` (string | string[], optional) {#elevationdata}
 
 Image URL that encodes height data.
 
+Required unless `_terrainTileset` is supplied.
+
 - If the value is a valid URL, this layer will render a single mesh.
 - If the value is a string, and contains substrings `{x}` and `{y}`, it is considered a URL template. This layer will render a `TileLayer` of meshes. `{x}` `{y}` and `{z}` will be replaced with a tile's actual index when it is requested.
 - If the value is an array: multiple URL templates. See `TileLayer`'s `data` prop documentation for use cases.
 
+#### `_terrainTileset` (`_SharedTileset2D<_TerrainTileData>`, experimental) {#terraintileset}
+
+Caller-owned shared terrain tile cache for tiled mode. When supplied, `TerrainLayer` renders the shared payload through `_SharedTile2DLayer` instead of creating its own `TileLayer`.
+
+Use `_TerrainSource` to load projection-independent terrain payloads into `_SharedTileset2D`, then pass the same tileset to each `TerrainLayer` that should reuse those payloads:
+
+```ts
+import {
+  TerrainLayer,
+  _SharedTileset2D as SharedTileset2D,
+  _TerrainSource as TerrainSource,
+  sharedTile2DDeckAdapter
+} from '@deck.gl/geo-layers';
+
+const terrainSource = new TerrainSource({
+  elevationData: 'https://example.com/elevation/{z}/{x}/{y}.png',
+  texture: 'https://example.com/texture/{z}/{x}/{y}.png',
+  meshMaxError: 4
+});
+const terrainTileset = SharedTileset2D.fromTileSource(terrainSource, {
+  adapter: sharedTile2DDeckAdapter,
+  minZoom: 0,
+  maxZoom: 14
+});
+
+const layers = [
+  new TerrainLayer({id: 'terrain-a', _terrainTileset: terrainTileset}),
+  new TerrainLayer({id: 'terrain-b', _terrainTileset: terrainTileset, wireframe: true})
+];
+```
+
+The shared source owns elevation, texture, decoder, mesh, loader, and load option props. The shared tileset owns tile traversal and cache options. Individual `TerrainLayer` instances keep render props such as `color`, `wireframe`, `material`, and `operation`. The owner should call `terrainTileset.finalize()` when the cache is no longer needed.
+
+The base tile payload is projection-independent. Each terrain layer asks the shared payload for the mesh variant needed by its active view; MapView and GlobeView variants are cached on the shared tile data and reused by later terrain layers using the same projection.
+
 
 #### `texture` (string | null, optional) {#texture}
 
@@ -260,7 +297,7 @@ Forwarded to `SimpleMeshLayer`'s `material` prop.
 
 The `TerrainLayer` renders the following sublayers:
 
-* `tiles` - a [TileLayer](./tile-layer.md). Only rendered if `elevationData` is a URL template.
+* `tiles` - a [TileLayer](./tile-layer.md) when `elevationData` is a URL template, or an experimental [_SharedTile2DLayer](./shared-tile-2d-layer.md) when `_terrainTileset` is supplied.
 * `mesh` - a [SimpleMeshLayer](../mesh-layers/simple-mesh-layer.md) rendering the terrain mesh.
 
 

docs/whats-new.md

@@ -79,7 +79,7 @@ Class-specific improvements:
 
 - [TextLayer](./api-reference/layers/text-layer.md) now supports per-object clipping box; and making text "sticky" when its container is partially off-screen. See a demo with this [new example](https://deck.gl/examples/text-layer-clipping).
 - [TileLayer](./api-reference/geo-layers/tile-layer.md) adds new `visibleMinZoom` and `visibleMaxZoom` props to control the zoom range at which tiles are drawn, independent of the zoom range at which data is loaded.
-- Experimental [`_SharedTile2DLayer`](./api-reference/geo-layers/shared-tile-2d-layer.md) and [`_SharedTileset2D`](./api-reference/geo-layers/shared-tileset-2d.md) let 2D tiled layers reuse one tile-content cache across multiple views.
+- Experimental [`_SharedTile2DLayer`](./api-reference/geo-layers/shared-tile-2d-layer.md) and [`_SharedTileset2D`](./api-reference/geo-layers/shared-tileset-2d.md) let 2D tiled layers reuse one tile-content cache across multiple views. [`TerrainLayer`](./api-reference/geo-layers/terrain-layer.md) can now opt into that cache with `_TerrainSource` and `_terrainTileset`.
 - Improvements to [Tile3DLayer](./api-reference/geo-layers/tile-3d-layer.md) including better performance and tile tracking.
 - WebGPU now materializes constant layer attributes into full buffers through `AttributeManager`, improving compatibility for layers that rely on constant accessors.
 

modules/geo-layers/src/index.ts

@@ -16,6 +16,7 @@ export {default as H3ClusterLayer} from './h3-layers/h3-cluster-layer';
 export {default as H3HexagonLayer} from './h3-layers/h3-hexagon-layer';
 export {default as Tile3DLayer} from './tile-3d-layer/tile-3d-layer';
 export {default as TerrainLayer} from './terrain-layer/terrain-layer';
+export {TerrainSource as _TerrainSource} from './terrain-layer/terrain-source';
 export {default as MVTLayer} from './mvt-layer/mvt-layer';
 export {default as GeohashLayer} from './geohash-layer/geohash-layer';
 
@@ -36,6 +37,10 @@ export type {
 export type {TripsLayerProps} from './trips-layer/trips-layer';
 export type {QuadkeyLayerProps} from './quadkey-layer/quadkey-layer';
 export type {TerrainLayerProps} from './terrain-layer/terrain-layer';
+export type {
+  TerrainSourceProps as _TerrainSourceProps,
+  TerrainTileData as _TerrainTileData
+} from './terrain-layer/terrain-source';
 export type {Tile3DLayerProps} from './tile-3d-layer/tile-3d-layer';
 export type {MVTLayerProps, MVTLayerPickingInfo} from './mvt-layer/mvt-layer';
 export type {GeoCellLayerProps as _GeoCellLayerProps} from './geo-cell-layer/GeoCellLayer';

modules/geo-layers/src/shared-tileset-2d/shared-tileset-2d.ts

@@ -174,11 +174,11 @@ export class SharedTileset2D<DataT = any, ViewStateT = unknown> {
   }
 
   /** Convenience factory for wrapping a loaders.gl `TileSource`. */
-  static fromTileSource<DataT = any>(
+  static fromTileSource<DataT = any, ViewStateT = unknown>(
     tileSource: TileSource,
-    opts: Omit<SharedTileset2DProps<DataT>, 'tileSource' | 'getTileData'> = {}
-  ): SharedTileset2D<DataT> {
-    return new SharedTileset2D<DataT>({...opts, tileSource});
+    opts: Omit<SharedTileset2DProps<DataT, ViewStateT>, 'tileSource' | 'getTileData'> = {}
+  ): SharedTileset2D<DataT, ViewStateT> {
+    return new SharedTileset2D<DataT, ViewStateT>({...opts, tileSource});
   }
 
   /** All tiles currently present in the shared cache. */
@@ -220,6 +220,11 @@ export class SharedTileset2D<DataT = any, ViewStateT = unknown> {
     return this._minZoom;
   }
 
+  /** Pixel dimension used by the shared tile index and tile payloads. */
+  get tileSize(): number {
+    return this.opts.tileSize;
+  }
+
   /** Active refinement strategy for placeholder handling. */
   get refinementStrategy(): SharedRefinementStrategy {
     return this.opts.refinementStrategy || STRATEGY_DEFAULT;
@@ -328,6 +333,17 @@ export class SharedTileset2D<DataT = any, ViewStateT = unknown> {
     this._updateStats();
   }
 
+  /** Recomputes retained bytes after a cached tile payload mutates in place. */
+  notifyTileContentChanged(tile: SharedTile2DHeader<DataT>): void {
+    if (this._cache.get(tile.id) !== tile) {
+      return;
+    }
+    this._cacheByteSize = this._getCacheByteSize();
+    this._resizeCache();
+    this._notifyUpdate();
+    this._updateStats();
+  }
+
   /** Updates the selected and visible tile sets for one consumer. */
   updateConsumer(
     id: symbol,