feat(core): Enhance onAfterRender with pass parameter and add hasActiveTransitions

[akre54]

Summary

Enhances existing APIs instead of adding a new callback, reducing API proliferation while providing the same functionality.

Changes

1. onAfterRender Enhancement

Added pass parameter to distinguish between render pass types:

deck.setProps({
  onAfterRender: ({device, gl, pass}) => {
    if (pass === 'screen') {
      // Main render to screen - safe to capture
      captureFrame(gl);
    }
    // pass === 'picking' for mouse picking
    // pass === 'shadow' for shadow maps
  }
});

2. New hasActiveTransitions() Method

Checks for active viewport and layer uniform transitions:

if (!deck.hasActiveTransitions()) {
  // Scene is settled - no animations in progress
  captureFrame();
}

Why This Approach

Per @chrisgervang's feedback, enhancing existing APIs is better than adding new callbacks:

• No new API surface to maintain
• Composable with existing patterns
• Clear separation of concerns
• Backward compatible

Use Cases

Video Export

async function captureFrame(deck: Deck) {
  // Wait for data
  const allLoaded = deck.props.layers.every(l => l.isLoaded);
  if (!allLoaded) return;

  // Wait for animations
  if (deck.hasActiveTransitions()) {
    await new Promise(resolve => {
      const check = () => {
        if (!deck.hasActiveTransitions()) resolve();
        else requestAnimationFrame(check);
      };
      check();
    });
  }

  // Capture on next screen render
  return new Promise(resolve => {
    deck.setProps({
      onAfterRender: ({pass}) => {
        if (pass === 'screen') {
          captureFrameData();
          resolve();
        }
      }
    });
    deck.redraw();
  });
}

Screenshots

deck.setProps({
  onAfterRender: ({pass}) => {
    if (pass === 'screen' && !deck.hasActiveTransitions()) {
      const allLoaded = deck.props.layers.every(l => l.isLoaded);
      if (allLoaded) {
        screenshot();
      }
    }
  }
});

Comparison to Original PR

Original (new callback):

• Added onFrameComplete callback
• GPU timing (can be measured externally)
• layersRendered count (trivially available via deck.props.layers.length)

New Approach (enhance existing):

• Enhanced onAfterRender with pass parameter
• Added hasActiveTransitions() method
• Same functionality, less API surface

Testing

• ✅ Unit tests for onAfterRender pass parameter
• ✅ Unit tests for hasActiveTransitions() with layer transitions
• ✅ Unit tests for hasActiveTransitions() with viewport transitions
• ✅ Complete documentation with examples

Related

This addresses the feedback from the original PR discussion about reducing API proliferation. Instead of a new callback, we enhance what exists.

[chrisgervang]

Let's see if we can get the same end result without adding another render callback to the core API. I think there's additive way to get the same end result by enhancing onAfterRender with pass and adding deck.hasActiveTransitions

[chrisgervang]

Wouldn't a user have this trivially available in the callback? deck.props.layers.length

[chrisgervang]

What if instead of adding a new API we passed opts.pass through onAfterRender?

[chrisgervang]

We could add a top level deck.hasActiveTransitions(), add pass to onAfterRender, and then an application can implement this on their own.

This pattern could be shared in documentation in tips and tricks

[chrisgervang]

Can an application monitor GPU metrics timings on their own?

See getStats

[akre54]

@chrisgervang - Great point about API proliferation. Your suggestion to enhance existing APIs is cleaner than adding a new callback.

Revised approach:

1. Add pass parameter to existing onAfterRender(info) where info.pass indicates screen render vs picking pass
2. Add deck.hasActiveTransitions() method to check for:
   • Layer uniform transitions
   • GPU attribute interpolations
   • Viewport transitions
3. Document the "safe to capture" pattern in tips/tricks

For GPU timing, I'll check whether deck.getStats() already provides what we need.

Re: layersRendered field - You're right, it's trivially available via deck.props.layers.length. I'll remove it.

If this can all be achieved by enhancing existing APIs + documentation rather than adding a new callback, that's definitely better. Let me revise the approach and come back with an enhancement proposal instead.