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