EGL_ANDROID_presentation_time: initial spec draft

Change-Id: I1cd174a08c499e5bde19e7ecd449da8266e7e66e

opengl/specs/EGL_ANDROID_presentation_time.txt

@@ -0,0 +1,121 @@
+Name
+
+    ANDROID_presentation_time
+
+Name Strings
+
+    EGL_ANDROID_presentation_time
+
+Contributors
+
+    Jamie Gennis
+    Andy McFadden
+
+Contact
+
+    Jamie Gennis, Google Inc. (jgennis 'at' google.com)
+
+Status
+
+    Draft
+
+Version
+
+    Version 2, April 1, 2013
+
+Number
+
+    EGL Extension #XXX
+
+Dependencies
+
+    Requires EGL 1.1
+
+    This extension is written against the wording of the EGL 1.4 Specification
+
+Overview
+
+    Often when rendering a sequence of images, there is some time at which each
+    image is intended to be presented to the viewer.  This extension allows
+    this desired presentation time to be specified for each frame rendered to
+    an EGLSurface, allowing the native window system to use it.
+
+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 eglPresentationTimeANDROID(
+                        EGLDisplay dpy,
+                        EGLSurface sur,
+                        EGLnsecsANDROID time);
+
+New Tokens
+
+    None.
+
+Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
+
+    Add a new subsection before Section 3.9.4, page 53 (Posting Errors)
+
+    "3.9.4 Presentation Time
+
+    The function
+
+        EGLboolean eglPresentationTimeANDROID(EGLDisplay dpy, EGLSurface
+            surface, EGLnsecsANDROID time);
+
+    specifies the time at which the current color buffer of surface should be
+    presented to the viewer.  The time parameter should be a time in
+    nanoseconds, but the exact meaning of the time depends on the native
+    window system's use of the presentation time.  In situations where
+    an absolute time is needed such as displaying the color buffer on a
+    display device, the time should correspond to the system monotonic up-time
+    clock.  For situations in which an absolute time is not needed such as
+    using the color buffer for video encoding, the presentation time of the
+    first frame may be arbitrarily chosen and those of subsequent frames
+    chosen relative to that of the first frame.
+
+    The presentation time may be set multiple times, with each call to
+    eglPresentationTimeANDROID overriding prior calls.  Setting the
+    presentation time alone does not cause the color buffer to be made
+    visible, but if the color buffer is subsequently posted to a native window
+    or copied to a native pixmap then the presentation time of the surface at
+    that time may be passed along for the native window system to use.
+
+    If the surface presentation time is successfully set, EGL_TRUE is
+    returned.  Otherwise EGL_FALSE is returned and an appropriate error is
+    set.
+
+Issues
+
+    1. How is the presentation time used?
+
+    RESOLVED: The uses of the presentation time are intentionally not specified
+    in this extension.  Some possible uses include Audio/Video synchronization,
+    video frame timestamps for video encoding, display latency metrics, and
+    display latency control.
+
+    2. How can the current value of the clock that should be used for the
+    presentation time when an absolute time is needed be queried on Android?
+
+    RESOLVED: The current clock value can be queried from the Java
+    SystemClock#uptimeMillis() method or from the native clock_gettime
+    function by passing CLOCK_MONOTONIC as the clock identifier.
+
+Revision History
+
+#1 (Jamie Gennis, April 1, 2013)
+    - Clarified how uses that either do or do not need an absolute time should
+      be handled.
+    - Specified the eglPresentationTimeANDROID return value.
+
+#1 (Jamie Gennis, January 8, 2013)
+    - Initial draft.