Skip to main content

SharedTileset2D

from v9.3experimental

SharedTileset2D is the shared cache and loading engine used by SharedTile2DLayer.

Its design goal is to separate:

  • shared tile content, request scheduling, and cache eviction
  • per-view selection and visibility state

This makes it possible to feed the same tileset to multiple layers and multiple views without duplicating tile requests or overwriting traversal state.

The tileset also owns the shared cache policy and the shared stats object used by the example infobox and other monitoring UIs.

See the SharedTile2DLayer example.

Installation​

npm install @deck.gl-community/geo-layers
import {SharedTileset2D} from '@deck.gl-community/geo-layers/tileset';
import type {SharedTileset2DProps} from '@deck.gl-community/geo-layers/tileset';

const tileset = new SharedTileset2D<DataT>(props as SharedTileset2DProps<DataT>);

Construction​

Create a tileset in one of two ways:

From getTileData​

const tileset = new SharedTileset2D({
  getTileData: async ({id, bbox}) => fetchTile(id, bbox),
  maxZoom: 14,
  maxCacheSize: 256
});

From a loaders.gl TileSource​

import type {TileSource} from '@loaders.gl/loader-utils';

const tileSource: TileSource = createTileSourceSomehow();
const tileset = SharedTileset2D.fromTileSource(tileSource, {
  maxCacheByteSize: 32 * 1024 * 1024
});

When backed by a TileSource, the tileset reads metadata once and adopts:

  • minZoom
  • maxZoom
  • boundingBox mapped to extent

Explicitly provided options still win over source metadata.

Properties and Methods​

Constructor Props​

getTileData (Function, optional)​

Tile payload loader used when not backing the tileset with a TileSource.

tileSource (TileSource, optional)​

loaders.gl tile source used for both metadata and tile loading.

extent (number[4] | null, optional)​

Bounding box limiting tile generation.

tileSize (number, optional)​

Tile size in pixels. Defaults to 512.

minZoom / maxZoom (number | null, optional)​

Zoom bounds used during tile selection.

maxCacheSize / maxCacheByteSize (number | null, optional)​

Cache limits for retained tiles.

  • maxCacheSize defaults to 100.
  • maxCacheSize is a high-water mark, not a hard cap.
  • Eviction uses least-recently-used order among tiles that are neither visible nor selected by any attached consumer.
  • If every cached tile is still visible, the cache may temporarily remain above the high-water mark.

maxRequests / debounceTime (number, optional)​

Request scheduling controls for tile loading.

refinementStrategy ('best-available' | 'no-overlap' | 'never' | Function, optional)​

Placeholder strategy used by attached SharedTile2DView consumers.

Instance Members​

tiles​

Current contents of the shared tile cache.

cacheByteSize​

Estimated byte size of loaded content currently retained in cache.

visibleTiles / selectedTiles​

Union views of tiles tracked across all attached consumers.

visibleTiles includes unloaded selected tiles so UI counters can reflect pending visibility as view state changes.

loadingTiles / unloadedTiles​

Current subsets of cached tiles that are loading or not yet loaded.

stats​

Live Stats object from @probe.gl/stats.

The shared tileset currently populates:

  • Tiles In Cache
  • Cache Size
  • Visible Tiles
  • Selected Tiles
  • Loading Tiles
  • Unloaded Tiles (cumulative evictions)
  • Consumers

minZoom / maxZoom​

Resolved zoom bounds after metadata overrides are applied.

subscribe(listener)​

Subscribes to tile load, unload, error, stats-change, and metadata update notifications.

The listener may provide:

  • onTileLoad
  • onTileUnload
  • onTileError
  • onUpdate
  • onError
  • onStatsChange

setOptions(opts)​

Updates runtime configuration and reapplies TileSource metadata overrides.

reloadAll()​

Marks retained cached tiles stale so they reload on the next traversal.

finalize()​

Aborts in-flight requests and clears the shared cache.

Ownership​

If a SharedTile2DLayer receives a SharedTileset2D instance through data, the tileset is treated as externally owned. You are responsible for calling finalize() when it is no longer needed.

Source​

modules/geo-layers/src/tileset