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.

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.

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.

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)
void
Deprecated: Use AChoreographer_postFrameCallback64 instead.
AChoreographer_postFrameCallback64(AChoreographer *choreographer, AChoreographer_frameCallback64 callback, void *data)
void
Post a callback to be run on the next frame.
AChoreographer_postFrameCallbackDelayed(AChoreographer *choreographer, AChoreographer_frameCallback callback, void *data, long delayMillis)
void
Deprecated: Use AChoreographer_postFrameCallbackDelayed64 instead.
AChoreographer_postFrameCallbackDelayed64(AChoreographer *choreographer, AChoreographer_frameCallback64 callback, void *data, uint32_t delayMillis)
void
Post a callback to be run on the frame following the specified delay.
AChoreographer_postVsyncCallback(AChoreographer *choreographer, AChoreographer_vsyncCallback callback, void *data)
void
Posts a callback to be run on 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.

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().

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.

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.

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.

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.

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.

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: Use AChoreographer_postFrameCallback64 instead.

AChoreographer_postFrameCallback64

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

Post a callback to be run on the next frame.

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

Available since API level 29.

AChoreographer_postFrameCallbackDelayed

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

Deprecated: Use AChoreographer_postFrameCallbackDelayed64 instead.

AChoreographer_postFrameCallbackDelayed64

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

Post a callback to be run on the frame following the specified delay.

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

Available since API level 29.

AChoreographer_postVsyncCallback

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

Posts a callback to be run on the next frame.

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

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.