Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 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 | */ |
| 21 | |
| 22 | /** |
| 23 | * @file choreographer.h |
| 24 | */ |
| 25 | |
| 26 | #ifndef ANDROID_CHOREOGRAPHER_H |
| 27 | #define ANDROID_CHOREOGRAPHER_H |
| 28 | |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 29 | #include <stdint.h> |
Michael Wright | fb911b2 | 2016-01-26 16:05:54 -0800 | [diff] [blame] | 30 | #include <sys/cdefs.h> |
| 31 | |
Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 32 | __BEGIN_DECLS |
| 33 | |
| 34 | struct AChoreographer; |
| 35 | typedef struct AChoreographer AChoreographer; |
| 36 | |
| 37 | /** |
| 38 | * Prototype of the function that is called when a new frame is being rendered. |
| 39 | * It's passed the time that the frame is being rendered as nanoseconds in the |
| 40 | * CLOCK_MONOTONIC time base, as well as the data pointer provided by the |
| 41 | * application that registered a callback. All callbacks that run as part of |
| 42 | * rendering a frame will observe the same frame time, so it should be used |
| 43 | * whenever events need to be synchronized (e.g. animations). |
| 44 | */ |
| 45 | typedef void (*AChoreographer_frameCallback)(long frameTimeNanos, void* data); |
| 46 | |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 47 | /** |
| 48 | * Prototype of the function that is called when a new frame is being rendered. |
| 49 | * It's passed the time that the frame is being rendered as nanoseconds in the |
| 50 | * CLOCK_MONOTONIC time base, as well as the data pointer provided by the |
| 51 | * application that registered a callback. All callbacks that run as part of |
| 52 | * rendering a frame will observe the same frame time, so it should be used |
| 53 | * whenever events need to be synchronized (e.g. animations). |
| 54 | */ |
| 55 | typedef void (*AChoreographer_frameCallback64)(int64_t frameTimeNanos, void* data); |
| 56 | |
Alec Mouri | 33682e9 | 2020-01-10 15:11:15 -0800 | [diff] [blame] | 57 | /** |
| 58 | * Prototype of the function that is called when the display refresh rate |
| 59 | * changes. It's passed the new vsync period in nanoseconds, as well as the data |
| 60 | * pointer provided by the application that registered a callback. |
| 61 | */ |
| 62 | typedef void (*AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, void* data); |
| 63 | |
Ryan Prichard | 92b1ebe | 2018-07-19 20:32:19 -0700 | [diff] [blame] | 64 | #if __ANDROID_API__ >= 24 |
| 65 | |
Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 66 | /** |
| 67 | * Get the AChoreographer instance for the current thread. This must be called |
| 68 | * on an ALooper thread. |
Elliott Hughes | 3d70e53 | 2019-10-29 08:59:39 -0700 | [diff] [blame] | 69 | * |
| 70 | * Available since API level 24. |
Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 71 | */ |
Elliott Hughes | 9db409b | 2018-06-18 12:28:46 -0700 | [diff] [blame] | 72 | AChoreographer* AChoreographer_getInstance() __INTRODUCED_IN(24); |
Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 73 | |
| 74 | /** |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 75 | * Deprecated: Use AChoreographer_postFrameCallback64 instead. |
Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 76 | */ |
| 77 | void AChoreographer_postFrameCallback(AChoreographer* choreographer, |
Alec Mouri | 271de04 | 2020-04-27 22:38:19 -0700 | [diff] [blame] | 78 | AChoreographer_frameCallback callback, void* data) |
| 79 | __INTRODUCED_IN(24) __DEPRECATED_IN(29); |
Elliott Hughes | 9db409b | 2018-06-18 12:28:46 -0700 | [diff] [blame] | 80 | |
Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 81 | /** |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 82 | * Deprecated: Use AChoreographer_postFrameCallbackDelayed64 instead. |
Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 83 | */ |
| 84 | void AChoreographer_postFrameCallbackDelayed(AChoreographer* choreographer, |
Alec Mouri | 271de04 | 2020-04-27 22:38:19 -0700 | [diff] [blame] | 85 | AChoreographer_frameCallback callback, void* data, |
| 86 | long delayMillis) __INTRODUCED_IN(24) |
| 87 | __DEPRECATED_IN(29); |
Dan Albert | 494ed55 | 2016-09-23 15:57:45 -0700 | [diff] [blame] | 88 | |
Ryan Prichard | 92b1ebe | 2018-07-19 20:32:19 -0700 | [diff] [blame] | 89 | #endif /* __ANDROID_API__ >= 24 */ |
| 90 | |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 91 | #if __ANDROID_API__ >= 29 |
| 92 | |
| 93 | /** |
| 94 | * Power a callback to be run on the next frame. The data pointer provided will |
| 95 | * be passed to the callback function when it's called. |
Elliott Hughes | 3d70e53 | 2019-10-29 08:59:39 -0700 | [diff] [blame] | 96 | * |
| 97 | * Available since API level 29. |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 98 | */ |
Dillon Cower | 20e67fa | 2019-07-30 15:39:54 -0700 | [diff] [blame] | 99 | void AChoreographer_postFrameCallback64(AChoreographer* choreographer, |
Alec Mouri | 271de04 | 2020-04-27 22:38:19 -0700 | [diff] [blame] | 100 | AChoreographer_frameCallback64 callback, void* data) |
| 101 | __INTRODUCED_IN(29); |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 102 | |
| 103 | /** |
| 104 | * Post a callback to be run on the frame following the specified delay. The |
| 105 | * data pointer provided will be passed to the callback function when it's |
| 106 | * called. |
Elliott Hughes | 3d70e53 | 2019-10-29 08:59:39 -0700 | [diff] [blame] | 107 | * |
| 108 | * Available since API level 29. |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 109 | */ |
| 110 | void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer, |
Alec Mouri | 271de04 | 2020-04-27 22:38:19 -0700 | [diff] [blame] | 111 | AChoreographer_frameCallback64 callback, void* data, |
| 112 | uint32_t delayMillis) __INTRODUCED_IN(29); |
Santos Cordon | 908d008 | 2019-02-20 18:08:02 +0000 | [diff] [blame] | 113 | |
| 114 | #endif /* __ANDROID_API__ >= 29 */ |
| 115 | |
Alec Mouri | 33682e9 | 2020-01-10 15:11:15 -0800 | [diff] [blame] | 116 | #if __ANDROID_API__ >= 30 |
| 117 | |
| 118 | /** |
| 119 | * Registers a callback to be run when the display refresh rate changes. The |
| 120 | * data pointer provided will be passed to the callback function when it's |
| 121 | * called. The same callback may be registered multiple times, provided that a |
| 122 | * different data pointer is provided each time. |
| 123 | * |
| 124 | * If an application registers a callback for this choreographer instance when |
| 125 | * no new callbacks were previously registered, that callback is guaranteed to |
| 126 | * be dispatched. However, if the callback and associated data pointer are |
| 127 | * unregistered prior to running the callback, then the callback may be silently |
| 128 | * dropped. |
| 129 | * |
| 130 | * This api is thread-safe. Any thread is allowed to register a new refresh |
| 131 | * rate callback for the choreographer instance. |
Elliott Hughes | 7be0e2d | 2020-06-02 13:05:04 -0700 | [diff] [blame] | 132 | * |
Alec Mouri | 4a33165 | 2020-07-20 22:05:24 +0000 | [diff] [blame] | 133 | * Note that in API level 30, this api is not guaranteed to be atomic with |
| 134 | * DisplayManager. That is, calling Display#getRefreshRate very soon after |
| 135 | * a refresh rate callback is invoked may return a stale refresh rate. If any |
| 136 | * Display properties would be required by this callback, then it is recommended |
| 137 | * to listen directly to DisplayManager.DisplayListener#onDisplayChanged events |
| 138 | * instead. |
| 139 | * |
Elliott Hughes | 7be0e2d | 2020-06-02 13:05:04 -0700 | [diff] [blame] | 140 | * Available since API level 30. |
Alec Mouri | 33682e9 | 2020-01-10 15:11:15 -0800 | [diff] [blame] | 141 | */ |
| 142 | void AChoreographer_registerRefreshRateCallback(AChoreographer* choreographer, |
Elliott Hughes | 7be0e2d | 2020-06-02 13:05:04 -0700 | [diff] [blame] | 143 | AChoreographer_refreshRateCallback, void* data) |
| 144 | __INTRODUCED_IN(30); |
Alec Mouri | 33682e9 | 2020-01-10 15:11:15 -0800 | [diff] [blame] | 145 | |
| 146 | /** |
| 147 | * Unregisters a callback to be run when the display refresh rate changes, along |
| 148 | * with the data pointer previously provided when registering the callback. The |
| 149 | * callback is only unregistered when the data pointer matches one that was |
| 150 | * previously registered. |
| 151 | * |
| 152 | * This api is thread-safe. Any thread is allowed to unregister an existing |
| 153 | * refresh rate callback for the choreographer instance. When a refresh rate |
| 154 | * callback and associated data pointer are unregistered, then there is a |
| 155 | * guarantee that when the unregistration completes that that callback will not |
| 156 | * be run with the data pointer passed. |
Elliott Hughes | 7be0e2d | 2020-06-02 13:05:04 -0700 | [diff] [blame] | 157 | * |
| 158 | * Available since API level 30. |
Alec Mouri | 33682e9 | 2020-01-10 15:11:15 -0800 | [diff] [blame] | 159 | */ |
| 160 | void AChoreographer_unregisterRefreshRateCallback(AChoreographer* choreographer, |
Elliott Hughes | 7be0e2d | 2020-06-02 13:05:04 -0700 | [diff] [blame] | 161 | AChoreographer_refreshRateCallback, void* data) |
| 162 | __INTRODUCED_IN(30); |
Alec Mouri | 33682e9 | 2020-01-10 15:11:15 -0800 | [diff] [blame] | 163 | #endif /* __ANDROID_API__ >= 30 */ |
| 164 | |
Michael Wright | f5eee40 | 2015-12-07 15:26:38 -0500 | [diff] [blame] | 165 | __END_DECLS |
| 166 | |
| 167 | #endif // ANDROID_CHOREOGRAPHER_H |
| 168 | |
| 169 | /** @} */ |