EGL_ANDROID_presentation_time: initial spec draft
Change-Id: I1cd174a08c499e5bde19e7ecd449da8266e7e66e
diff --git a/opengl/specs/EGL_ANDROID_presentation_time.txt b/opengl/specs/EGL_ANDROID_presentation_time.txt
new file mode 100644
index 0000000..03370ed
--- /dev/null
+++ b/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.