blob: 30337ad7a922d36b8e3cf6c0d37c23d821017cd8 [file] [log] [blame]
Name
ANDROID_get_frame_timestamps
Name Strings
EGL_ANDROID_get_frame_timestamps
Contributors
Pablo Ceballos
Contact
Pablo Ceballos, Google Inc. (pceballos 'at' google.com)
Status
Draft
Version
Version 1, May 31, 2016
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 retire 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 eglGetFrameTimestampsANDROID(EGLDisplay dpy, EGLSurface surface,
EGLint framesAgo, EGLint numTimestamps, const EGLint *timestamps,
EGLnsecsANDROID *values);
EGLBoolean eglQueryTimestampSupportedANDROID(EGLDisplay dpy, EGLSurface
surface, EGLint timestamp);
New Tokens
EGL_TIMESTAMPS_ANDROID 0x314D
EGL_QUEUE_TIME_ANDROID 0x314E
EGL_RENDERING_COMPLETE_TIME_ANDROID 0x314F
EGL_COMPOSITION_START_TIME_ANDROID 0x3430
EGL_COMPOSITION_FINISHED_TIME_ANDROID 0x3431
EGL_DISPLAY_RETIRE_TIME_ANDROID 0x3432
EGL_READS_DONE_TIME_ANDROID 0x3433
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 eglGetFrameTimestampsANDROID(EGLDisplay dpy, EGLSurface
surface, EGLint framesAgo, EGLint numTimestamps,
const EGLint *timestamps, EGLnsecsANDROID *values);
allows querying various timestamps related to the composition and display of
a window surface.
The framesAgo parameter indicates how many frames before the last posted
frame to query. So a value of zero would indicate that the query is for the
last posted frame. Note that 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 will not occur or have not yet occurred will be
zero. 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 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_QUEUE_TIME_ANDROID - The time this frame was queued by the
application.
- EGL_RENDERING_COMPLETE_TIME_ANDROID - The time when all of the
application's rendering to the surface was completed.
- EGL_COMPOSITION_START_TIME_ANDROID - The time at which the compositor
began preparing composition for this frame.
- EGL_COMPOSITION_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_RETIRE_TIME_ANDROID - The time at which this frame was
replaced by the next frame on-screen.
- 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 off the above timestamp queries. The
function
EGLBoolean eglQueryTimestampSupportedANDROID(EGLDisplay dpy, EGLSurface
surface, EGLint timestamp);
allows querying which timestamps are supported on the implementation."
Issues
None
Revision History
#1 (Pablo Ceballos, May 31, 2016)
- Initial draft.