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 1, January 13, 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 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 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 0x314D
    EGL_COMPOSITE_DEADLINE_ANDROID 0x314E
    EGL_COMPOSITE_INTERVAL_ANDROID 0x314F
    EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID 0x3150
    EGL_REQUESTED_PRESENT_TIME_ANDROID 0x3151
    EGL_RENDERING_COMPLETE_TIME_ANDROID 0x3152
    EGL_COMPOSITION_LATCH_TIME_ANDROID 0x3153
    EGL_FIRST_COMPOSITION_START_TIME_ANDROID 0x3154
    EGL_LAST_COMPOSITION_START_TIME_ANDROID 0x3155
    EGL_FIRST_COMPOSITION_FINISHED_TIME_ANDROID 0x3156
    EGL_DISPLAY_PRESENT_TIME_ANDROID 0x3157
    EGL_DISPLAY_RETIRE_TIME_ANDROID 0x3158
    EGL_DEQUEUE_READY_TIME_ANDROID 0x3159
    EGL_READS_DONE_TIME_ANDROID 0x315A

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 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 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_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_DISPLAY_RETIRE_TIME_ANDROID - The time at which this frame was
          replaced by the next frame on-screen.
        - 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

#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.

