Choreographer

Choreographer 协调帧渲染的时机。

摘要

这是 Java 中 android.view.Choreographer 对象的 C 版本。如果您不使用 Choreographer 来控制渲染循环的步调，您的渲染速度可能会快于显示器的刷新速度，从而增加帧提交和呈现之间的延迟。

输入事件保证在调用帧回调之前处理，并且不会并发运行。输入和传感器事件不应在 Choregrapher 回调中处理。

帧回调也是运行任何逐帧状态更新逻辑的合适位置。例如，在游戏中，帧回调应负责更新物理、AI、游戏状态以及渲染帧等内容。输入和传感器应通过注册到 AInputQueue 和 ASensorManager 的回调单独处理。

从 API 级别 33 开始，应用可以遵循适当的帧步调，甚至可以选择未来的帧进行渲染。API 的使用方式如下：

应用将一个 AChoreographer_vsyncCallback 发布到 Choreographer，以便在下一帧运行。
当需要开始帧时，会调用该回调，并带有一个 AChoreographerFrameCallbackData 有效载荷：其中包含有关多个可能的帧时间线的信息。
应用可以从 AChoreographerFrameCallbackData 有效载荷中选择一个帧时间线，具体取决于它们在渲染帧时可以满足的帧截止时间以及所需的呈现时间，然后通知 SurfaceFlinger 所做的选择。另外，对于未选择帧时间线的应用，其帧将在最早可能的时间线呈现。
- 首选帧时间线是平台根据设备配置为应用调度的默认帧时间线。
SurfaceFlinger 尝试遵循选定的帧时间线，方法是在所需呈现时间之前不应用事务或锁定缓冲区。

在较旧的设备上，可以使用 AChoreographer_postFrameCallback64 或 AChoreographer_postFrameCallback，但效果较差。它们无法用于精确规划您的渲染时间线，但会限制速率以避免过载显示流水线和增加帧延迟。

类型定义
`AChoreographer`	typedef `struct AChoreographer` 提供对 AChoreographer 对象访问的不透明类型。
`AChoreographerFrameCallbackData`	typedef `struct AChoreographerFrameCallbackData` 提供对 AChoreographerFrameCallbackData 对象访问的不透明类型，该对象包含各种提取帧信息的方法。
`AChoreographer_frameCallback)(long frameTimeNanos, void *data)`	typedef `void(*` 渲染新帧时调用的函数原型。
`AChoreographer_frameCallback64)(int64_t frameTimeNanos, void *data)`	typedef `void(*` 渲染新帧时调用的函数原型。
`AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, void *data)`	typedef `void(*` 显示刷新率更改时调用的函数原型。
`AChoreographer_vsyncCallback)(const AChoreographerFrameCallbackData callbackData, void data)`	typedef `void(*` 渲染新帧时调用的函数原型。
`AVsyncId`	typedef `int64_t` 帧时间线的标识符。

变量
`替代`	`void 使用 AChoreographer_postFrameCallback64`

函数
`AChoreographerFrameCallbackData_getFrameTimeNanos(const AChoreographerFrameCallbackData *data)`	`int64_t` 帧开始渲染的时间，单位为纳秒。
`AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos(const AChoreographerFrameCallbackData *data, size_t index)`	`int64_t` 获取给定 `index` 处描述的帧需要准备就绪的时间（纳秒），以便按时呈现。
`AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(const AChoreographerFrameCallbackData *data, size_t index)`	`int64_t` 获取给定 `index` 处描述的帧预计呈现的时间，单位为纳秒。
`AChoreographerFrameCallbackData_getFrameTimelineVsyncId(const AChoreographerFrameCallbackData *data, size_t index)`	`AVsyncId` 获取平台用于标识给定 `index` 处帧时间线的令牌。
`AChoreographerFrameCallbackData_getFrameTimelinesLength(const AChoreographerFrameCallbackData *data)`	`size_t` 可能的帧时间线数量。
`AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex(const AChoreographerFrameCallbackData *data)`	`size_t` 获取平台首选帧时间线的索引。
`AChoreographer_getInstance()`	`AChoreographer *` 获取当前线程的 AChoreographer 实例。
`AChoreographer_postFrameCallback(AChoreographer choreographer, AChoreographer_frameCallback callback, void data) __DEPRECATED_IN(29`	`void` 已弃用。使用 AChoreographer_postFrameCallback64，它没有上述 bug。发布一个回调，以便在应用应开始渲染下一帧时运行。
`AChoreographer_postFrameCallback64(AChoreographer choreographer, AChoreographer_frameCallback64 callback, void data)`	`void` 发布一个回调，以便在应用应开始渲染下一帧时运行。
`AChoreographer_postFrameCallbackDelayed(AChoreographer choreographer, AChoreographer_frameCallback callback, void data, long delayMillis) __DEPRECATED_IN(29`	`void` 已弃用。使用 AChoreographer_postFrameCallbackDelayed64，它没有上述 bug。发布一个回调，以便在应用应在指定延迟后开始渲染下一帧时运行。
`AChoreographer_postFrameCallbackDelayed64(AChoreographer choreographer, AChoreographer_frameCallback64 callback, void data, uint32_t delayMillis)`	`void` 发布一个回调，以便在应用应在指定延迟后开始渲染下一帧时运行。
`AChoreographer_postVsyncCallback(AChoreographer choreographer, AChoreographer_vsyncCallback callback, void data)`	`void` 发布一个回调，以便在应用应开始渲染下一帧时运行。
`AChoreographer_registerRefreshRateCallback(AChoreographer choreographer, AChoreographer_refreshRateCallback, void data)`	`void` 注册一个回调，以便在显示刷新率更改时运行。
`AChoreographer_unregisterRefreshRateCallback(AChoreographer choreographer, AChoreographer_refreshRateCallback, void data)`	`void` 注销一个回调，以便在显示刷新率更改时运行，同时注销注册回调时先前提供的数据指针。

