Choreographer

#include <choreographer.h>

Choreographer coordinates the timing of frame rendering.

Summary

This is the C version of the android.view.Choreographer object in Java. If you do not use Choreographer to pace your render loop, you may render too quickly for the display, increasing latency between frame submission and presentation.

Input events are guaranteed to be processed before the frame callback is called, and will not be run concurrently. Input and sensor events should not be handled in the Choregrapher callback.

The frame callback is also the appropriate place to run any per-frame state update logic. For example, in a game, the frame callback should be responsible for updating things like physics, AI, game state, and rendering the frame. Input and sensors should be handled separately via callbacks registered with AInputQueue and ASensorManager.

As of API level 33, apps can follow proper frame pacing and even choose a future frame to render. The API is used as follows:

  1. The app posts an AChoreographer_vsyncCallback to Choreographer to run on the next frame.
  2. The callback is called when it is the time to start the frame with an AChoreographerFrameCallbackData payload: information about multiple possible frame timelines.
  3. Apps can choose a frame timeline from the AChoreographerFrameCallbackData payload, depending on the frame deadline they can meet when rendering the frame and their desired presentation time, and subsequently notify SurfaceFlinger of the choice. Alternatively, for apps that do not choose a frame timeline, their frame would be presented at the earliest possible timeline.
    • The preferred frame timeline is the default frame timeline that the platform scheduled for the app, based on device configuration.
  4. SurfaceFlinger attempts to follow the chosen frame timeline, by not applying transactions or latching buffers before the desired presentation time.

On older devices, AChoreographer_postFrameCallback64 or AChoreographer_postFrameCallback can be used to lesser effect. They cannot be used to precisely plan your render timeline, but will rate limit to avoid overloading the display pipeline and increasing frame latency.

