Home | History | Annotate | Download | only in specs 
      1 Name
      2 
      3     ANDROID_get_frame_timestamps
      4 
      5 Name Strings
      6 
      7     EGL_ANDROID_get_frame_timestamps
      8 
      9 Contributors
     10 
     11     Pablo Ceballos
     12 
     13 Contact
     14 
     15     Pablo Ceballos, Google Inc. (pceballos 'at' google.com)
     16 
     17 Status
     18 
     19     Draft
     20 
     21 Version
     22 
     23     Version 1, May 31, 2016
     24 
     25 Number
     26 
     27     EGL Extension #XXX
     28 
     29 Dependencies
     30 
     31     Requires EGL 1.2
     32 
     33     This extension is written against the wording of the EGL 1.5 Specification
     34 
     35 Overview
     36 
     37     This extension allows querying various timestamps related to the composition
     38     and display of window surfaces.
     39 
     40     Some examples of how this might be used:
     41         - The display retire time can be used to calculate end-to-end latency of
     42           the entire graphics pipeline.
     43         - The queue time and rendering complete time can be used to determine
     44           how long the application's rendering took to complete. Likewise, the
     45           composition start time and finish time can be used to determine how
     46           long the compositor's rendering work took. In combination these can be
     47           used to help determine if the system is GPU or CPU bound.
     48 
     49 New Types
     50 
     51     /*
     52      * EGLnsecsANDROID is a signed integer type for representing a time in
     53      * nanoseconds.
     54      */
     55     #include <khrplatform.h>
     56     typedef khronos_stime_nanoseconds_t EGLnsecsANDROID;
     57 
     58 New Procedures and Functions
     59 
     60     EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, EGLSurface surface,
     61             EGLint framesAgo, EGLint numTimestamps, const EGLint *timestamps,
     62             EGLnsecsANDROID *values);
     63 
     64     EGLBoolean eglQueryTimestampSupportedANDROID(EGLDisplay dpy, EGLSurface
     65             surface, EGLint timestamp);
     66 
     67 New Tokens
     68 
     69     EGL_TIMESTAMPS_ANDROID 0x314D
     70     EGL_QUEUE_TIME_ANDROID 0x314E
     71     EGL_RENDERING_COMPLETE_TIME_ANDROID 0x314F
     72     EGL_COMPOSITION_START_TIME_ANDROID 0x3430
     73     EGL_COMPOSITION_FINISHED_TIME_ANDROID 0x3431
     74     EGL_DISPLAY_RETIRE_TIME_ANDROID 0x3432
     75     EGL_READS_DONE_TIME_ANDROID 0x3433
     76 
     77 Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6
     78 "Surface Attributes", page 43:
     79 
     80     If attribute is EGL_TIMESTAMPS_ANDROID, then values specifies whether to
     81     enable/disable timestamp collection for this surface. A value of EGL_TRUE
     82     enables timestamp collection, while a value of EGL_FALSE disables it. The
     83     initial value is false. If surface is not a window surface this has no
     84     effect.
     85 
     86 Changes to Chapter 3 of the EGL 1.5 Specification (EGL Functions and Errors)
     87 
     88     Add a new subsection under Section 3,
     89 
     90     "3.13 Composition and Display Timestamps
     91 
     92     The function
     93 
     94         EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, EGLSurface
     95             surface, EGLint framesAgo, EGLint numTimestamps,
     96             const EGLint *timestamps, EGLnsecsANDROID *values);
     97 
     98     allows querying various timestamps related to the composition and display of
     99     a window surface.
    100 
    101     The framesAgo parameter indicates how many frames before the last posted
    102     frame to query. So a value of zero would indicate that the query is for the
    103     last posted frame. Note that the implementation maintains a limited history
    104     of timestamp data. If a query is made for a frame whose timestamp history
    105     no longer exists then EGL_BAD_ACCESS is generated. If timestamp collection
    106     has not been enabled for the surface then EGL_BAD_SURFACE is generated.
    107     Timestamps for events that will not occur or have not yet occurred will be
    108     zero. Timestamp queries that are not supported will generate an
    109     EGL_BAD_PARAMETER error. If any error is generated the function will return
    110     EGL_FALSE.
    111 
    112     The eglGetFrameTimestampsANDROID function takes an array of timestamps to
    113     query and returns timestamps in the corresponding indices of the values
    114     array. The possible timestamps that can be queried are:
    115         - EGL_QUEUE_TIME_ANDROID - The time this frame was queued by the
    116           application.
    117         - EGL_RENDERING_COMPLETE_TIME_ANDROID - The time when all of the
    118           application's rendering to the surface was completed.
    119         - EGL_COMPOSITION_START_TIME_ANDROID - The time at which the compositor
    120           began preparing composition for this frame.
    121         - EGL_COMPOSITION_FINISHED_TIME_ANDROID - The time at which the
    122           compositor's rendering work for this frame finished. This will be zero
    123           if composition was handled by the display and the compositor didn't do
    124           any rendering.
    125         - EGL_DISPLAY_RETIRE_TIME_ANDROID - The time at which this frame was
    126           replaced by the next frame on-screen.
    127         - EGL_READS_DONE_TIME_ANDROID - The time at which all reads for the
    128           purpose of display/composition were completed for this frame.
    129 
    130     Not all implementations may support all off the above timestamp queries. The
    131     function
    132 
    133         EGLBoolean eglQueryTimestampSupportedANDROID(EGLDisplay dpy, EGLSurface
    134             surface, EGLint timestamp);
    135 
    136     allows querying which timestamps are supported on the implementation."
    137 
    138 Issues
    139 
    140     None
    141 
    142 Revision History
    143 
    144 #1 (Pablo Ceballos, May 31, 2016)
    145     - Initial draft.
    146