类型定义

AChoreographer

在 android/choreographer.h 中声明

struct AChoreographer AChoreographer

提供对 AChoreographer 对象访问的不透明类型。

可以使用 AChoreographer_getInstance() 获取指针。

AChoreographerFrameCallbackData

在 android/choreographer.h 中声明

struct AChoreographerFrameCallbackData AChoreographerFrameCallbackData

提供对 AChoreographerFrameCallbackData 对象访问的不透明类型，该对象包含各种提取帧信息的方法。

AChoreographer_frameCallback

在 android/choreographer.h 中声明

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

渲染新帧时调用的函数原型。

它以 CLOCK_MONOTONIC 时间基准的纳秒为单位传递帧正在渲染的时间，以及应用注册回调时提供的数据指针。所有作为渲染帧一部分运行的回调都将观察到相同的帧时间，因此每当事件需要同步时（例如动画），都应使用它。

AChoreographer_frameCallback64

在 android/choreographer.h 中声明

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

渲染新帧时调用的函数原型。

AChoreographer_refreshRateCallback

在 android/choreographer.h 中声明

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

显示刷新率更改时调用的函数原型。

它以纳秒为单位传递新的 vsync 周期，以及应用注册回调时提供的数据指针。

AChoreographer_vsyncCallback

在 android/choreographer.h 中声明

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

渲染新帧时调用的函数原型。

调用时会带有一个描述多个帧时间线的 callbackData，以及应用注册回调时提供的 data 指针。 callbackData 在回调结束后即失效。

AVsyncId

在 android/choreographer.h 中声明

int64_t AVsyncId

帧时间线的标识符。

变量

替代

在 android/choreographer.h 中声明

void Use AChoreographer_postFrameCallback64 instead

函数

AChoreographerFrameCallbackData_getFrameTimeNanos

在 android/choreographer.h 中声明

int64_t AChoreographerFrameCallbackData_getFrameTimeNanos(
  const AChoreographerFrameCallbackData *data
)

帧开始渲染的时间，单位为纳秒。

请注意，不应使用此时间来推进动画时钟。请参阅 AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos()。

从 API 级别 33 开始可用。

AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos

在 android/choreographer.h 中声明

int64_t AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

获取给定 index 处描述的帧需要准备就绪的时间（纳秒），以便按时呈现。

从 API 级别 33 开始可用。

详细信息

参数

index

帧时间线的索引，范围为 ( [0, FrameTimelinesLength) )。请参阅 AChoreographerFrameCallbackData_getFrameTimelinesLength()

AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos

在 android/choreographer.h 中声明

int64_t AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

获取给定 index 处描述的帧预计呈现的时间，单位为纳秒。

应使用此时间来推进任何动画时钟。

从 API 级别 33 开始可用。

详细信息

参数

index

帧时间线的索引，范围为 ( [0, FrameTimelinesLength) )。请参阅 AChoreographerFrameCallbackData_getFrameTimelinesLength()

AChoreographerFrameCallbackData_getFrameTimelineVsyncId

在 android/choreographer.h 中声明

AVsyncId AChoreographerFrameCallbackData_getFrameTimelineVsyncId(
  const AChoreographerFrameCallbackData *data,
  size_t index
)

获取平台用于标识给定 index 处帧时间线的令牌。

从 API 级别 33 开始可用。

详细信息

参数

index

帧时间线的索引，范围为 ( [0, FrameTimelinesLength) )。请参阅 AChoreographerFrameCallbackData_getFrameTimelinesLength()

