xref: /third_party/EGL/extensions/ANDROID/EGL_ANDROID_presentation_time.txt

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 4, June 6, 2016

Number

    EGL Extension #98

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 surface,
                        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

#4 (Jon Leech, June 6, 2016)
    - Clean up for publication. Make prototype parameter name 'surface'
      match the spec body.

#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.