feat(core): add Deck#waitForFrameReady() Promise API

[akre54]

Summary

Adds a waitForFrameReady() Promise API to Deck for detecting when a frame is safe to capture during sequential rendering (video export, image sequences, headless rendering).

Motivation

When exporting video from deck.gl applications (e.g., noodles.gl), detecting when a frame is "ready to capture" is critical for correctness. The existing onAfterRender callback fires after GPU command submission but doesn't wait for:

• Async layer data to load (layer.isLoaded)
• Attribute updates to complete (AttributeManager cycles)
• Multiple render passes to settle

This leads to captured frames with stale/incomplete data. Polling onAfterRender with debounced timeouts works but is slow (~300ms per frame). This PR adds a deterministic signal for frame readiness, achieving 8.6× faster video export (308ms→36ms/frame) in noodles.gl.

API

deck.waitForFrameReady(options?: {
  timeout?: number,          // Max wait time in ms (default: 5000)
  checkLayers?: boolean,     // Check layer.isLoaded (default: true)
  checkAttributes?: boolean  // Check AttributeManager updates (default: true)
}): Promise<{
  layersReady: boolean,
  attributesReady: boolean,
  duration: number           // Time spent waiting in ms
}>

Resolves when:

• All layers have isLoaded === true (if checkLayers enabled)
• LayerManager has no pending update cycles (if checkAttributes enabled)
• No redraw is queued
• One onAfterRender cycle has completed

Rejects if timeout is reached before the above conditions are met.

Usage Example

// Sequential frame export for video
const deck = new Deck({...});

for (let frame = 0; frame < totalFrames; frame++) {
  const time = frame / fps;
  
  // Update layers with new timeline position
  deck.setProps({
    layers: [
      new ScatterplotLayer({
        data: getDataAtTime(time),
        transitions: null,  // Disable animations during export
        ...
      })
    ]
  });
  
  // Wait for frame to be ready
  await deck.waitForFrameReady();
  
  // Capture from canvas
  const imageData = canvas.toDataURL('image/png');
}

Implementation Details

• Chains onto user-provided onAfterRender (preserved via try/finally)
• Polls layer state and LayerManager update cycles
• Skips waiting if scene is already settled
• Timeout prevents indefinite hangs

Tests

6 new tests in test/modules/core/lib/deck.spec.ts:

• ✅ Resolves when layers loaded
• ✅ Waits for async data to settle
• ✅ Rejects on timeout
• ✅ checkLayers: false bypasses layer checks
• ✅ Throws if deck not initialized
• ✅ Preserves user onAfterRender

All 27 deck.spec.ts tests pass. All 272 core module tests pass.

Performance

Less than 1ms overhead per frame when layers are already loaded (single RAF + state check).

Limitations

Does not check for in-progress animations (layer transitions, viewport easing). For video export use cases, disable animations:

// Disable layer transitions during export
new ScatterplotLayer({
  data,
  transitions: null,  // Disable all transitions
  ...
})

// Disable viewport animations
deck.setProps({
  controller: { inertia: 0, transitionDuration: 0 }
})

Or use the onFrameComplete callback (#10361) which provides animationsInProgress flag.

Breaking Changes

None - purely additive API.

Related PRs

• feat(geo-layers): expose Layer.getTileLoadingState() and Tile2DHeader error state #10360: getTileLoadingState() for tile layers
• feat(core): Enhance onAfterRender with pass parameter and add hasActiveTransitions #10361: onFrameComplete callback with animation state detection

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

Benchmarks

Tested in noodles.gl video export (30fps, 100 frames, cached tiles):

Metric	Before (idle polling)	After (waitForFrameReady)	Improvement
Time per frame	308ms	36ms	8.6× faster
Export FPS	3.2	27.8	8.7×
Realtime factor	0.11×	0.93×	Near-realtime

---

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

[coveralls]

coverage: 83.407% (+0.02%) from 83.39% — akre54:frame-ready-api into visgl:master

[chrisgervang]

Do the majority of applications need duration? Can't they measure this trivially if they want it?

[chrisgervang]

This is a good pattern, but I don't see why this needs to be a part of deck's API.

Wouldn't a utility function with deck as a parameter be just as effective?

[akre54]

@chrisgervang: waitForFrameReady needs to temporarily replace onAfterRender to hook into the render loop, access LayerManager update cycle state, and restore the caller's existing handler via try/finally. A utility function taking deck as a parameter would need to reach into the same private internals at the same complexity, with no encapsulation benefit. The implementation has to live on Deck.

@Pessimistress - this PR adds waitForFrameReady() to the Deck class for headless/video-export use cases like noodles.gl, giving a deterministic signal for when a frame is safe to capture (vs. polling with debounced timeouts). Benchmarks show an 8.6x speedup in practice (308ms to 36ms per frame).