Typedefs
AChoreographer typedef
Opaque type that provides access to an AChoreographer object.
AChoreographerFrameCallbackData typedef
Opaque type that provides access to an AChoreographerFrameCallbackData object, which contains various methods to extract frame information.
AChoreographer_frameCallback)(long frameTimeNanos, void *data) typedef
void(*
Prototype of the function that is called when a new frame is being rendered.
AChoreographer_frameCallback64)(int64_t frameTimeNanos, void *data) typedef
void(*
Prototype of the function that is called when a new frame is being rendered.
AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, void *data) typedef
void(*
Prototype of the function that is called when the display refresh rate changes.
AChoreographer_vsyncCallback)(const AChoreographerFrameCallbackData *callbackData, void *data) typedef
void(*
Prototype of the function that is called when a new frame is being rendered.
AVsyncId typedef
int64_t
The identifier of a frame timeline.

Variables
instead

Functions
AChoreographerFrameCallbackData_getFrameTimeNanos(const AChoreographerFrameCallbackData *data)
int64_t
The time in nanoseconds at which the frame started being rendered.
AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos(const AChoreographerFrameCallbackData *data, size_t index)
int64_t
Gets the time in nanoseconds at which the frame described at the given index needs to be ready by in order to be presented on time.
AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(const AChoreographerFrameCallbackData *data, size_t index)
int64_t
Gets the time in nanoseconds at which the frame described at the given index is expected to be presented.
AChoreographerFrameCallbackData_getFrameTimelineVsyncId(const AChoreographerFrameCallbackData *data, size_t index)
Gets the token used by the platform to identify the frame timeline at the given index.
AChoreographerFrameCallbackData_getFrameTimelinesLength(const AChoreographerFrameCallbackData *data)
size_t
The number of possible frame timelines.
AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex(const AChoreographerFrameCallbackData *data)
size_t
Gets the index of the platform-preferred frame timeline.
AChoreographer_getInstance()
Get the AChoreographer instance for the current thread.
AChoreographer_postFrameCallback(AChoreographer *choreographer, AChoreographer_frameCallback callback, void *data) __DEPRECATED_IN(29
void
Deprecated. Use AChoreographer_postFrameCallback64, which does not have the bug described above.
Post a callback to be run when the application should begin rendering the next frame.
AChoreographer_postFrameCallback64(AChoreographer *choreographer, AChoreographer_frameCallback64 callback, void *data)
void
Post a callback to be run when the application should begin rendering the next frame.
AChoreographer_postFrameCallbackDelayed(AChoreographer *choreographer, AChoreographer_frameCallback callback, void *data, long delayMillis) __DEPRECATED_IN(29
void
Deprecated. Use AChoreographer_postFrameCallbackDelayed64, which does not have the bug described above.
Post a callback to be run when the application should begin rendering the next frame following the specified delay.
AChoreographer_postFrameCallbackDelayed64(AChoreographer *choreographer, AChoreographer_frameCallback64 callback, void *data, uint32_t delayMillis)
void
Post a callback to be run when the application should begin rendering the next frame following the specified delay.
AChoreographer_postVsyncCallback(AChoreographer *choreographer, AChoreographer_vsyncCallback callback, void *data)
void
Posts a callback to be run when the application should begin rendering the next frame.
AChoreographer_registerRefreshRateCallback(AChoreographer *choreographer, AChoreographer_refreshRateCallback, void *data)
void
Registers a callback to be run when the display refresh rate changes.
AChoreographer_unregisterRefreshRateCallback(AChoreographer *choreographer, AChoreographer_refreshRateCallback, void *data)
void
Unregisters a callback to be run when the display refresh rate changes, along with the data pointer previously provided when registering the callback.

Typedefs

AChoreographer

struct AChoreographer AChoreographer

Opaque type that provides access to an AChoreographer object.

A pointer can be obtained using AChoreographer_getInstance().

AChoreographerFrameCallbackData

struct AChoreographerFrameCallbackData AChoreographerFrameCallbackData

Opaque type that provides access to an AChoreographerFrameCallbackData object, which contains various methods to extract frame information.

AChoreographer_frameCallback

void(* AChoreographer_frameCallback)(long frameTimeNanos, void *data)

Prototype of the function that is called when a new frame is being rendered.

It's passed the time that the frame is being rendered as nanoseconds in the CLOCK_MONOTONIC time base, as well as the data pointer provided by the application that registered a callback. All callbacks that run as part of rendering a frame will observe the same frame time, so it should be used whenever events need to be synchronized (e.g. animations).

AChoreographer_frameCallback64

void(* AChoreographer_frameCallback64)(int64_t frameTimeNanos, void *data)

Prototype of the function that is called when a new frame is being rendered.

It's passed the time that the frame is being rendered as nanoseconds in the CLOCK_MONOTONIC time base, as well as the data pointer provided by the application that registered a callback. All callbacks that run as part of rendering a frame will observe the same frame time, so it should be used whenever events need to be synchronized (e.g. animations).

AChoreographer_refreshRateCallback

void(* AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, void *data)

Prototype of the function that is called when the display refresh rate changes.

It's passed the new vsync period in nanoseconds, as well as the data pointer provided by the application that registered a callback.

AChoreographer_vsyncCallback

void(* AChoreographer_vsyncCallback)(const AChoreographerFrameCallbackData *callbackData, void *data)

Prototype of the function that is called when a new frame is being rendered.

It is called with callbackData describing multiple frame timelines, as well as the data pointer provided by the application that registered a callback. The callbackData does not outlive the callback.

AVsyncId

int64_t AVsyncId

The identifier of a frame timeline.

Variables

instead

void Use AChoreographer_postFrameCallback64 instead

Functions

AChoreographerFrameCallbackData_getFrameTimeNanos

int64_t AChoreographerFrameCallbackData_getFrameTimeNanos(
  const AChoreographerFrameCallbackData *data
)

The time in nanoseconds at which the frame started being rendered.

Note that this time should not be used to advance animation clocks. Instead, see AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos().

Available since API level 33.

AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos

int64_t AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

Gets the time in nanoseconds at which the frame described at the given index needs to be ready by in order to be presented on time.

Available since API level 33.

Details
Parameters
index
index of a frame timeline, in ( [0, FrameTimelinesLength) ). See AChoreographerFrameCallbackData_getFrameTimelinesLength()

AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos

int64_t AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

Gets the time in nanoseconds at which the frame described at the given index is expected to be presented.

This time should be used to advance any animation clocks.

Available since API level 33.

Details
Parameters
index
index of a frame timeline, in ( [0, FrameTimelinesLength) ). See AChoreographerFrameCallbackData_getFrameTimelinesLength()

AChoreographerFrameCallbackData_getFrameTimelineVsyncId

AVsyncId AChoreographerFrameCallbackData_getFrameTimelineVsyncId(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

Gets the token used by the platform to identify the frame timeline at the given index.

q Available since API level 33.

Details
Parameters
index
index of a frame timeline, in ( [0, FrameTimelinesLength) ). See AChoreographerFrameCallbackData_getFrameTimelinesLength()

AChoreographerFrameCallbackData_getFrameTimelinesLength

size_t AChoreographerFrameCallbackData_getFrameTimelinesLength(
  const AChoreographerFrameCallbackData *data
)

The number of possible frame timelines.

Available since API level 33.

AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex

size_t AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex(
  const AChoreographerFrameCallbackData *data
)

Gets the index of the platform-preferred frame timeline.

The preferred frame timeline is the default by which the platform scheduled the app, based on the device configuration.

Available since API level 33.

AChoreographer_getInstance

AChoreographer * AChoreographer_getInstance()

Get the AChoreographer instance for the current thread.

This must be called on an ALooper thread.

Available since API level 24.

AChoreographer_postFrameCallback

void AChoreographer_postFrameCallback(
  AChoreographer *choreographer,
  AChoreographer_frameCallback callback,
  void *data
) __DEPRECATED_IN(29

Post a callback to be run when the application should begin rendering the next frame.

The data pointer provided will be passed to the callback function when it's called.

The callback will only be run for the next frame, not all subsequent frames, so to render continuously the callback should itself call AChoreographer_postFrameCallback.

Deprecated. Use AChoreographer_postFrameCallback64, which does not have the bug described above.

AChoreographer_postFrameCallback64

void AChoreographer_postFrameCallback64(
  AChoreographer *choreographer,
  AChoreographer_frameCallback64 callback,
  void *data
)

Post a callback to be run when the application should begin rendering the next frame.

The data pointer provided will be passed to the callback function when it's called.

The callback will only be run on the next frame, not all subsequent frames, so to render continuously the callback should itself call AChoreographer_postFrameCallback64.

Available since API level 29.

AChoreographer_postFrameCallbackDelayed

void AChoreographer_postFrameCallbackDelayed(
  AChoreographer *choreographer,
  AChoreographer_frameCallback callback,
  void *data,
  long delayMillis
) __DEPRECATED_IN(29

Post a callback to be run when the application should begin rendering the next frame following the specified delay.

The data pointer provided will be passed to the callback function when it's called.

The callback will only be run for the next frame after the delay, not all subsequent frames, so to render continuously the callback should itself call AChoreographer_postFrameCallbackDelayed.

Deprecated. Use AChoreographer_postFrameCallbackDelayed64, which does not have the bug described above.

AChoreographer_postFrameCallbackDelayed64

void AChoreographer_postFrameCallbackDelayed64(
  AChoreographer *choreographer,
  AChoreographer_frameCallback64 callback,
  void *data,
  uint32_t delayMillis
)

Post a callback to be run when the application should begin rendering the next frame following the specified delay.

The data pointer provided will be passed to the callback function when it's called.

The callback will only be run for the next frame after the delay, not all subsequent frames, so to render continuously the callback should itself call AChoreographer_postFrameCallbackDelayed64.

Available since API level 29.

AChoreographer_postVsyncCallback

void AChoreographer_postVsyncCallback(
  AChoreographer *choreographer,
  AChoreographer_vsyncCallback callback,
  void *data
)

Posts a callback to be run when the application should begin rendering the next frame.

The data pointer provided will be passed to the callback function when it's called.

The callback will only be run for the next frame, not all subsequent frames, so to render continuously the callback should itself call AChoreographer_postVsyncCallback.

Available since API level 33.

AChoreographer_registerRefreshRateCallback

void AChoreographer_registerRefreshRateCallback(
  AChoreographer *choreographer,
  AChoreographer_refreshRateCallback,
  void *data
)

Registers a callback to be run when the display refresh rate changes.

The data pointer provided will be passed to the callback function when it's called. The same callback may be registered multiple times, provided that a different data pointer is provided each time.

If an application registers a callback for this choreographer instance when no new callbacks were previously registered, that callback is guaranteed to be dispatched. However, if the callback and associated data pointer are unregistered prior to running the callback, then the callback may be silently dropped.

This api is thread-safe. Any thread is allowed to register a new refresh rate callback for the choreographer instance.

Note that in API level 30, this api is not guaranteed to be atomic with DisplayManager. That is, calling Display::getRefreshRate very soon after a refresh rate callback is invoked may return a stale refresh rate. If any Display properties would be required by this callback, then it is recommended to listen directly to DisplayManager.DisplayListener::onDisplayChanged events instead.

As of API level 31, this api is guaranteed to have a consistent view with DisplayManager; Display::getRefreshRate is guaranteed to not return a stale refresh rate when invoked from this callback.

Available since API level 30.

AChoreographer_unregisterRefreshRateCallback

void AChoreographer_unregisterRefreshRateCallback(
  AChoreographer *choreographer,
  AChoreographer_refreshRateCallback,
  void *data
)

Unregisters a callback to be run when the display refresh rate changes, along with the data pointer previously provided when registering the callback.

The callback is only unregistered when the data pointer matches one that was previously registered.

This api is thread-safe. Any thread is allowed to unregister an existing refresh rate callback for the choreographer instance. When a refresh rate callback and associated data pointer are unregistered, then there is a guarantee that when the unregistration completes that that callback will not be run with the data pointer passed.

Available since API level 30.