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 29 #include <stdint.h> 30 #include <sys/cdefs.h> 31 32 __BEGIN_DECLS 33 34 struct AChoreographer; 35 /** 36 * Opaque type that provides access to an AChoreographer object. 37 * 38 * A pointer can be obtained using {@link AChoreographer_getInstance()}. 39 */ 40 typedef struct AChoreographer AChoreographer; 41 42 /** 43 * Prototype of the function that is called when a new frame is being rendered. 44 * It's passed the time that the frame is being rendered as nanoseconds in the 45 * CLOCK_MONOTONIC time base, as well as the data pointer provided by the 46 * application that registered a callback. All callbacks that run as part of 47 * rendering a frame will observe the same frame time, so it should be used 48 * whenever events need to be synchronized (e.g. animations). 49 */ 50 typedef void (*AChoreographer_frameCallback)(long frameTimeNanos, void* data); 51 52 /** 53 * Prototype of the function that is called when a new frame is being rendered. 54 * It's passed the time that the frame is being rendered as nanoseconds in the 55 * CLOCK_MONOTONIC time base, as well as the data pointer provided by the 56 * application that registered a callback. All callbacks that run as part of 57 * rendering a frame will observe the same frame time, so it should be used 58 * whenever events need to be synchronized (e.g. animations). 59 */ 60 typedef void (*AChoreographer_frameCallback64)(int64_t frameTimeNanos, void* data); 61 62 /** 63 * Prototype of the function that is called when the display refresh rate 64 * changes. It's passed the new vsync period in nanoseconds, as well as the data 65 * pointer provided by the application that registered a callback. 66 */ 67 typedef void (*AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, void* data); 68 69 /** 70 * Get the AChoreographer instance for the current thread. This must be called 71 * on an ALooper thread. 72 * 73 * Available since API level 24. 74 */ 75 AChoreographer* AChoreographer_getInstance() __INTRODUCED_IN(24); 76 77 /** 78 * Deprecated: Use AChoreographer_postFrameCallback64 instead. 79 */ 80 void AChoreographer_postFrameCallback(AChoreographer* choreographer, 81 AChoreographer_frameCallback callback, void* data) 82 __INTRODUCED_IN(24) __DEPRECATED_IN(29); 83 84 /** 85 * Deprecated: Use AChoreographer_postFrameCallbackDelayed64 instead. 86 */ 87 void AChoreographer_postFrameCallbackDelayed(AChoreographer* choreographer, 88 AChoreographer_frameCallback callback, void* data, 89 long delayMillis) __INTRODUCED_IN(24) 90 __DEPRECATED_IN(29); 91 92 /** 93 * Power a callback to be run on the next frame. The data pointer provided will 94 * be passed to the callback function when it's called. 95 * 96 * Available since API level 29. 97 */ 98 void AChoreographer_postFrameCallback64(AChoreographer* choreographer, 99 AChoreographer_frameCallback64 callback, void* data) 100 __INTRODUCED_IN(29); 101 102 /** 103 * Post a callback to be run on the frame following the specified delay. The 104 * data pointer provided will be passed to the callback function when it's 105 * called. 106 * 107 * Available since API level 29. 108 */ 109 void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer, 110 AChoreographer_frameCallback64 callback, void* data, 111 uint32_t delayMillis) __INTRODUCED_IN(29); 112 113 /** 114 * Registers a callback to be run when the display refresh rate changes. The 115 * data pointer provided will be passed to the callback function when it's 116 * called. The same callback may be registered multiple times, provided that a 117 * different data pointer is provided each time. 118 * 119 * If an application registers a callback for this choreographer instance when 120 * no new callbacks were previously registered, that callback is guaranteed to 121 * be dispatched. However, if the callback and associated data pointer are 122 * unregistered prior to running the callback, then the callback may be silently 123 * dropped. 124 * 125 * This api is thread-safe. Any thread is allowed to register a new refresh 126 * rate callback for the choreographer instance. 127 * 128 * Note that in API level 30, this api is not guaranteed to be atomic with 129 * DisplayManager. That is, calling Display#getRefreshRate very soon after 130 * a refresh rate callback is invoked may return a stale refresh rate. If any 131 * Display properties would be required by this callback, then it is recommended 132 * to listen directly to DisplayManager.DisplayListener#onDisplayChanged events 133 * instead. 134 * 135 * As of API level 31, this api is guaranteed to have a consistent view with DisplayManager; 136 * Display#getRefreshRate is guaranteed to not return a stale refresh rate when invoked from this 137 * callback. 138 * 139 * Available since API level 30. 140 */ 141 void AChoreographer_registerRefreshRateCallback(AChoreographer* choreographer, 142 AChoreographer_refreshRateCallback, void* data) 143 __INTRODUCED_IN(30); 144 145 /** 146 * Unregisters a callback to be run when the display refresh rate changes, along 147 * with the data pointer previously provided when registering the callback. The 148 * callback is only unregistered when the data pointer matches one that was 149 * previously registered. 150 * 151 * This api is thread-safe. Any thread is allowed to unregister an existing 152 * refresh rate callback for the choreographer instance. When a refresh rate 153 * callback and associated data pointer are unregistered, then there is a 154 * guarantee that when the unregistration completes that that callback will not 155 * be run with the data pointer passed. 156 * 157 * Available since API level 30. 158 */ 159 void AChoreographer_unregisterRefreshRateCallback(AChoreographer* choreographer, 160 AChoreographer_refreshRateCallback, void* data) 161 __INTRODUCED_IN(30); 162 163 __END_DECLS 164 165 #endif // ANDROID_CHOREOGRAPHER_H 166 167 /** @} */ 168