EGL_ANDROID_presentation_time.txt revision 5ac6c0a3ddbd4ff7680ba57c092c435d68eb9c13 
1Name
2
3    ANDROID_presentation_time
4
5Name Strings
6
7    EGL_ANDROID_presentation_time
8
9Contributors
10
11    Jamie Gennis
12    Andy McFadden
13    Jesse Hall
14
15Contact
16
17    Jamie Gennis, Google Inc. (jgennis 'at' google.com)
18
19Status
20
21    Draft
22
23Version
24
25    Version 3, June 26, 2013
26
27Number
28
29    EGL Extension #XXX
30
31Dependencies
32
33    Requires EGL 1.1
34
35    This extension is written against the wording of the EGL 1.4 Specification
36
37Overview
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
44New 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
54New Procedures and Functions
55
56    EGLboolean eglPresentationTimeANDROID(
57                        EGLDisplay dpy,
58                        EGLSurface sur,
59                        EGLnsecsANDROID time);
60
61New Tokens
62
63    None.
64
65Changes 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
100Issues
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
124Revision 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