1 Name 2 3 ANDROID_get_frame_timestamps 4 5 Name Strings 6 7 EGL_ANDROID_get_frame_timestamps 8 9 Contributors 10 11 Brian Anderson 12 Dan Stoza 13 Pablo Ceballos 14 Jesse Hall 15 Fabien Sanglard 16 17 Contact 18 19 Brian Anderson, Google Inc. (brianderson 'at' google.com) 20 Dan Stoza, Google Inc. (stoza 'at' google.com) 21 Pablo Ceballos, Google Inc. (pceballos 'at' google.com) 22 Jesse Hall, Google Inc. (jessehall 'at' google.com) 23 Fabien Sanglard, Google Inc. (sanglardf 'at' google.com) 24 25 Status 26 27 Draft 28 29 Version 30 31 Version 8, April 11, 2017 32 33 Number 34 35 EGL Extension #XXX 36 37 Dependencies 38 39 Requires EGL 1.2 40 41 This extension is written against the wording of the EGL 1.5 Specification 42 43 Overview 44 45 This extension allows querying various timestamps related to the composition 46 and display of window surfaces. 47 48 Some examples of how this might be used: 49 - The display present time can be used to calculate end-to-end latency 50 of the entire graphics pipeline. 51 - The queue time and rendering complete time can be used to determine 52 how long the application's rendering took to complete. Likewise, the 53 composition start time and finish time can be used to determine how 54 long the compositor's rendering work took. In combination these can be 55 used to help determine if the system is GPU or CPU bound. 56 57 New Types 58 59 /* 60 * EGLnsecsANDROID is a signed integer type for representing a time in 61 * nanoseconds. 62 */ 63 #include <khrplatform.h> 64 typedef khronos_stime_nanoseconds_t EGLnsecsANDROID; 65 66 New Procedures and Functions 67 68 EGLBoolean eglGetNextFrameIdANDROID(EGLDisplay dpy, EGLSurface surface, 69 EGLuint64KHR *frameId); 70 71 EGLBoolean eglGetCompositorTimingANDROID(EGLDisplay dpy, 72 EGLSurface surface, EGLint numTimestamps, 73 const EGLint *names, EGLnsecsANDROID *values); 74 75 EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, EGLSurface surface, 76 EGLuint64KHR frameId, EGLint numTimestamps, 77 const EGLint *timestamps, EGLnsecsANDROID *values); 78 79 EGLBoolean eglQueryTimestampSupportedANDROID(EGLDisplay dpy, 80 EGLSurface surface, EGLint timestamp); 81 82 New Tokens 83 84 EGL_TIMESTAMPS_ANDROID 0x3430 85 EGL_COMPOSITE_DEADLINE_ANDROID 0x3431 86 EGL_COMPOSITE_INTERVAL_ANDROID 0x3432 87 EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID 0x3433 88 EGL_REQUESTED_PRESENT_TIME_ANDROID 0x3434 89 EGL_RENDERING_COMPLETE_TIME_ANDROID 0x3435 90 EGL_COMPOSITION_LATCH_TIME_ANDROID 0x3436 91 EGL_FIRST_COMPOSITION_START_TIME_ANDROID 0x3437 92 EGL_LAST_COMPOSITION_START_TIME_ANDROID 0x3438 93 EGL_FIRST_COMPOSITION_GPU_FINISHED_TIME_ANDROID 0x3439 94 EGL_DISPLAY_PRESENT_TIME_ANDROID 0x343A 95 EGL_DEQUEUE_READY_TIME_ANDROID 0x343B 96 EGL_READS_DONE_TIME_ANDROID 0x343C 97 EGL_TIMESTAMP_PENDING_ANDROID -2 98 EGL_TIMESTAMP_INVALID_ANDROID -1 99 100 Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6 101 "Surface Attributes", page 43: 102 103 If attribute is EGL_TIMESTAMPS_ANDROID, then values specifies whether to 104 enable/disable timestamp collection for this surface. A value of EGL_TRUE 105 enables timestamp collection, while a value of EGL_FALSE disables it. The 106 initial value is false. If surface is not a window surface this has no 107 effect. 108 Changes to Chapter 3 of the EGL 1.5 Specification (EGL Functions and Errors) 109 110 Add a new subsection under Section 3, 111 112 "3.13 Composition and Display Timestamps 113 114 The function 115 116 EGLBoolean eglGetNextFrameIdANDROID(EGLDisplay dpy, EGLSurface surface, 117 EGLuint64KHR *frameId); 118 119 Returns an identifier for the next frame to be swapped. The identifier can 120 be used to correlate a particular eglSwapBuffers with its timestamps in 121 eglGetFrameTimestampsANDROID. If any error is generated, the function will 122 return EGL_FALSE. 123 124 The function 125 126 EGLBoolean eglGetCompositorTimingANDROID(EGLDisplay dpy, 127 EGLSurface surface, EGLint numTimestamps, 128 const EGLint *names, EGLnsecsANDROID *values); 129 130 allows querying anticipated timestamps and durations related to the 131 composition and display of a window surface. The values are not associated 132 with a particular frame and can be retrieved before the first swap. 133 134 The eglGetCompositorTimingANDROID function takes an array of names to 135 query and returns their values in the corresponding indices of the values 136 array. The possible names that can be queried are: 137 - EGL_COMPOSITE_DEADLINE_ANDROID - The timestamp of the next time the 138 compositor will begin composition. This is effectively the deadline 139 for when the compositor must receive a newly queued frame. 140 - EGL_COMPOSITE_INTERVAL_ANDROID - The time delta between subsequent 141 composition events. 142 - EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID - The time delta between 143 the start of composition and the expected present time of that 144 composition. This can be used to estimate the latency of the 145 actual present time. 146 147 The function 148 149 EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, 150 EGLSurface surface, EGLuint64KHR frameId, EGLint numTimestamps, 151 const EGLint *timestamps, EGLnsecsANDROID *values); 152 153 allows querying various timestamps related to the composition and display 154 of specific frames of a window surface. 155 156 The frameId indicates which frame to query. The implementation maintains a 157 limited history of timestamp data. If a query is made for a frame whose 158 timestamp history no longer exists then EGL_BAD_ACCESS is generated. If 159 timestamp collection has not been enabled for the surface then 160 EGL_BAD_SURFACE is generated. Timestamps for events that might still occur 161 will have the value EGL_TIMESTAMP_PENDING_ANDROID. Timestamps for events 162 that did not occur will have the value EGL_TIMESTAMP_INVALID_ANDROID. 163 Otherwise, the timestamp will be valid and indicate the event has occured. 164 Timestamp queries that are not supported will generate an EGL_BAD_PARAMETER 165 error. If any error is generated the function will return EGL_FALSE. 166 167 The application can poll for the timestamp of particular events by calling 168 eglGetFrameTimestamps over and over without needing to call any other EGL 169 function between calls. This is true even for the most recently swapped 170 frame. eglGetFrameTimestamps is thread safe and can be called from a 171 different thread than the swapping thread. 172 173 The eglGetFrameTimestampsANDROID function takes an array of timestamps to 174 query and returns timestamps in the corresponding indices of the values 175 array. The possible timestamps that can be queried are: 176 - EGL_REQUESTED_PRESENT_TIME_ANDROID - The time the application 177 requested this frame be presented. See EGL_ANDROID_presentation_time. 178 If the application does not request a presentation time explicitly, 179 this will correspond to buffer's queue time. 180 - EGL_RENDERING_COMPLETE_TIME_ANDROID - The time when all of the 181 application's rendering to the surface was completed. 182 - EGL_COMPOSITION_LATCH_TIME_ANDROID - The time when the compositor 183 selected this frame as the one to use for the next composition. The 184 latch is the earliest indication that the frame was submitted in time 185 to be composited. 186 - EGL_FIRST_COMPOSITION_START_TIME_ANDROID - The first time at which 187 the compositor began preparing composition for this frame. 188 - EGL_LAST_COMPOSITION_START_TIME_ANDROID - The last time at which the 189 compositor began preparing composition for this frame. If this frame 190 is composited only once, it will have the same value as 191 EGL_FIRST_COMPOSITION_START_TIME_ANDROID. If the value is not equal, 192 that indicates the subsequent frame was not submitted in time to be 193 latched by the compositor. Note: The value may not be updated for 194 every display refresh if the compositor becomes idle. 195 - EGL_FIRST_COMPOSITION_GPU_FINISHED_TIME_ANDROID - The time at which 196 the compositor's rendering work for this frame finished. This will be 197 zero if composition was handled by the display and the compositor 198 didn't do any rendering. 199 - EGL_DISPLAY_PRESENT_TIME_ANDROID - The time at which this frame 200 started to scan out to the physical display. 201 - EGL_DEQUEUE_READY_TIME_ANDROID - The time when the buffer became 202 available for reuse as a buffer the client can target without 203 blocking. This is generally the point when all read commands of the 204 buffer have been submitted, but not necessarily completed. 205 - EGL_READS_DONE_TIME_ANDROID - The time at which all reads for the 206 purpose of display/composition were completed for this frame. 207 208 Not all implementations may support all of the above timestamp queries. The 209 functions 210 211 EGLBoolean eglGetCompositorTimingSupportedANDROID(EGLDisplay dpy, 212 EGLSurface surface, EGLint name); 213 214 and 215 216 EGLBoolean eglGetFrameTimestampsSupportedANDROID(EGLDisplay dpy, 217 EGLSurface surface, EGLint timestamp); 218 219 allows querying which values are supported by the implementations of 220 eglGetCompositoTimingANDROID and eglGetFrameTimestampsSupportedANDROID 221 respectively." 222 223 Issues 224 225 None 226 227 Revision History 228 229 #8 (Brian Anderson, April 11, 2017) 230 - Use reserved enumerant values. 231 232 #7 (Brian Anderson, March 21, 2017) 233 - Differentiate between pending events and events that did not occur. 234 235 #6 (Brian Anderson, March 16, 2017) 236 - Remove DISPLAY_RETIRE_TIME_ANDROID. 237 238 #5 (Brian Anderson, January 13, 2017) 239 - Add eglGetCompositorTimingANDROID. 240 241 #4 (Brian Anderson, January 10, 2017) 242 - Use an absolute frameId rather than a relative framesAgo. 243 244 #3 (Brian Anderson, November 30, 2016) 245 - Add EGL_COMPOSITION_LATCH_TIME_ANDROID, 246 EGL_LAST_COMPOSITION_START_TIME_ANDROID, and 247 EGL_DEQUEUE_READY_TIME_ANDROID. 248 249 #2 (Brian Anderson, July 22, 2016) 250 - Replace EGL_QUEUE_TIME_ANDROID with EGL_REQUESTED_PRESENT_TIME_ANDROID. 251 - Add DISPLAY_PRESENT_TIME_ANDROID. 252 253 #1 (Pablo Ceballos, May 31, 2016) 254 - Initial draft. 255 256
