Stay organized with collections Save and categorize content based on your preferences.

Choreographer

#include <choreographer.h>

Summary

Typedefs

AChoreographer typedef
Opaque type that provides access to an AChoreographer object.
AChoreographerFrameCallbackData typedef
Opaque type that provides access to an AChoreographerFrameCallbackData object.
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 when the frame started being rendered.
AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos(const AChoreographerFrameCallbackData *data, size_t index)
int64_t
The time in nanoseconds which the frame at given index needs to be ready by.
AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(const AChoreographerFrameCallbackData *data, size_t index)
int64_t
The time in nanoseconds which the frame at given index is expected to be presented.
AChoreographerFrameCallbackData_getFrameTimelineVsyncId(const AChoreographerFrameCallbackData *data, size_t index)
The vsync ID token used to map Choreographer data.
AChoreographerFrameCallbackData_getFrameTimelinesLength(const AChoreographerFrameCallbackData *data)
size_t
The number of possible frame timelines.
AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex(const AChoreographerFrameCallbackData *data)
size_t
Get index of the platform-preferred FrameTimeline.
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
Power 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 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.

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's passed the frame data that should not outlive the callback, as well as the data pointer provided by the application that registered a 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 when the frame started being rendered.

AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos

int64_t AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

The time in nanoseconds which the frame at given index needs to be ready by.

AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos

int64_t AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

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

AChoreographerFrameCallbackData_getFrameTimelineVsyncId

AVsyncId AChoreographerFrameCallbackData_getFrameTimelineVsyncId(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

The vsync ID token used to map Choreographer data.

AChoreographerFrameCallbackData_getFrameTimelinesLength

size_t AChoreographerFrameCallbackData_getFrameTimelinesLength(
  const AChoreographerFrameCallbackData *data
)

The number of possible frame timelines.

AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex

size_t AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex(
  const AChoreographerFrameCallbackData *data
)

Get index of the platform-preferred FrameTimeline.

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
)

Power 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 run on the next frame.

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

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.