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 present or 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_REQUESTED_PRESENT_TIME_ANDROID 0x314E
    EGL_RENDERING_COMPLETE_TIME_ANDROID 0x314F
    EGL_COMPOSITION_START_TIME_ANDROID 0x3430
    EGL_COMPOSITION_FINISHED_TIME_ANDROID 0x3431
    EGL_DISPLAY_PRESENT_TIME_ANDROID 0x3432
    EGL_DISPLAY_RETIRE_TIME_ANDROID 0x3433
    EGL_READS_DONE_TIME_ANDROID 0x3434

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 queued
    frame to query. So a value of zero would indicate that the query is for the
    last queued 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_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_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_PRESENT_TIME_ANDROID - The time at which this frame
          started to scan out on the physical display.
        - 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 of 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.

#2 (Brian Anderson, July 22, 2016)
    - Replace EGL_QUEUE_TIME_ANDROID with EGL_REQUESTED_PRESENT_TIME_ANDROID.
    - Add DISPLAY_PRESENT_TIME_ANDROID.
