//filament-android/com.google.android.filament.android/ChoreographerHelper

ChoreographerHelper

ChoreographerHelper is a utility class that encapsulates Android's Choreographer callbacks to properly schedule rendering loops and feed desired presentation timestamps and deadlines to Filament's Renderer.

It automatically utilizes Android 13+ (API 33) VsyncCallback and FrameTimeline APIs when available, gracefully falling back to traditional FrameCallback APIs on older Android versions.

This class can be used in two distinct architectural patterns: Inheritance Mode and Composition Mode.

Usage Example 1: Inheritance Mode (Recommended for Custom Handlers)

kotlin


public class MyFrameHandler extends ChoreographerHelper {
    
    public void onFrame(long frameTimeNanos, @Nullable Object frameData) {
        // Optional: Configure Filament FrameData or Presentation Timestamps
        if (Build.VERSION.SDK_INT >= 33 && frameData instanceof Choreographer.FrameData) {
            modelViewer.render((Choreographer.FrameData) frameData);
        } else {
            modelViewer.render(frameTimeNanos);
        }
    }
}

MyFrameHandler handler = new MyFrameHandler();
handler.post();

Usage Example 2: Composition Mode (Recommended for Anonymous Callbacks)

kotlin


ChoreographerHelper helper = new ChoreographerHelper(new ChoreographerHelper.Callback() {
    
    public void onFrame(long frameTimeNanos) {
        // Render frame...
    }
});

// Optional: Let the helper automatically apply frame timeline targets to your Renderer
helper.setRenderer(myRenderer);
helper.post();

Constructors


ChoreographerHelper	[main]
constructor()
Initializes a new `ChoreographerHelper` in Inheritance Mode.
constructor(callback: ChoreographerHelper.Callback)
Initializes a new `ChoreographerHelper` in Composition Mode with a client callback.

Types

Name	Summary
Callback	[main]
interface Callback
Callback interface for receiving frame synchronization events in Composition Mode.

Functions

Name	Summary
onFrame	[main]
open fun onFrame(frameTimeNanos: Long)
Base callback invoked when a new frame should be rendered.
[main]
open fun onFrame(frameTimeNanos: Long, frameData: Any)
Main callback invoked when a new frame should be rendered, providing optional payload telemetry.
post	[main]
open fun post()
Posts a callback to Android's Choreographer to schedule the next frame.
remove	[main]
open fun remove()
Cancels any pending frame synchronization callbacks, stopping the scheduling loop.
setRenderer	[main]
open fun setRenderer(renderer: Renderer)
Attaches an optional Filament Renderer to be automatically paced by this helper.