Home | History | Annotate | Download | only in specs 
      1 Name
      2 
      3     ANDROID_presentation_time
      4 
      5 Name Strings
      6 
      7     EGL_ANDROID_presentation_time
      8 
      9 Contributors
     10 
     11     Jamie Gennis
     12     Andy McFadden
     13     Jesse Hall
     14 
     15 Contact
     16 
     17     Jamie Gennis, Google Inc. (jgennis 'at' google.com)
     18 
     19 Status
     20 
     21     Draft
     22 
     23 Version
     24 
     25     Version 3, June 26, 2013
     26 
     27 Number
     28 
     29     EGL Extension #XXX
     30 
     31 Dependencies
     32 
     33     Requires EGL 1.1
     34 
     35     This extension is written against the wording of the EGL 1.4 Specification
     36 
     37 Overview
     38 
     39     Often when rendering a sequence of images, there is some time at which each
     40     image is intended to be presented to the viewer.  This extension allows
     41     this desired presentation time to be specified for each frame rendered to
     42     an EGLSurface, allowing the native window system to use it.
     43 
     44 New Types
     45 
     46     /*
     47      * EGLnsecsANDROID is a signed integer type for representing a time in
     48      * nanoseconds.
     49      */
     50     #include <khrplatform.h>
     51     typedef khronos_stime_nanoseconds_t EGLnsecsANDROID;
     52 
     53 
     54 New Procedures and Functions
     55 
     56     EGLboolean eglPresentationTimeANDROID(
     57                         EGLDisplay dpy,
     58                         EGLSurface sur,
     59                         EGLnsecsANDROID time);
     60 
     61 New Tokens
     62 
     63     None.
     64 
     65 Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
     66 
     67     Add a new subsection before Section 3.9.4, page 53 (Posting Errors)
     68 
     69     "3.9.4 Presentation Time
     70 
     71     The function
     72 
     73         EGLboolean eglPresentationTimeANDROID(EGLDisplay dpy, EGLSurface
     74             surface, EGLnsecsANDROID time);
     75 
     76     specifies the time at which the current color buffer of surface should be
     77     presented to the viewer.  The time parameter should be a time in
     78     nanoseconds, but the exact meaning of the time depends on the native
     79     window system's use of the presentation time.  In situations where
     80     an absolute time is needed such as displaying the color buffer on a
     81     display device, the time should correspond to the system monotonic up-time
     82     clock.  For situations in which an absolute time is not needed such as
     83     using the color buffer for video encoding, the presentation time of the
     84     first frame may be arbitrarily chosen and those of subsequent frames
     85     chosen relative to that of the first frame.
     86 
     87     The presentation time may be set multiple times, with each call to
     88     eglPresentationTimeANDROID overriding prior calls.  Setting the
     89     presentation time alone does not cause the color buffer to be made
     90     visible, but if the color buffer is subsequently posted to a native window
     91     or copied to a native pixmap then the presentation time of the surface at
     92     that time may be passed along for the native window system to use.
     93 
     94     If the surface presentation time is successfully set, EGL_TRUE is
     95     returned.  Otherwise EGL_FALSE is returned and an appropriate error is
     96     set.  If <dpy> is not the name of a valid, initialized EGLDisplay, an
     97     EGL_BAD_DISPLAY error is generated.  If <surface> is not a valid EGLSurface
     98     then an EGL_BAD_SURFACE error is generated.
     99 
    100 Issues
    101 
    102     1. How is the presentation time used?
    103 
    104     RESOLVED: The uses of the presentation time are intentionally not specified
    105     in this extension.  Some possible uses include Audio/Video synchronization,
    106     video frame timestamps for video encoding, display latency metrics, and
    107     display latency control.
    108 
    109     2. How can the current value of the clock that should be used for the
    110     presentation time when an absolute time is needed be queried on Android?
    111 
    112     RESOLVED: The current clock value can be queried from the Java
    113     System.nanoTime() method, or from the native clock_gettime function by
    114     passing CLOCK_MONOTONIC as the clock identifier.
    115 
    116     3. Should the presentation time be state which is used by eglSwapBuffers,
    117     or should it be a new parameter to an extended variant of eglSwapBuffers?
    118 
    119     RESOLVED: The presentation time should be new state which is used by
    120     the existing eglSwapBuffers call. Adding new state composes better with
    121     other (hypothetical) extensions that also modify the behavior of
    122     eglSwapBuffers.
    123 
    124 Revision History
    125 
    126 #3 (Jesse Hall, June 26, 2013)
    127     - Enumerated errors generated by eglPresentationTimeANDROID.
    128     - Added Issue #3 with resolution.
    129 
    130 #2 (Jamie Gennis, April 1, 2013)
    131     - Clarified how uses that either do or do not need an absolute time should
    132       be handled.
    133     - Specified the eglPresentationTimeANDROID return value.
    134 
    135 #1 (Jamie Gennis, January 8, 2013)
    136     - Initial draft.
    137