blob: b0248bd0ef7fad86625e1bf6cfb64c4477b0b76a [file] [log] [blame]
Michael Wrightf5eee402015-12-07 15:26:38 -05001/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/**
18 * @addtogroup Choreographer
Rachel Leee81bf262022-08-23 14:37:59 -070019 *
20 * Choreographer coordinates the timing of frame rendering. This is the C version of the
21 * android.view.Choreographer object in Java.
22 *
23 * As of API level 33, apps can follow proper frame pacing and even choose a future frame to render.
24 * The API is used as follows:
25 * 1. The app posts an {@link AChoreographer_vsyncCallback} to Choreographer to run on the next
26 * frame.
27 * 2. The callback is called when it is the time to start the frame with an {@link
28 * AChoreographerFrameCallbackData} payload: information about multiple possible frame
29 * timelines.
30 * 3. Apps can choose a frame timeline from the {@link
31 * AChoreographerFrameCallbackData} payload, depending on the frame deadline they can meet when
32 * rendering the frame and their desired presentation time, and subsequently
33 * {@link ASurfaceTransaction_setFrameTimeline notify SurfaceFlinger}
34 * of the choice. Alternatively, for apps that do not choose a frame timeline, their frame would be
35 * presented at the earliest possible timeline.
36 * - The preferred frame timeline is the default frame
37 * timeline that the platform scheduled for the app, based on device configuration.
38 * 4. SurfaceFlinger attempts to follow the chosen frame timeline, by not applying transactions or
39 * latching buffers before the desired presentation time.
40 *
Michael Wrightf5eee402015-12-07 15:26:38 -050041 * @{
42 */
43
44/**
45 * @file choreographer.h
46 */
47
48#ifndef ANDROID_CHOREOGRAPHER_H
49#define ANDROID_CHOREOGRAPHER_H
50
Santos Cordon908d0082019-02-20 18:08:02 +000051#include <stdint.h>
Michael Wrightfb911b22016-01-26 16:05:54 -080052#include <sys/cdefs.h>
53
Michael Wrightf5eee402015-12-07 15:26:38 -050054__BEGIN_DECLS
55
56struct AChoreographer;
gfan7fed43d2021-04-06 18:50:06 -070057/**
58 * Opaque type that provides access to an AChoreographer object.
59 *
60 * A pointer can be obtained using {@link AChoreographer_getInstance()}.
61 */
Michael Wrightf5eee402015-12-07 15:26:38 -050062typedef struct AChoreographer AChoreographer;
63
Rachel Lee1fb2ddc2022-01-12 14:33:07 -080064
65/**
66 * The identifier of a frame timeline.
67 */
68typedef int64_t AVsyncId;
69
Rachel Lee4879d812021-08-25 11:50:11 -070070struct AChoreographerFrameCallbackData;
71/**
Rachel Leee81bf262022-08-23 14:37:59 -070072 * Opaque type that provides access to an AChoreographerFrameCallbackData object, which contains
73 * various methods to extract frame information.
Rachel Lee4879d812021-08-25 11:50:11 -070074 */
75typedef struct AChoreographerFrameCallbackData AChoreographerFrameCallbackData;
76
Michael Wrightf5eee402015-12-07 15:26:38 -050077/**
78 * Prototype of the function that is called when a new frame is being rendered.
79 * It's passed the time that the frame is being rendered as nanoseconds in the
80 * CLOCK_MONOTONIC time base, as well as the data pointer provided by the
81 * application that registered a callback. All callbacks that run as part of
82 * rendering a frame will observe the same frame time, so it should be used
83 * whenever events need to be synchronized (e.g. animations).
84 */
85typedef void (*AChoreographer_frameCallback)(long frameTimeNanos, void* data);
86
Santos Cordon908d0082019-02-20 18:08:02 +000087/**
88 * Prototype of the function that is called when a new frame is being rendered.
89 * It's passed the time that the frame is being rendered as nanoseconds in the
90 * CLOCK_MONOTONIC time base, as well as the data pointer provided by the
91 * application that registered a callback. All callbacks that run as part of
92 * rendering a frame will observe the same frame time, so it should be used
93 * whenever events need to be synchronized (e.g. animations).
94 */
95typedef void (*AChoreographer_frameCallback64)(int64_t frameTimeNanos, void* data);
96
Alec Mouri33682e92020-01-10 15:11:15 -080097/**
Rachel Lee4879d812021-08-25 11:50:11 -070098 * Prototype of the function that is called when a new frame is being rendered.
Rachel Leee81bf262022-08-23 14:37:59 -070099 * It is called with \c callbackData describing multiple frame timelines, as well as the \c data
100 * pointer provided by the application that registered a callback. The \c callbackData does not
101 * outlive the callback.
Rachel Lee4879d812021-08-25 11:50:11 -0700102 */
Rachel Leef4dc39f2022-02-15 18:30:59 -0800103typedef void (*AChoreographer_vsyncCallback)(
Rachel Lee4879d812021-08-25 11:50:11 -0700104 const AChoreographerFrameCallbackData* callbackData, void* data);
105
106/**
Alec Mouri33682e92020-01-10 15:11:15 -0800107 * Prototype of the function that is called when the display refresh rate
108 * changes. It's passed the new vsync period in nanoseconds, as well as the data
109 * pointer provided by the application that registered a callback.
110 */
111typedef void (*AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, void* data);
112
Michael Wrightf5eee402015-12-07 15:26:38 -0500113/**
114 * Get the AChoreographer instance for the current thread. This must be called
115 * on an ALooper thread.
Elliott Hughes3d70e532019-10-29 08:59:39 -0700116 *
117 * Available since API level 24.
Michael Wrightf5eee402015-12-07 15:26:38 -0500118 */
Elliott Hughes9db409b2018-06-18 12:28:46 -0700119AChoreographer* AChoreographer_getInstance() __INTRODUCED_IN(24);
Michael Wrightf5eee402015-12-07 15:26:38 -0500120
121/**
Dan Albert9ca6b3d2024-05-02 20:36:06 +0000122 * Post a callback to be run on the next frame. The data pointer provided will
123 * be passed to the callback function when it's called.
124 *
125 * \bug The callback receives the frame time in nanoseconds as a long. On 32-bit
126 * systems, long is 32-bit, so the frame time will roll over roughly every two
127 * seconds. If your minSdkVersion is 29 or higher, switch to
128 * AChoreographer_postFrameCallback64, which uses a 64-bit frame time for all
129 * platforms. For older OS versions, you must combine the argument with the
130 * upper bits of clock_gettime(CLOCK_MONOTONIC, ...) on 32-bit systems.
131 *
132 * \deprecated Use AChoreographer_postFrameCallback64, which does not have the
133 * bug described above.
Michael Wrightf5eee402015-12-07 15:26:38 -0500134 */
135void AChoreographer_postFrameCallback(AChoreographer* choreographer,
Alec Mouri271de042020-04-27 22:38:19 -0700136 AChoreographer_frameCallback callback, void* data)
Dan Albertc47ac842024-05-02 20:19:54 +0000137 __INTRODUCED_IN(24) __DEPRECATED_IN(29, "Use AChoreographer_postFrameCallback64 instead");
Elliott Hughes9db409b2018-06-18 12:28:46 -0700138
Michael Wrightf5eee402015-12-07 15:26:38 -0500139/**
Dan Albert9ca6b3d2024-05-02 20:36:06 +0000140 * Post a callback to be run on the frame following the specified delay. The
141 * data pointer provided will be passed to the callback function when it's
142 * called.
143 *
144 * \bug The callback receives the frame time in nanoseconds as a long. On 32-bit
145 * systems, long is 32-bit, so the frame time will roll over roughly every two
146 * seconds. If your minSdkVersion is 29 or higher, switch to
147 * AChoreographer_postFrameCallbackDelayed64, which uses a 64-bit frame time for
148 * all platforms. For older OS versions, you must combine the argument with the
149 * upper bits of clock_gettime(CLOCK_MONOTONIC, ...) on 32-bit systems.
150 *
151 * \deprecated Use AChoreographer_postFrameCallbackDelayed64, which does not
152 * have the bug described above.
Michael Wrightf5eee402015-12-07 15:26:38 -0500153 */
154void AChoreographer_postFrameCallbackDelayed(AChoreographer* choreographer,
Alec Mouri271de042020-04-27 22:38:19 -0700155 AChoreographer_frameCallback callback, void* data,
156 long delayMillis) __INTRODUCED_IN(24)
Dan Albertc47ac842024-05-02 20:19:54 +0000157 __DEPRECATED_IN(29, "Use AChoreographer_postFrameCallbackDelayed64 instead");
Dan Albert494ed552016-09-23 15:57:45 -0700158
Santos Cordon908d0082019-02-20 18:08:02 +0000159/**
Rachel Leee81bf262022-08-23 14:37:59 -0700160 * Post a callback to be run on the next frame. The data pointer provided will
Santos Cordon908d0082019-02-20 18:08:02 +0000161 * be passed to the callback function when it's called.
Elliott Hughes3d70e532019-10-29 08:59:39 -0700162 *
163 * Available since API level 29.
Santos Cordon908d0082019-02-20 18:08:02 +0000164 */
Dillon Cower20e67fa2019-07-30 15:39:54 -0700165void AChoreographer_postFrameCallback64(AChoreographer* choreographer,
Alec Mouri271de042020-04-27 22:38:19 -0700166 AChoreographer_frameCallback64 callback, void* data)
167 __INTRODUCED_IN(29);
Santos Cordon908d0082019-02-20 18:08:02 +0000168
169/**
170 * Post a callback to be run on the frame following the specified delay. The
171 * data pointer provided will be passed to the callback function when it's
172 * called.
Elliott Hughes3d70e532019-10-29 08:59:39 -0700173 *
174 * Available since API level 29.
Santos Cordon908d0082019-02-20 18:08:02 +0000175 */
176void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer,
Alec Mouri271de042020-04-27 22:38:19 -0700177 AChoreographer_frameCallback64 callback, void* data,
178 uint32_t delayMillis) __INTRODUCED_IN(29);
Santos Cordon908d0082019-02-20 18:08:02 +0000179
Alec Mouri33682e92020-01-10 15:11:15 -0800180/**
Rachel Leee81bf262022-08-23 14:37:59 -0700181 * Posts a callback to be run on the next frame. The data pointer provided will
Rachel Lee4879d812021-08-25 11:50:11 -0700182 * be passed to the callback function when it's called.
Rachel Leee81bf262022-08-23 14:37:59 -0700183 *
184 * Available since API level 33.
Rachel Lee4879d812021-08-25 11:50:11 -0700185 */
Rachel Leef4dc39f2022-02-15 18:30:59 -0800186void AChoreographer_postVsyncCallback(AChoreographer* choreographer,
187 AChoreographer_vsyncCallback callback, void* data)
Rachel Lee4879d812021-08-25 11:50:11 -0700188 __INTRODUCED_IN(33);
189
190/**
Alec Mouri33682e92020-01-10 15:11:15 -0800191 * Registers a callback to be run when the display refresh rate changes. The
192 * data pointer provided will be passed to the callback function when it's
193 * called. The same callback may be registered multiple times, provided that a
194 * different data pointer is provided each time.
195 *
196 * If an application registers a callback for this choreographer instance when
197 * no new callbacks were previously registered, that callback is guaranteed to
198 * be dispatched. However, if the callback and associated data pointer are
199 * unregistered prior to running the callback, then the callback may be silently
200 * dropped.
201 *
202 * This api is thread-safe. Any thread is allowed to register a new refresh
203 * rate callback for the choreographer instance.
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700204 *
Alec Mouri4a331652020-07-20 22:05:24 +0000205 * Note that in API level 30, this api is not guaranteed to be atomic with
206 * DisplayManager. That is, calling Display#getRefreshRate very soon after
207 * a refresh rate callback is invoked may return a stale refresh rate. If any
208 * Display properties would be required by this callback, then it is recommended
209 * to listen directly to DisplayManager.DisplayListener#onDisplayChanged events
210 * instead.
211 *
Alec Mouri7015fa92021-02-11 19:31:44 +0000212 * As of API level 31, this api is guaranteed to have a consistent view with DisplayManager;
213 * Display#getRefreshRate is guaranteed to not return a stale refresh rate when invoked from this
214 * callback.
215 *
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700216 * Available since API level 30.
Alec Mouri33682e92020-01-10 15:11:15 -0800217 */
218void AChoreographer_registerRefreshRateCallback(AChoreographer* choreographer,
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700219 AChoreographer_refreshRateCallback, void* data)
220 __INTRODUCED_IN(30);
Alec Mouri33682e92020-01-10 15:11:15 -0800221
222/**
223 * Unregisters a callback to be run when the display refresh rate changes, along
224 * with the data pointer previously provided when registering the callback. The
225 * callback is only unregistered when the data pointer matches one that was
226 * previously registered.
227 *
228 * This api is thread-safe. Any thread is allowed to unregister an existing
229 * refresh rate callback for the choreographer instance. When a refresh rate
230 * callback and associated data pointer are unregistered, then there is a
231 * guarantee that when the unregistration completes that that callback will not
232 * be run with the data pointer passed.
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700233 *
234 * Available since API level 30.
Alec Mouri33682e92020-01-10 15:11:15 -0800235 */
236void AChoreographer_unregisterRefreshRateCallback(AChoreographer* choreographer,
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700237 AChoreographer_refreshRateCallback, void* data)
238 __INTRODUCED_IN(30);
Alec Mouri33682e92020-01-10 15:11:15 -0800239
Rachel Lee4879d812021-08-25 11:50:11 -0700240/**
Rachel Leee81bf262022-08-23 14:37:59 -0700241 * The time in nanoseconds at which the frame started being rendered.
242 *
243 * Note that this time should \b not be used to advance animation clocks.
244 * Instead, see AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos().
Alec Mouri5a100fa2023-02-24 00:45:29 +0000245 *
246 * Available since API level 33.
Rachel Lee4879d812021-08-25 11:50:11 -0700247 */
248int64_t AChoreographerFrameCallbackData_getFrameTimeNanos(
249 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33);
250
251/**
252 * The number of possible frame timelines.
Alec Mouri5a100fa2023-02-24 00:45:29 +0000253 *
254 * Available since API level 33.
Rachel Lee4879d812021-08-25 11:50:11 -0700255 */
256size_t AChoreographerFrameCallbackData_getFrameTimelinesLength(
257 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33);
258
259/**
Rachel Leee81bf262022-08-23 14:37:59 -0700260 * Gets the index of the platform-preferred frame timeline.
261 * The preferred frame timeline is the default
262 * by which the platform scheduled the app, based on the device configuration.
Alec Mouri5a100fa2023-02-24 00:45:29 +0000263 *
264 * Available since API level 33.
Rachel Lee4879d812021-08-25 11:50:11 -0700265 */
266size_t AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex(
267 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33);
268
269/**
Rachel Leee81bf262022-08-23 14:37:59 -0700270 * Gets the token used by the platform to identify the frame timeline at the given \c index.
Alec Mouri5a100fa2023-02-24 00:45:29 +0000271 * q
272 * Available since API level 33.
Rachel Leee81bf262022-08-23 14:37:59 -0700273 *
274 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See
275 * AChoreographerFrameCallbackData_getFrameTimelinesLength()
Alec Mouri5a100fa2023-02-24 00:45:29 +0000276 *
Rachel Lee4879d812021-08-25 11:50:11 -0700277 */
Rachel Lee1fb2ddc2022-01-12 14:33:07 -0800278AVsyncId AChoreographerFrameCallbackData_getFrameTimelineVsyncId(
Rachel Lee4879d812021-08-25 11:50:11 -0700279 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33);
280
281/**
Rachel Leee81bf262022-08-23 14:37:59 -0700282 * Gets the time in nanoseconds at which the frame described at the given \c index is expected to
283 * be presented. This time should be used to advance any animation clocks.
284 *
Alec Mouri5a100fa2023-02-24 00:45:29 +0000285 * Available since API level 33.
286 *
Rachel Leee81bf262022-08-23 14:37:59 -0700287 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See
288 * AChoreographerFrameCallbackData_getFrameTimelinesLength()
Rachel Lee4879d812021-08-25 11:50:11 -0700289 */
Rachel Leef4dc39f2022-02-15 18:30:59 -0800290int64_t AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(
Rachel Lee4879d812021-08-25 11:50:11 -0700291 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33);
292
293/**
Rachel Leee81bf262022-08-23 14:37:59 -0700294 * Gets the time in nanoseconds at which the frame described at the given \c index needs to be
295 * ready by in order to be presented on time.
296 *
Alec Mouri5a100fa2023-02-24 00:45:29 +0000297 * Available since API level 33.
298 *
Rachel Leee81bf262022-08-23 14:37:59 -0700299 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See
300 * AChoreographerFrameCallbackData_getFrameTimelinesLength()
Rachel Lee4879d812021-08-25 11:50:11 -0700301 */
Rachel Lee2825fa22022-01-12 17:35:16 -0800302int64_t AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos(
Rachel Lee4879d812021-08-25 11:50:11 -0700303 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33);
304
Michael Wrightf5eee402015-12-07 15:26:38 -0500305__END_DECLS
306
307#endif // ANDROID_CHOREOGRAPHER_H
308
309/** @} */