1Name
2
3    ANDROID_get_frame_timestamps
4
5Name Strings
6
7    EGL_ANDROID_get_frame_timestamps
8
9Contributors
10
11    Brian Anderson
12    Dan Stoza
13    Pablo Ceballos
14    Jesse Hall
15    Fabien Sanglard
16
17Contact
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
25Status
26
27    Draft
28
29Version
30
31    Version 8, April 11, 2017
32
33Number
34
35    EGL Extension #XXX
36
37Dependencies
38
39    Requires EGL 1.2
40
41    This extension is written against the wording of the EGL 1.5 Specification
42
43Overview
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
57New 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
66New 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
82New 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
100Add 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.
108Changes 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
223Issues
224
225    None
226
227Revision 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