• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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