blob: e1dab3425e289280c13a246df7d647a6a7546b43 [file] [log] [blame]
Name
ANDROID_presentation_time
Name Strings
EGL_ANDROID_presentation_time
Contributors
Jamie Gennis
Andy McFadden
Jesse Hall
Contact
Jamie Gennis, Google Inc. (jgennis 'at' google.com)
Status
Draft
Version
Version 3, June 26, 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. If <dpy> is not the name of a valid, initialized EGLDisplay, an
EGL_BAD_DISPLAY error is generated. If <surface> is not a valid EGLSurface
then an EGL_BAD_SURFACE error is generated.
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
System.nanoTime() method, or from the native clock_gettime function by
passing CLOCK_MONOTONIC as the clock identifier.
3. Should the presentation time be state which is used by eglSwapBuffers,
or should it be a new parameter to an extended variant of eglSwapBuffers?
RESOLVED: The presentation time should be new state which is used by
the existing eglSwapBuffers call. Adding new state composes better with
other (hypothetical) extensions that also modify the behavior of
eglSwapBuffers.
Revision History
#3 (Jesse Hall, June 26, 2013)
- Enumerated errors generated by eglPresentationTimeANDROID.
- Added Issue #3 with resolution.
#2 (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.