RFC(geo-layers) SharedTileLayer

[ibgreen-openai]

The deck.gl-community SharedTileLayer allows multiple layers x multiple views to load from the same tile source and reuse common tiles across views.

The community demo is here: https://visgl.github.io/deck.gl-community/docs/modules/geo-layers/api-reference/shared-tile-2d-layer

It would likely be a great basis for TerrainLayer, sharing terrain tiles between layers.

One tricky question is whether to try to make this layer replace TileLayer, that layer is heavily customizable and changing the implementation may be risky, and will likely break some applications.

• The plan below shows the big scope of unification
• On the other hand, several layers, MVTLayer, TerrainLayer, CARTO layers etc inherit from TileLayer, we need to make decisions in each of those cases as well.

Make Shared Tile Layer the TileLayer Replacement

Summary

• Replace the current parallel _SharedTile2DLayer path with a shared-backed TileLayer implementation.
• Keep TileLayer as the canonical public class and preserve strict drop-in compatibility for current props, subclasses, exported helper classes, callbacks, tests, and in-repo consumers.
• Keep _SharedTile2DLayer, _SharedTileset2D, and _SharedTile2DHeader as experimental alias exports around the same implementation, not a second behavior path.

Key Changes

• Refactor the existing TileLayer / Tileset2D stack so Tileset2D owns shared tile content, loading, request scheduling, cache eviction, stats, TileSource metadata, and subscriptions.
• Add internal per-consumer/per-viewport view state for selected tiles, visible tiles, refinement state, tree links, and sublayer caches.
• Preserve _Tile2DHeader compatibility by exposing stable view-scoped tile header facades with existing fields: isSelected, isVisible, state, layers, parent, children, content, data, isLoaded, isLoading, needsReload, abort, and setNeedsReload.
• Keep TilesetClass?: typeof Tileset2D working unchanged. Existing _Tileset2D subclasses such as H3, Quadbin, and custom app tilesets continue overriding getTileIndices, getTileId, getTileZoom, getTileMetadata, and getParentIndex.
• Keep custom refinementStrategy callbacks. Run them per viewport against that viewport’s tile header facades so mutations do not leak between views.
• Make one TileLayer instance automatically share tile content across all rendered viewports. Separate layer instances share only when passed the same external _SharedTileset2D.
• Broaden TileLayer.data additively to accept URL templates, loaders.gl TileSource, or an external _SharedTileset2D. URL-template behavior remains exact; explicit layer props override TileSource metadata; external tilesets are not finalized by layers.
• Preserve current render behavior: visible zoom gating, tile.layers caching semantics per layer/view, renderSubLayers, filterSubLayer, picking info, onViewportLoad, onTileLoad, onTileUnload, onTileError, errored-tile loaded state, abort/reload behavior, repeat views, and current cache defaults.
• Keep legacy state.tileset and public-ish tileset fields usable. For direct legacy access, tiles, selectedTiles, isLoaded, isTileVisible, _tiles, _cache, and opts reflect the active/default view; direct tileset.update(viewport) uses a default legacy view.

Public API

• TileLayer becomes the shared-backed replacement.
• _SharedTile2DLayer becomes an alias of TileLayer.
• _SharedTileset2D becomes an alias or thin experimental wrapper over _Tileset2D.
• _SharedTile2DHeader becomes an alias of _Tile2DHeader.
• SharedTile2DLayerProps aliases TileLayerProps.
• SharedTile2DLayerPickingInfo aliases TileLayerPickingInfo.
• SharedTileset2DProps / related shared tileset types map to the compatible Tileset2D surface.
• SharedRefinementStrategy aliases RefinementStrategy, including custom callback functions.
• Keep all exports on @deck.gl/geo-layers and deck.gl; do not add a separate tileset subpath.

Docs And Example

• Rewrite TileLayer docs to describe shared cache behavior, multi-view sharing, TileSource input, and external _SharedTileset2D.
• Reframe shared-layer docs as experimental alias/advanced shared-cache docs, not a parallel API.
• Update layer index docs, table of contents, docs/developer-guide/views.md, docs/whats-new.md, and affected WebGPU notes.
• Update the website example to use TileLayer as the main layer API and _SharedTileset2D only for explicit cross-layer sharing across main/minimap views.

Test Plan

• Keep existing TileLayer, Tileset2D, Tile2DHeader, MVTLayer, TerrainLayer, CARTO, and custom tileset tests passing unchanged.
• Add focused tests for export alias identity, URL templates, TileSource metadata precedence, external tileset ownership, same-layer multi-view deduped loading, separate-layer explicit sharing, per-view selected/visible state, per-view custom refinement callback isolation, LRU eviction across active views, released-view eviction, sublayer cache isolation, viewport-owned rendering/filtering, errored loads, aborted loads, reloads, and visible zoom gating.
• Run yarn, yarn build, yarn lint, yarn test-headless, yarn test-browser, and yarn test-website.

Assumptions

• “Fully compatible” means strict drop-in compatibility, including current exported _Tileset2D / _Tile2DHeader extension points and in-repo state usage.
• TileLayer is the final user-facing replacement; _Shared* names remain transitional experimental aliases.
• Same-layer multi-view sharing is automatic; cross-layer sharing is explicit through an external shared tileset.
• Existing MVTLayer, TerrainLayer, CARTO layers, and custom TilesetClass implementations should not require source changes beyond incidental type fixes if the refactor exposes existing type gaps.

[coveralls]

coverage: 83.286% (-0.1%) from 83.391% — ib/shared-tile-layer into master

[chrisgervang]

Looks like some lint thrashing on unmodified lines. Which is right?

[chrisgervang]

This would be experiential too, right? Is there an api doc on how to use it?

[chrisgervang]

Expect the adapter to be exported too?

[chrisgervang]

Would be nice if this example also had a toggle between shared and not shared, along with some stats to measure the benefit

[chrisgervang]

I'm not sure what the adapter is for if I'm reading these docs for the first time

[chrisgervang]

Ah, the adapter is for viewport transversal within the layer. I'd like to see if LayerManager could provide layers with a hook for this as a part of experimental graduation, unless users would want to write their own custom adapter for some reason