feat(geo-layers): expose Layer.getTileLoadingState() and Tile2DHeader error state

[akre54]

Summary

Adds getTileLoadingState() method to tile-based layers (TileLayer, MVTLayer, etc.) for visibility into tile loading/failure state during rendering.

Motivation

When exporting video or performing headless rendering with tile-based layers, it's critical to know when tiles are fully loaded vs still streaming. The existing layer.isLoaded property is binary (true/false) with no visibility into:

• How many tiles are pending
• How many have failed
• Whether the layer is actively loading vs settled

This leads to either:

1. Capturing frames too early (incomplete tiles)
2. Adding conservative delays that slow export unnecessarily

Applications like noodles.gl need granular tile state to make informed capture decisions.

API

layer.getTileLoadingState(): {
  pending: number,      // Tiles being fetched
  loaded: number,       // Tiles successfully in GPU
  failed: number,       // Tiles that errored
  total: number,        // Total tiles requested
  isComplete: boolean   // pending === 0 && failed === 0
} | null  // Returns null for non-tile layers

Implemented on:

• TileLayer
• MVTLayer (inherits from TileLayer)
• Other tile-based layers via TileLayer base

Returns null for non-tile layers (e.g., ScatterplotLayer).

Usage Example

const tileLayer = new MVTLayer({
  data: 'https://tiles.example.com/{z}/{x}/{y}.pbf',
  ...
});

deck.setProps({ layers: [tileLayer] });

// Poll until tiles complete
async function waitForTiles() {
  while (true) {
    const state = tileLayer.getTileLoadingState();
    if (!state) break; // Not a tile layer
    
    console.log(`Tiles: ${state.loaded}/${state.total} loaded, ${state.pending} pending`);
    
    if (state.isComplete) break;
    await new Promise(r => setTimeout(r, 100));
  }
  
  // All tiles ready - safe to capture
  captureFrame();
}

Implementation Details

• Extends Tileset2D to track per-state tile counts
• Added Tile2DHeader.isFailed getter (tracks _error field)
• Counts updated in tile lifecycle callbacks (load, error, reload)
• Zero overhead when not called (no extra bookkeeping)

Tests

10 new tests across:

• Tile2DHeader: error state transitions, reload recovery
• Tileset2D: null before update, pending→loaded transitions, failure counting
• TileLayer: state before/after viewport selection
• MVTLayer: inherits method correctly
• Base Layer: non-tile layers return null

All 69 tile layer tests pass. All 77 geo-layers module tests pass.

Performance

Less than 0.1ms per call (aggregates cached tile state, no iteration).

Breaking Changes

None - purely additive API.

Related PRs

• feat(core): add Deck#waitForFrameReady() Promise API #10362: waitForFrameReady() Promise API
• feat(core): add Deck#onFrameComplete callback with CPU/GPU timing and animation state #10361: onFrameComplete callback with animation state

Companion MapLibre PRs

• feat: add getViewportTileProgress() API and viewporttilesloaded event maplibre/maplibre-gl-js#7767: Viewport tile progress API
• feat: attach CPU timing metadata to render event maplibre/maplibre-gl-js#7768: Render timing metadata

Example Integration

For video export with tiles:

for (let frame = 0; frame < totalFrames; frame++) {
  deck.setProps({ layers: updateLayers(frame) });
  
  // Wait for deck + tiles
  await deck.waitForFrameReady();
  
  // Double-check tile state
  const tileState = tileLayer.getTileLoadingState();
  if (tileState && !tileState.isComplete) {
    console.warn(`Frame ${frame}: ${tileState.pending} tiles still loading`);
  }
  
  captureFrame();
}

---

Co-authored-by: Claude Sonnet 4.5 noreply@anthropic.com

[coveralls]

coverage: 83.405% (+0.02%) from 83.39% — akre54:tile-loading-state into visgl:master

[chrisgervang]

no visibility into:

How many tiles are pending
How many have failed
Whether the layer is actively loading vs settled

Capturing frames too early (incomplete tiles)

layer.isLoaded is supposed to be false if there are pending / actively loading tiles. The specifics may not be visible, but most cases should be covered already. If they aren't in some case, I'd consider that a bug and unintentional.

Exposing failed tiles seems to be the main new capability this adds since a tile layer is technically loaded even if all tiles failed.

[chrisgervang]

Tiles aren't a core concept to deck so I don't think this belongs on the base Layer.

Please isolate the changes to the geo-layers module.

[akre54]

Sure thing I can move to geo-layers