Jamie Gennis | 6730acb | 2013-01-08 18:07:17 -0800 | [diff] [blame] | 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 |
Jesse Hall | 5ac6c0a | 2013-06-26 07:50:32 -0700 | [diff] [blame] | 13 | Jesse Hall |
Jamie Gennis | 6730acb | 2013-01-08 18:07:17 -0800 | [diff] [blame] | 14 | |
| 15 | Contact |
| 16 | |
| 17 | Jamie Gennis, Google Inc. (jgennis 'at' google.com) |
| 18 | |
| 19 | Status |
| 20 | |
| 21 | Draft |
| 22 | |
| 23 | Version |
| 24 | |
Jesse Hall | 5ac6c0a | 2013-06-26 07:50:32 -0700 | [diff] [blame] | 25 | Version 3, June 26, 2013 |
Jamie Gennis | 6730acb | 2013-01-08 18:07:17 -0800 | [diff] [blame] | 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 |
Jesse Hall | 5ac6c0a | 2013-06-26 07:50:32 -0700 | [diff] [blame] | 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. |
Jamie Gennis | 6730acb | 2013-01-08 18:07:17 -0800 | [diff] [blame] | 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 |
Andy McFadden | 0e77569 | 2013-04-26 11:17:57 -0700 | [diff] [blame] | 113 | System.nanoTime() method, or from the native clock_gettime function by |
| 114 | passing CLOCK_MONOTONIC as the clock identifier. |
Jamie Gennis | 6730acb | 2013-01-08 18:07:17 -0800 | [diff] [blame] | 115 | |
Jesse Hall | 5ac6c0a | 2013-06-26 07:50:32 -0700 | [diff] [blame] | 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 | |
Jamie Gennis | 6730acb | 2013-01-08 18:07:17 -0800 | [diff] [blame] | 124 | Revision History |
| 125 | |
Jesse Hall | 5ac6c0a | 2013-06-26 07:50:32 -0700 | [diff] [blame] | 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) |
Jamie Gennis | 6730acb | 2013-01-08 18:07:17 -0800 | [diff] [blame] | 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. |