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 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 * 41 * @{ 42 */ 43 44 /** 45 * @file choreographer.h 46 */ 47 48 #ifndef ANDROID_CHOREOGRAPHER_H 49 #define ANDROID_CHOREOGRAPHER_H 50 51 #include <stdint.h> 52 #include <sys/cdefs.h> 53 54 __BEGIN_DECLS 55 56 struct AChoreographer; 57 /** 58 * Opaque type that provides access to an AChoreographer object. 59 * 60 * A pointer can be obtained using {@link AChoreographer_getInstance()}. 61 */ 62 typedef struct AChoreographer AChoreographer; 63 64 65 /** 66 * The identifier of a frame timeline. 67 */ 68 typedef int64_t AVsyncId; 69 70 struct AChoreographerFrameCallbackData; 71 /** 72 * Opaque type that provides access to an AChoreographerFrameCallbackData object, which contains 73 * various methods to extract frame information. 74 */ 75 typedef struct AChoreographerFrameCallbackData AChoreographerFrameCallbackData; 76 77 /** 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 */ 85 typedef void (*AChoreographer_frameCallback)(long frameTimeNanos, void* data); 86 87 /** 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 */ 95 typedef void (*AChoreographer_frameCallback64)(int64_t frameTimeNanos, void* data); 96 97 /** 98 * Prototype of the function that is called when a new frame is being rendered. 99 * 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. 102 */ 103 typedef void (*AChoreographer_vsyncCallback)( 104 const AChoreographerFrameCallbackData* callbackData, void* data); 105 106 /** 107 * 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 */ 111 typedef void (*AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, void* data); 112 113 /** 114 * Get the AChoreographer instance for the current thread. This must be called 115 * on an ALooper thread. 116 * 117 * Available since API level 24. 118 */ 119 AChoreographer* AChoreographer_getInstance() __INTRODUCED_IN(24); 120 121 /** 122 * Deprecated: Use AChoreographer_postFrameCallback64 instead. 123 */ 124 void AChoreographer_postFrameCallback(AChoreographer* choreographer, 125 AChoreographer_frameCallback callback, void* data) 126 __INTRODUCED_IN(24) __DEPRECATED_IN(29); 127 128 /** 129 * Deprecated: Use AChoreographer_postFrameCallbackDelayed64 instead. 130 */ 131 void AChoreographer_postFrameCallbackDelayed(AChoreographer* choreographer, 132 AChoreographer_frameCallback callback, void* data, 133 long delayMillis) __INTRODUCED_IN(24) 134 __DEPRECATED_IN(29); 135 136 /** 137 * Post a callback to be run on the next frame. The data pointer provided will 138 * be passed to the callback function when it's called. 139 * 140 * Available since API level 29. 141 */ 142 void AChoreographer_postFrameCallback64(AChoreographer* choreographer, 143 AChoreographer_frameCallback64 callback, void* data) 144 __INTRODUCED_IN(29); 145 146 /** 147 * Post a callback to be run on the frame following the specified delay. The 148 * data pointer provided will be passed to the callback function when it's 149 * called. 150 * 151 * Available since API level 29. 152 */ 153 void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer, 154 AChoreographer_frameCallback64 callback, void* data, 155 uint32_t delayMillis) __INTRODUCED_IN(29); 156 157 /** 158 * Posts a callback to be run on the next frame. The data pointer provided will 159 * be passed to the callback function when it's called. 160 * 161 * Available since API level 33. 162 */ 163 void AChoreographer_postVsyncCallback(AChoreographer* choreographer, 164 AChoreographer_vsyncCallback callback, void* data) 165 __INTRODUCED_IN(33); 166 167 /** 168 * Registers a callback to be run when the display refresh rate changes. The 169 * data pointer provided will be passed to the callback function when it's 170 * called. The same callback may be registered multiple times, provided that a 171 * different data pointer is provided each time. 172 * 173 * If an application registers a callback for this choreographer instance when 174 * no new callbacks were previously registered, that callback is guaranteed to 175 * be dispatched. However, if the callback and associated data pointer are 176 * unregistered prior to running the callback, then the callback may be silently 177 * dropped. 178 * 179 * This api is thread-safe. Any thread is allowed to register a new refresh 180 * rate callback for the choreographer instance. 181 * 182 * Note that in API level 30, this api is not guaranteed to be atomic with 183 * DisplayManager. That is, calling Display#getRefreshRate very soon after 184 * a refresh rate callback is invoked may return a stale refresh rate. If any 185 * Display properties would be required by this callback, then it is recommended 186 * to listen directly to DisplayManager.DisplayListener#onDisplayChanged events 187 * instead. 188 * 189 * As of API level 31, this api is guaranteed to have a consistent view with DisplayManager; 190 * Display#getRefreshRate is guaranteed to not return a stale refresh rate when invoked from this 191 * callback. 192 * 193 * Available since API level 30. 194 */ 195 void AChoreographer_registerRefreshRateCallback(AChoreographer* choreographer, 196 AChoreographer_refreshRateCallback, void* data) 197 __INTRODUCED_IN(30); 198 199 /** 200 * Unregisters a callback to be run when the display refresh rate changes, along 201 * with the data pointer previously provided when registering the callback. The 202 * callback is only unregistered when the data pointer matches one that was 203 * previously registered. 204 * 205 * This api is thread-safe. Any thread is allowed to unregister an existing 206 * refresh rate callback for the choreographer instance. When a refresh rate 207 * callback and associated data pointer are unregistered, then there is a 208 * guarantee that when the unregistration completes that that callback will not 209 * be run with the data pointer passed. 210 * 211 * Available since API level 30. 212 */ 213 void AChoreographer_unregisterRefreshRateCallback(AChoreographer* choreographer, 214 AChoreographer_refreshRateCallback, void* data) 215 __INTRODUCED_IN(30); 216 217 /** 218 * The time in nanoseconds at which the frame started being rendered. 219 * 220 * Note that this time should \b not be used to advance animation clocks. 221 * Instead, see AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(). 222 */ 223 int64_t AChoreographerFrameCallbackData_getFrameTimeNanos( 224 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); 225 226 /** 227 * The number of possible frame timelines. 228 */ 229 size_t AChoreographerFrameCallbackData_getFrameTimelinesLength( 230 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); 231 232 /** 233 * Gets the index of the platform-preferred frame timeline. 234 * The preferred frame timeline is the default 235 * by which the platform scheduled the app, based on the device configuration. 236 */ 237 size_t AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex( 238 const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); 239 240 /** 241 * Gets the token used by the platform to identify the frame timeline at the given \c index. 242 * 243 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See 244 * AChoreographerFrameCallbackData_getFrameTimelinesLength() 245 */ 246 AVsyncId AChoreographerFrameCallbackData_getFrameTimelineVsyncId( 247 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); 248 249 /** 250 * Gets the time in nanoseconds at which the frame described at the given \c index is expected to 251 * be presented. This time should be used to advance any animation clocks. 252 * 253 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See 254 * AChoreographerFrameCallbackData_getFrameTimelinesLength() 255 */ 256 int64_t AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos( 257 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); 258 259 /** 260 * Gets the time in nanoseconds at which the frame described at the given \c index needs to be 261 * ready by in order to be presented on time. 262 * 263 * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See 264 * AChoreographerFrameCallbackData_getFrameTimelinesLength() 265 */ 266 int64_t AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos( 267 const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); 268 269 __END_DECLS 270 271 #endif // ANDROID_CHOREOGRAPHER_H 272 273 /** @} */ 274