opengl/specs/EGL_ANDROID_presentation_time.txt

   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.