| Name |
| |
| ANDROID_get_frame_timestamps |
| |
| Name Strings |
| |
| EGL_ANDROID_get_frame_timestamps |
| |
| Contributors |
| |
| Brian Anderson |
| Dan Stoza |
| Pablo Ceballos |
| Jesse Hall |
| Fabien Sanglard |
| |
| Contact |
| |
| Brian Anderson, Google Inc. (brianderson 'at' google.com) |
| Dan Stoza, Google Inc. (stoza 'at' google.com) |
| Pablo Ceballos, Google Inc. (pceballos 'at' google.com) |
| Jesse Hall, Google Inc. (jessehall 'at' google.com) |
| Fabien Sanglard, Google Inc. (sanglardf 'at' google.com) |
| |
| Status |
| |
| Draft |
| |
| Version |
| |
| Version 8, April 11, 2017 |
| |
| Number |
| |
| EGL Extension #XXX |
| |
| Dependencies |
| |
| Requires EGL 1.2 |
| |
| This extension is written against the wording of the EGL 1.5 Specification |
| |
| Overview |
| |
| This extension allows querying various timestamps related to the composition |
| and display of window surfaces. |
| |
| Some examples of how this might be used: |
| - The display present time can be used to calculate end-to-end latency |
| of the entire graphics pipeline. |
| - The queue time and rendering complete time can be used to determine |
| how long the application's rendering took to complete. Likewise, the |
| composition start time and finish time can be used to determine how |
| long the compositor's rendering work took. In combination these can be |
| used to help determine if the system is GPU or CPU bound. |
| |
| New Types |
| |
| /* |
| * EGLnsecsANDROID is a signed integer type for representing a time in |
| * nanoseconds. |
| */ |
| #include <khrplatform.h> |
| typedef khronos_stime_nanoseconds_t EGLnsecsANDROID; |
| |
| New Procedures and Functions |
| |
| EGLBoolean eglGetNextFrameIdANDROID(EGLDisplay dpy, EGLSurface surface, |
| EGLuint64KHR *frameId); |
| |
| EGLBoolean eglGetCompositorTimingANDROID(EGLDisplay dpy, |
| EGLSurface surface, EGLint numTimestamps, |
| const EGLint *names, EGLnsecsANDROID *values); |
| |
| EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, EGLSurface surface, |
| EGLuint64KHR frameId, EGLint numTimestamps, |
| const EGLint *timestamps, EGLnsecsANDROID *values); |
| |
| EGLBoolean eglQueryTimestampSupportedANDROID(EGLDisplay dpy, |
| EGLSurface surface, EGLint timestamp); |
| |
| New Tokens |
| |
| EGL_TIMESTAMPS_ANDROID 0x3430 |
| EGL_COMPOSITE_DEADLINE_ANDROID 0x3431 |
| EGL_COMPOSITE_INTERVAL_ANDROID 0x3432 |
| EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID 0x3433 |
| EGL_REQUESTED_PRESENT_TIME_ANDROID 0x3434 |
| EGL_RENDERING_COMPLETE_TIME_ANDROID 0x3435 |
| EGL_COMPOSITION_LATCH_TIME_ANDROID 0x3436 |
| EGL_FIRST_COMPOSITION_START_TIME_ANDROID 0x3437 |
| EGL_LAST_COMPOSITION_START_TIME_ANDROID 0x3438 |
| EGL_FIRST_COMPOSITION_GPU_FINISHED_TIME_ANDROID 0x3439 |
| EGL_DISPLAY_PRESENT_TIME_ANDROID 0x343A |
| EGL_DEQUEUE_READY_TIME_ANDROID 0x343B |
| EGL_READS_DONE_TIME_ANDROID 0x343C |
| EGL_TIMESTAMP_PENDING_ANDROID -2 |
| EGL_TIMESTAMP_INVALID_ANDROID -1 |
| |
| Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6 |
| "Surface Attributes", page 43: |
| |
| If attribute is EGL_TIMESTAMPS_ANDROID, then values specifies whether to |
| enable/disable timestamp collection for this surface. A value of EGL_TRUE |
| enables timestamp collection, while a value of EGL_FALSE disables it. The |
| initial value is false. If surface is not a window surface this has no |
| effect. |
| Changes to Chapter 3 of the EGL 1.5 Specification (EGL Functions and Errors) |
| |
| Add a new subsection under Section 3, |
| |
| "3.13 Composition and Display Timestamps |
| |
| The function |
| |
| EGLBoolean eglGetNextFrameIdANDROID(EGLDisplay dpy, EGLSurface surface, |
| EGLuint64KHR *frameId); |
| |
| Returns an identifier for the next frame to be swapped. The identifier can |
| be used to correlate a particular eglSwapBuffers with its timestamps in |
| eglGetFrameTimestampsANDROID. If any error is generated, the function will |
| return EGL_FALSE. |
| |
| The function |
| |
| EGLBoolean eglGetCompositorTimingANDROID(EGLDisplay dpy, |
| EGLSurface surface, EGLint numTimestamps, |
| const EGLint *names, EGLnsecsANDROID *values); |
| |
| allows querying anticipated timestamps and durations related to the |
| composition and display of a window surface. The values are not associated |
| with a particular frame and can be retrieved before the first swap. |
| |
| The eglGetCompositorTimingANDROID function takes an array of names to |
| query and returns their values in the corresponding indices of the values |
| array. The possible names that can be queried are: |
| - EGL_COMPOSITE_DEADLINE_ANDROID - The timestamp of the next time the |
| compositor will begin composition. This is effectively the deadline |
| for when the compositor must receive a newly queued frame. |
| - EGL_COMPOSITE_INTERVAL_ANDROID - The time delta between subsequent |
| composition events. |
| - EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID - The time delta between |
| the start of composition and the expected present time of that |
| composition. This can be used to estimate the latency of the |
| actual present time. |
| |
| The function |
| |
| EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, |
| EGLSurface surface, EGLuint64KHR frameId, EGLint numTimestamps, |
| const EGLint *timestamps, EGLnsecsANDROID *values); |
| |
| allows querying various timestamps related to the composition and display |
| of specific frames of a window surface. |
| |
| The frameId indicates which frame to query. The implementation maintains a |
| limited history of timestamp data. If a query is made for a frame whose |
| timestamp history no longer exists then EGL_BAD_ACCESS is generated. If |
| timestamp collection has not been enabled for the surface then |
| EGL_BAD_SURFACE is generated. Timestamps for events that might still occur |
| will have the value EGL_TIMESTAMP_PENDING_ANDROID. Timestamps for events |
| that did not occur will have the value EGL_TIMESTAMP_INVALID_ANDROID. |
| Otherwise, the timestamp will be valid and indicate the event has occured. |
| Timestamp queries that are not supported will generate an EGL_BAD_PARAMETER |
| error. If any error is generated the function will return EGL_FALSE. |
| |
| The application can poll for the timestamp of particular events by calling |
| eglGetFrameTimestamps over and over without needing to call any other EGL |
| function between calls. This is true even for the most recently swapped |
| frame. eglGetFrameTimestamps is thread safe and can be called from a |
| different thread than the swapping thread. |
| |
| The eglGetFrameTimestampsANDROID function takes an array of timestamps to |
| query and returns timestamps in the corresponding indices of the values |
| array. The possible timestamps that can be queried are: |
| - EGL_REQUESTED_PRESENT_TIME_ANDROID - The time the application |
| requested this frame be presented. See EGL_ANDROID_presentation_time. |
| If the application does not request a presentation time explicitly, |
| this will correspond to buffer's queue time. |
| - EGL_RENDERING_COMPLETE_TIME_ANDROID - The time when all of the |
| application's rendering to the surface was completed. |
| - EGL_COMPOSITION_LATCH_TIME_ANDROID - The time when the compositor |
| selected this frame as the one to use for the next composition. The |
| latch is the earliest indication that the frame was submitted in time |
| to be composited. |
| - EGL_FIRST_COMPOSITION_START_TIME_ANDROID - The first time at which |
| the compositor began preparing composition for this frame. |
| - EGL_LAST_COMPOSITION_START_TIME_ANDROID - The last time at which the |
| compositor began preparing composition for this frame. If this frame |
| is composited only once, it will have the same value as |
| EGL_FIRST_COMPOSITION_START_TIME_ANDROID. If the value is not equal, |
| that indicates the subsequent frame was not submitted in time to be |
| latched by the compositor. Note: The value may not be updated for |
| every display refresh if the compositor becomes idle. |
| - EGL_FIRST_COMPOSITION_GPU_FINISHED_TIME_ANDROID - The time at which |
| the compositor's rendering work for this frame finished. This will be |
| zero if composition was handled by the display and the compositor |
| didn't do any rendering. |
| - EGL_DISPLAY_PRESENT_TIME_ANDROID - The time at which this frame |
| started to scan out to the physical display. |
| - EGL_DEQUEUE_READY_TIME_ANDROID - The time when the buffer became |
| available for reuse as a buffer the client can target without |
| blocking. This is generally the point when all read commands of the |
| buffer have been submitted, but not necessarily completed. |
| - EGL_READS_DONE_TIME_ANDROID - The time at which all reads for the |
| purpose of display/composition were completed for this frame. |
| |
| Not all implementations may support all of the above timestamp queries. The |
| functions |
| |
| EGLBoolean eglGetCompositorTimingSupportedANDROID(EGLDisplay dpy, |
| EGLSurface surface, EGLint name); |
| |
| and |
| |
| EGLBoolean eglGetFrameTimestampsSupportedANDROID(EGLDisplay dpy, |
| EGLSurface surface, EGLint timestamp); |
| |
| allows querying which values are supported by the implementations of |
| eglGetCompositoTimingANDROID and eglGetFrameTimestampsSupportedANDROID |
| respectively." |
| |
| Issues |
| |
| None |
| |
| Revision History |
| |
| #8 (Brian Anderson, April 11, 2017) |
| - Use reserved enumerant values. |
| |
| #7 (Brian Anderson, March 21, 2017) |
| - Differentiate between pending events and events that did not occur. |
| |
| #6 (Brian Anderson, March 16, 2017) |
| - Remove DISPLAY_RETIRE_TIME_ANDROID. |
| |
| #5 (Brian Anderson, January 13, 2017) |
| - Add eglGetCompositorTimingANDROID. |
| |
| #4 (Brian Anderson, January 10, 2017) |
| - Use an absolute frameId rather than a relative framesAgo. |
| |
| #3 (Brian Anderson, November 30, 2016) |
| - Add EGL_COMPOSITION_LATCH_TIME_ANDROID, |
| EGL_LAST_COMPOSITION_START_TIME_ANDROID, and |
| EGL_DEQUEUE_READY_TIME_ANDROID. |
| |
| #2 (Brian Anderson, July 22, 2016) |
| - Replace EGL_QUEUE_TIME_ANDROID with EGL_REQUESTED_PRESENT_TIME_ANDROID. |
| - Add DISPLAY_PRESENT_TIME_ANDROID. |
| |
| #1 (Pablo Ceballos, May 31, 2016) |
| - Initial draft. |
| |