AChoreographerFrameCallbackData_getFrameTimelinesLength

在 android/choreographer.h 中声明

size_t AChoreographerFrameCallbackData_getFrameTimelinesLength(
  const AChoreographerFrameCallbackData *data
)

可能的帧时间线数量。

从 API 级别 33 开始可用。

AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex

在 android/choreographer.h 中声明

size_t AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex(
  const AChoreographerFrameCallbackData *data
)

获取平台首选帧时间线的索引。

首选帧时间线是平台根据设备配置为应用调度的默认时间线。

从 API 级别 33 开始可用。

AChoreographer_getInstance

在 android/choreographer.h 中声明

AChoreographer * AChoreographer_getInstance()

获取当前线程的 AChoreographer 实例。

此函数必须在 ALooper 线程上调用。

从 API 级别 24 开始可用。

AChoreographer_postFrameCallback

在 android/choreographer.h 中声明

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

发布一个回调，以便在应用应开始渲染下一帧时运行。

提供的数据指针将在调用回调函数时传递给它。

回调仅在下一帧运行，而不是所有后续帧，因此要连续渲染，回调本身应调用 AChoreographer_postFrameCallback。

已弃用。 使用 AChoreographer_postFrameCallback64，它没有上述 bug。

AChoreographer_postFrameCallback64

在 android/choreographer.h 中声明

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

发布一个回调，以便在应用应开始渲染下一帧时运行。

提供的数据指针将在调用回调函数时传递给它。

回调仅在下一帧运行，而不是所有后续帧，因此要连续渲染，回调本身应调用 AChoreographer_postFrameCallback64。

从 API 级别 29 开始可用。

AChoreographer_postFrameCallbackDelayed

在 android/choreographer.h 中声明

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

发布一个回调，以便在应用应在指定延迟后开始渲染下一帧时运行。

提供的数据指针将在调用回调函数时传递给它。

回调仅在延迟后的下一帧运行，而不是所有后续帧，因此要连续渲染，回调本身应调用 AChoreographer_postFrameCallbackDelayed。

已弃用。 使用 AChoreographer_postFrameCallbackDelayed64，它没有上述 bug。

AChoreographer_postFrameCallbackDelayed64

在 android/choreographer.h 中声明

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

发布一个回调，以便在应用应在指定延迟后开始渲染下一帧时运行。

提供的数据指针将在调用回调函数时传递给它。

回调仅在延迟后的下一帧运行，而不是所有后续帧，因此要连续渲染，回调本身应调用 AChoreographer_postFrameCallbackDelayed64。

从 API 级别 29 开始可用。

AChoreographer_postVsyncCallback

在 android/choreographer.h 中声明

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

发布一个回调，以便在应用应开始渲染下一帧时运行。

提供的数据指针将在调用回调函数时传递给它。

回调仅在下一帧运行，而不是所有后续帧，因此要连续渲染，回调本身应调用 AChoreographer_postVsyncCallback。

从 API 级别 33 开始可用。

AChoreographer_registerRefreshRateCallback

在 android/choreographer.h 中声明

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

注册一个回调，以便在显示刷新率更改时运行。

提供的数据指针将在调用回调函数时传递给它。同一个回调可以多次注册，前提是每次提供不同的数据指针。

如果应用在此 Choreographer 实例先前未注册任何新回调时注册了一个回调，则保证该回调会被调度。但是，如果在运行回调之前注销了该回调及其关联的数据指针，则该回调可能会被默默丢弃。

此 API 是线程安全的。任何线程都可以为 Choreographer 实例注册新的刷新率回调。

请注意，在 API 级别 30 中，此 API 不保证与 DisplayManager 原子。也就是说，在调用刷新率回调后立即调用 Display::getRefreshRate 可能会返回过时的刷新率。如果此回调需要任何 Display 属性，则建议直接监听 DisplayManager.DisplayListener::onDisplayChanged 事件。

从 API 级别 31 开始，此 API 保证与 DisplayManager 具有一致的视图；从该回调调用 Display::getRefreshRate 保证不会返回过时的刷新率。

从 API 级别 30 开始可用。

AChoreographer_unregisterRefreshRateCallback

在 android/choreographer.h 中声明

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

注销一个回调，以便在显示刷新率更改时运行，同时注销注册回调时先前提供的数据指针。

仅当数据指针与先前注册的指针匹配时，回调才会被注销。

此 API 是线程安全的。任何线程都可以为 Choreographer 实例注销现有的刷新率回调。当注销刷新率回调及其关联的数据指针时，保证在注销完成后不会使用传递的数据指针运行该回调。

从 API 级别 30 开始可用。