1 /* 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 19 * 20 * Choreographer coordinates the timing of frame rendering. This is the C 21 * version of the android.view.Choreographer object in Java. If you do not use 22 * Choreographer to pace your render loop, you may render too quickly for the 23 * display, increasing latency between frame submission and presentation. 24 * 25 * Input events are guaranteed to be processed before the frame callback is 26 * called, and will not be run concurrently. Input and sensor events should not 27 * be handled in the Choregrapher callback. 28 * 29 * The frame callback is also the appropriate place to run any per-frame state 30 * update logic. For example, in a game, the frame callback should be 31 * responsible for updating things like physics, AI, game state, and rendering 32 * the frame. Input and sensors should be handled separately via callbacks 33 * registered with AInputQueue and ASensorManager. 34 * 35 * As of API level 33, apps can follow proper frame pacing and even choose a future frame to render. 36 * The API is used as follows: 37 * 1. The app posts an {@link AChoreographer_vsyncCallback} to Choreographer to run on the next 38 * frame. 39 * 2. The callback is called when it is the time to start the frame with an {@link 40 * AChoreographerFrameCallbackData} payload: information about multiple possible frame 41 * timelines. 42 * 3. Apps can choose a frame timeline from the {@link 43 * AChoreographerFrameCallbackData} payload, depending on the frame deadline they can meet when 44 * rendering the frame and their desired presentation time, and subsequently 45 * {@link ASurfaceTransaction_setFrameTimeline notify SurfaceFlinger} 46 * of the choice. Alternatively, for apps that do not choose a frame timeline, their frame would be 47 * presented at the earliest possible timeline. 48 * - The preferred frame timeline is the default frame 49 * timeline that the platform scheduled for the app, based on device configuration. 50 * 4. SurfaceFlinger attempts to follow the chosen frame timeline, by not applying transactions or 51 * latching buffers before the desired presentation time. 52 * 53 * On older devices, AChoreographer_postFrameCallback64 or 54 * AChoreographer_postFrameCallback can be used to lesser effect. They cannot be 55 * used to precisely plan your render timeline, but will rate limit to avoid 56 * overloading the display pipeline and increasing frame latency. 57 * 58 * @{ 59 */ 60 61 /** 62 * @file choreographer.h 63 */ 64 65 #ifndef ANDROID_CHOREOGRAPHER_H 66 #define ANDROID_CHOREOGRAPHER_H 67 68 #include <stddef.h> 69 #include <stdint.h> 70 #include <sys/cdefs.h> 71 72 // This file may also be built on glibc or on Windows/MacOS libc's, so no-op 73 // and deprecated definitions are provided. 74 #if !defined(__INTRODUCED_IN) 75 #define __INTRODUCED_IN(__api_level) /* nothing */ 76 #endif 77 #if !defined(__DEPRECATED_IN) 78 #define __DEPRECATED_IN(__api_level, ...) __attribute__((__deprecated__)) 79 #endif 80 81 __BEGIN_DECLS 82 83 struct AChoreographer; 84 /** 85 * Opaque type that provides access to an AChoreographer object. 86 * 87 * A pointer can be obtained using {@link AChoreographer_getInstance()}. 88 */ 89 typedef struct AChoreographer AChoreographer; 90 91 92 /** 93 * The identifier of a frame timeline. 94 */ 95 typedef int64_t AVsyncId; 96 97 struct AChoreographerFrameCallbackData; 98 /** 99 * Opaque type that provides access to an AChoreographerFrameCallbackData object, which contains 100 * various methods to extract frame information. 101 */ 102 typedef struct AChoreographerFrameCallbackData AChoreographerFrameCallbackData; 103 104 /** 105 * Prototype of the function that is called when a new frame is being rendered. 106 * It's passed the time that the frame is being rendered as nanoseconds in the 107 * CLOCK_MONOTONIC time base, as well as the data pointer provided by the 108 * application that registered a callback. All callbacks that run as part of 109 * rendering a frame will observe the same frame time, so it should be used 110 * whenever events need to be synchronized (e.g. animations). 111 */ 112 typedef void (*AChoreographer_frameCallback)(long frameTimeNanos, void* data); 113 114 /** 115 * Prototype of the function that is called when a new frame is being rendered. 116 * It's passed the time that the frame is being rendered as nanoseconds in the 117 * CLOCK_MONOTONIC time base, as well as the data pointer provided by the 118 * application that registered a callback. All callbacks that run as part of 119 * rendering a frame will observe the same frame time, so it should be used 120 * whenever events need to be synchronized (e.g. animations). 121 */ 122 typedef void (*AChoreographer_frameCallback64)(int64_t frameTimeNanos, void* data); 123 124 /** 125 * Prototype of the function that is called when a new frame is being rendered. 126 * It is called with \c callbackData describing multiple frame timelines, as well as the \c data 127 * pointer provided by the application that registered a callback. The \c callbackData does not 128 * outlive the callback. 129 */ 130 typedef void (*AChoreographer_vsyncCallback)( 131 const AChoreographerFrameCallbackData* callbackData, void* data); 132 133 /** 134 * Prototype of the function that is called when the display refresh rate 135 * changes. It's passed the new vsync period in nanoseconds, as well as the data 136 * pointer provided by the application that registered a callback. 137 */ 138 typedef void (*AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, void* data); 139 140 /** 141 * Get the AChoreographer instance for the current thread. This must be called 142 * on an ALooper thread. 143 * 144 * Available since API level 24. 145 */ 146 AChoreographer* AChoreographer_getInstance() __INTRODUCED_IN(24); 147 148 /** 149 * Post a callback to be run when the application should begin rendering the 150 * next frame. The data pointer provided will be passed to the callback function 151 * when it's called. 152 * 153 * The callback will only be run for the next frame, not all subsequent frames, 154 * so to render continuously the callback should itself call 155 * AChoreographer_postFrameCallback. 156 * 157 * \bug The callback receives the frame time in nanoseconds as a long. On 32-bit 158 * systems, long is 32-bit, so the frame time will roll over roughly every two 159 * seconds. If your minSdkVersion is 29 or higher, switch to 160 * AChoreographer_postFrameCallback64, which uses a 64-bit frame time for all 161 * platforms. For older OS versions, you must combine the argument with the 162 * upper bits of clock_gettime(CLOCK_MONOTONIC, ...) on 32-bit systems. 163 * 164 * \deprecated Use AChoreographer_postFrameCallback64, which does not have the 165 * bug described above. 166 */ 167 void AChoreographer_postFrameCallback(AChoreographer* choreographer, 168 AChoreographer_frameCallback callback, void* data) 169 __INTRODUCED_IN(24) __DEPRECATED_IN(29, "Use AChoreographer_postFrameCallback64 instead"); 170 171 /** 172 * Post a callback to be run when the application should begin rendering the 173 * next frame following the specified delay. The data pointer provided will be 174 * passed to the callback function when it's called. 175 * 176 * The callback will only be run for the next frame after the delay, not all 177 * subsequent frames, so to render continuously the callback should itself call 178 * AChoreographer_postFrameCallbackDelayed. 179 * 180 * \bug The callback receives the frame time in nanoseconds as a long. On 32-bit 181 * systems, long is 32-bit, so the frame time will roll over roughly every two 182 * seconds. If your minSdkVersion is 29 or higher, switch to 183 * AChoreographer_postFrameCallbackDelayed64, which uses a 64-bit frame time for 184 * all platforms. For older OS versions, you must combine the argument with the 185 * upper bits of clock_gettime(CLOCK_MONOTONIC, ...) on 32-bit systems. 186 * 187 * \deprecated Use AChoreographer_postFrameCallbackDelayed64, which does not 188 * have the bug described above. 189 */ 190 void AChoreographer_postFrameCallbackDelayed(AChoreographer* choreographer, 191 AChoreographer_frameCallback callback, void* data, 192 long delayMillis) __INTRODUCED_IN(24) 193 __DEPRECATED_IN(29, "Use AChoreographer_postFrameCallbackDelayed64 instead"); 194 195 /** 196 * Post a callback to be run when the application should begin rendering the 197 * next frame. The data pointer provided will be passed to the callback function 198 * when it's called. 199 * 200 * The callback will only be run on the next frame, not all subsequent frames, 201 * so to render continuously the callback should itself call 202 * AChoreographer_postFrameCallback64. 203 * 204 * Available since API level 29. 205 */ 206 void AChoreographer_postFrameCallback64(AChoreographer* choreographer, 207 AChoreographer_frameCallback64 callback, void* data) 208 __INTRODUCED_IN(29); 209 210 /** 211 * Post a callback to be run when the application should begin rendering the 212 * next frame following the specified delay. The data pointer provided will be 213 * passed to the callback function when it's called. 214 * 215 * The callback will only be run for the next frame after the delay, not all 216 * subsequent frames, so to render continuously the callback should itself call 217 * AChoreographer_postFrameCallbackDelayed64. 218 * 219 * Available since API level 29. 220 */ 221 void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer, 222 AChoreographer_frameCallback64 callback, void* data, 223 uint32_t delayMillis) __INTRODUCED_IN(29); 224 225 /** 226 * Posts a callback to be run when the application should begin rendering the 227 * next frame. The data pointer provided will be passed to the callback function 228 * when it's called. 229 * 230 * The callback will only be run for the next frame, not all subsequent frames, 231 * so to render continuously the callback should itself call 232 * AChoreographer_postVsyncCallback. 233 * 234 * Available since API level 33. 235 */ 236 void AChoreographer_postVsyncCallback(AChoreographer* choreographer, 237 AChoreographer_vsyncCallback callback, void* data) 238 __INTRODUCED_IN(33); 239 240 /** 241 * Registers a callback to be run when the display refresh rate changes. The 242 * data pointer provided will be passed to the callback function when it's 243 * called. The same callback may be registered multiple times, provided that a 244 * different data pointer is provided each time. 245 * 246 * If an application registers a callback for this choreographer instance when 247 * no new callbacks were previously registered, that callback is guaranteed to 248 * be dispatched. However, if the callback and associated data pointer are 249 * unregistered prior to running the callback, then the callback may be silently 250 * dropped. 251 * 252 * This api is thread-safe. Any thread is allowed to register a new refresh 253 * rate callback for the choreographer instance. 254 * 255 * Note that in API level 30, this api is not guaranteed to be atomic with 256 * DisplayManager. That is, calling Display#getRefreshRate very soon after 257 * a refresh rate callback is invoked may return a stale refresh rate. If any 258 * Display properties would be required by this callback, then it is recommended 259 * to listen directly to DisplayManager.DisplayListener#onDisplayChanged events 260 * instead. 261 * 262 * As of API level 31, this api is guaranteed to have a consistent view with DisplayManager; 263 * Display#getRefreshRate is guaranteed to not return a stale refresh rate when invoked from this 264 * callback. 265 * 266 * Available since API level 30. 267 */ 268 void AChoreographer_registerRefreshRateCallback(AChoreographer* choreographer, 269 AChoreographer_refreshRateCallback, void* data) 270 __INTRODUCED_IN(30); 271 272 /** 273 * Unregisters a callback to be run when the display refresh rate changes, along 274 * with the data pointer previously provided when registering the callback. The 275 * callback is only unregistered when the data pointer matches one that was 276 * previously registered. 277 * 278 * This api is thread-safe. Any thread is allowed to unregister an existing 279 * refresh rate callback for the choreographer instance. When a refresh rate 280 * callback and associated data pointer are unregistered, then there is a 281 * guarantee that when the unregistration completes that that callback will not 282 * be run with the data pointer passed. 283 * 284 * Available since API level 30. 285 */ 286 void AChoreographer_unregisterRefreshRateCallback(AChoreographer* choreographer, 287 AChoreographer_refreshRateCallback, void* data) 288 __INTRODUCED_IN(30); 289 290 /** 291 * The time in nanoseconds at which the frame started being rendered. 292 * 293 * Note that this time should \b not be used to advance animation clocks. 294 * Instead, see AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(). 295 * 296 * Available since API level 33. 297 */ 298 int64_t AChoreographerFrameCallbackData_getFrameTimeNanos( 299 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); 300 301 /** 302 * The number of possible frame timelines. 303 * 304 * Available since API level 33. 305 */ 306 size_t AChoreographerFrameCallbackData_getFrameTimelinesLength( 307 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); 308 309 /** 310 * Gets the index of the platform-preferred frame timeline. 311 * The preferred frame timeline is the default 312 * by which the platform scheduled the app, based on the device configuration. 313 * 314 * Available since API level 33. 315 */ 316 size_t AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex( 317 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); 318 319 /** 320 * Gets the token used by the platform to identify the frame timeline at the given \c index. 321 * q 322 * Available since API level 33. 323 * 324 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See 325 * AChoreographerFrameCallbackData_getFrameTimelinesLength() 326 * 327 */ 328 AVsyncId AChoreographerFrameCallbackData_getFrameTimelineVsyncId( 329 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); 330 331 /** 332 * Gets the time in nanoseconds at which the frame described at the given \c index is expected to 333 * be presented. This time should be used to advance any animation clocks. 334 * 335 * Available since API level 33. 336 * 337 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See 338 * AChoreographerFrameCallbackData_getFrameTimelinesLength() 339 */ 340 int64_t AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos( 341 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); 342 343 /** 344 * Gets the time in nanoseconds at which the frame described at the given \c index needs to be 345 * ready by in order to be presented on time. 346 * 347 * Available since API level 33. 348 * 349 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See 350 * AChoreographerFrameCallbackData_getFrameTimelinesLength() 351 */ 352 int64_t AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos( 353 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); 354 355 __END_DECLS 356 357 #endif // ANDROID_CHOREOGRAPHER_H 358 359 /** @} */ 360