xref: /third_party/EGL/extensions/KHR/EGL_KHR_mutable_render_buffer.txt

Name

    KHR_mutable_render_buffer

Name Strings

    EGL_KHR_mutable_render_buffer

Contributors

    Alon Or-bach
    John Carmack
    Cass Everitt
    Michael Gold
    James Jones
    Jesse Hall
    Ray Smith

Contact

    Alon Or-bach, Samsung Electronics (alon.orbach 'at' samsung.com)

IP Status

    No known claims.

Notice

    Copyright (c) 2016 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

Status

    Approved by the EGL Working Group on January 28, 2016
    Ratified by the Khronos Board of Promoters on March 11, 2016

Version

    Version 12, January 29, 2016

Number

    EGL Extension #96

Extension Type

    EGL display extension

Dependencies

    EGL 1.2 or later is required.

    Written based on the EGL 1.5 specification (August 27, 2014).

New Types

    None

New Procedures and Functions

    None

New Tokens

    Accepted as a new value for the EGL_SURFACE_TYPE EGLConfig attribute:

        EGL_MUTABLE_RENDER_BUFFER_BIT_KHR           0x00001000

Overview

    The aim of this extension is to allow toggling of front-buffer rendering
    for window surfaces after their initial creation.

    This allows for implementations to switch between back-buffered and single-
    buffered rendering without requiring re-creation of the surface. It is not
    expected for toggling to be a frequent event.

    This extension does not guarantee when rendering results appear on-screen.
    To avoid incorrect results, applications will need to use mechanisms not
    included in this extension to synchronize rendering with the display. This
    functionality is not covered by this extension, and vendors are encouraged
    to provide guidelines on how this is achieved on their implementation.

Add to the list of supported tokens for EGL_SURFACE_TYPE in section 3.4
"Configuration Management", page 23:

    If EGL_MUTABLE_RENDER_BUFFER_BIT_KHR is set in EGL_SURFACE_TYPE, then the
    EGL_RENDER_BUFFER attribute of a surface can be toggled between front
    buffer and back buffer rendering using eglSurfaceAttrib (see section
    3.5.6).

Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6
"Surface Attributes", page 43:

    If attribute is EGL_RENDER_BUFFER, then value specifies whether to render
    to a back buffer by specifying EGL_BACK_BUFFER, or directly to the front
    buffer by specifying EGL_SINGLE_BUFFER. The change to which buffer is
    rendered to takes effect at the subsequent eglSwapBuffers call, as
    described in section 3.10.1.2, and changes are considered pending up until
    that point.

    If attribute is EGL_RENDER_BUFFER, and the EGL_SURFACE_TYPE attribute of
    the EGLConfig used to create surface does not contain
    EGL_MUTABLE_RENDER_BUFFER_BIT_KHR, or the windowing system is unable to
    support the requested rendering mode, an EGL_BAD_MATCH error is generated
    and the EGL_RENDER_BUFFER state is left unchanged.

Modify the following sentence in section 3.5.6 "Surface Attributes", page 45:

    Querying EGL_RENDER_BUFFER returns the buffer which client API rendering
    is requested to use. For a window surface, this is the attribute value
    specified when the surface was created or last set via eglSurfaceAttrib.

Modify the third bullet describing eglQueryContext in section 3.7.4, page 63:

    If the context is bound to a window surface, then either EGL_BACK_BUFFER
    or EGL_SINGLE_BUFFER may be returned. The value returned depends on
    both the buffer requested by the setting of the EGL_RENDER_BUFFER property
    of the surface (which may be queried by calling eglQuerySurface - see
    section 3.5.6), and on the client API (not all client APIs support
    single-buffer rendering to window surfaces). Some client APIs allow control
    of whether rendering goes to the front or back buffer for back buffered
    surfaces. This client API-specific choice is not reflected in the returned
    value, which only describes the buffer that will be rendered to by default
    if not overridden by the client API. If the EGL_RENDER_BUFFER attribute of
    a surface is changed by calling eglSurfaceAttrib, the value returned by
    eglQueryContext will change once eglSwapBuffers is called, as described in
    section 3.10.1.2.

Modify the following sentence in section 3.10.1 "Posting to a Window", page 79:

    If surface is a single-buffered window, pixmap, or pbuffer surface for which
    there is a pending change to the EGL_RENDER_BUFFER attribute, eglSwapBuffers
    performs an implicit flush operation on the context and effects the
    attribute change. If surface is a single-buffered window, pixmap, or pbuffer
    surface for which there is no pending change to the EGL_RENDER_BUFFER
    attribute, eglSwapBuffers has no effect.

Add a new section 3.10.1.2 "Handling of render buffer attribute changes"

    If there is a pending change to the EGL_RENDER_BUFFER attribute of a
    surface, as described in section 3.5.6, the change to which buffer is
    rendered to takes effect at the subsequent eglSwapBuffers call.

    When switching to single-buffered from back-buffered rendering and the
    surface's EGL_SWAP_BEHAVIOR attribute is set to EGL_BUFFER_DESTROYED, the
    back buffers are considered to be undefined after calling eglSurfaceAttrib.
    Only draw calls after this eglSurfaceAttrib call are guaranteed to affect
    the back buffer content. If it is set to EGL_BUFFER_PRESERVED, the back
    buffer contents are unaffected. At the next eglSwapBuffers call, the back
    buffer is posted as the front buffer. After this, any draw calls take
    effect on the front buffer.

    When switching to back-buffered from single-buffered rendering, any draw
    calls up until the next eglSwapBuffers call continues to affect the front
    buffer, and this initial eglSwapBuffers call does not affect the window
    content. The back buffer is considered to be undefined at this point, no
    matter what the EGL_SWAP_BEHAVIOR attribute of the surface is set to. Once
    the pending change has taken place during this initial eglSwapBuffers call,
    further rendering affects the back buffer.

    If the EGL_RENDER_BUFFER attribute is changed twice or more in succession
    without new content rendered to the surface as described above, undefined
    content may appear on-screen.


Issues

 1) When should the switch between rendering modes occur?

    RESOLVED: The switch should take effect after the subsequent eglSwapBuffers
    call. The operation of the subsequent eglSwapBuffers call is according to
    the current state (i.e the state before the eglSurfaceAttrib call), not the
    pending state.

    When switching to EGL_SINGLE_BUFFER, the current state is EGL_BACK_BUFFER
    and therefore eglSwapBuffers posts the current back buffer. After this any
    rendering takes effect on the front buffer.

    When switching to EGL_BACK_BUFFER, the current state is EGL_SINGLE_BUFFER
    and therefore eglSwapBuffers only flushes the current context. After this
    any rendering takes effect on the back buffer.

 2) If this extension is advertised, should all surface configurations with
    EGL_WINDOW_BIT in EGL_SURFACE_TYPE be required to support it?

    RESOLVED: No. Add a config bit to indicate support for EGL_RENDER_BUFFER
    toggling. If toggle performed when not supported, EGL_BAD_MATCH error is
    generated.

 3) How often do we expect the switch between single and back buffering to
    occur?

    RESOLVED: It is not expected for the toggle to be a frequent call. For
    example, we expect it to be called once when enabling a VR accessory and
    once when disabling it.

 4) Do we need to reword section 3.7.4 (page 63)?

    RESOLVED: Yes. Modified to explain how some client APIs can still override
    the behavior and what value eglQueryContext is expected to return for
    EGL_RENDER_BUFFER.

 5) Why not enable this via the client API, like OpenGL does via glDrawBuffer?

    RESOLVED: This would not be possible on some platforms, where the swap chain
    is controlled via EGL.

 6) Is this extension a client or display extension?

    RESOLVED: This is a display extension.

 7) What state are back buffers after switching between single and back buffered
    rendering?

    RESOLVED: This is as set out in section 3.10.1.2.

 8) What guarantees of an onscreen update does this extension make?

    RESOLVED: This extension does not make any additional guarantees to the
    equivalent behavior of a window surface with EGL_RENDER_BUFFER set to the
    same value at creation of the surface. When a surface is single-buffered,
    any API call which is specified to explicitly or implicitly flush is
    expected to affect the on-screen content in finite time, but no timing
    guarantees are provided.

    It is recommended that if ancillary buffers are not required, they are
    invalidated before flushing to reduce unnecessary memory transfers on some
    implementations (e.g. by calling glInvalidateFramebuffer for OpenGL ES).

 9) Should an implicit flush occur when eglSwapBuffers is called on a
    single-buffered surface?

    RESOLVED: Only when there is a pending EGL_RENDER_BUFFER change which will
    be affected by this eglSwapBuffers call. Contexts must be flushed when
    changing render targets.

 10) How does toggling EGL_RENDER_BUFFER affect client APIs?

    RESOLVED: Changing the value of EGL_RENDER_BUFFER should result in the same
    behavior in client APIs as binding a window surface with that mode to the
    current context.  For example, in OpenGL, it is akin to switching from a
    drawable with a back buffer and front buffer to a drawable with only a
    front buffer, or vice versa.

    Note the effect of such an operation on the draw buffer and framebuffer
    completeness, if applicable, is client API specific. OpenGL ES applications
    will see no change and will be able to continue rendering without updating
    the draw buffer, as OpenGL ES exposes only one renderable surface,
    regardless of single or back-buffered drawables. OpenGL applications should
    update the current draw buffer using glDrawBuffers() or similar commands to
    ensure rendering targets the correct buffer after toggling
    EGL_RENDER_BUFFER.

 11) How should interaction between multiple window surfaces be handled?

    RESOLVED: This is left to platform vendors to define. Implementations may
    choose to restrict use of front buffer rendering to forbid interaction
    between multiple windows, or provide a buffer that is read by the display
    or compositing hardware but not the final composited results to prevent
    security concerns or undefined content.

 12) How should the name of the extension be?

    RESOLVED: EGL_KHR_mutable_render_buffer


Revision History

#12 (Jon Leech, January 29, 2016)
   - Assign enumerant value
   - Update Status block

#11 (Alon Or-bach, January 28, 2016)
   - Updated issue 1 to be consistent with new resolution to issue 9
   - Marked issues 7, 8 and 10 as resolved

#10 (Alon Or-bach, January 28, 2016)
   - Renamed extension to EGL_KHR_mutable_render_buffer, resolving issue 12
   - Updates issue 7 resolution to just refer to spec
   - Cleaned up section 3.10.1.2 wording
   - Added wording to overview on lack of guarantee of rendering results

#9 (Alon Or-bach, January 22, 2016)
   - Marked issues 1, 9 and 11 as resolved
   - Updated issue 4 to reflect previously agreed wording for section 3.7.4
   - Updated issue 8 to indicate no new flush guarantees made by this extension
   - New proposed resolution to issue 7 and modified section 3.10.1.2 to vary
     whether back buffer content are undefined based on swap behavior
   - Updated issue 10 with wording to explain differing client API behaviors
   - Added error condition for windowing systems unable to support a requested
     rendering mode in section 3.5.6
   - New proposed resolution to issue 12 for extension naming
   - Minor updates to wording (attribute instead of mode, overview phrasing)

#8 (Ray Smith, January 5, 2016)
   - Revert issue 1 resolution to that in revision 6, adding wording to section
     3.10.1 to make eglSwapBuffers effect pending state changes even for single
     buffered surfaces.

#7 (Alon Or-bach, December 17, 2015)
   - New proposed resolution to issue 1 (explicit flush as update boundary),
     updating the wording of 3.5.6, 3.7.4 3.10.1.2 to reflect this
   - Added new issue 11 to reflect concerns about interactions between multiple
     windows
   - Added new issue 12 to determine extension name

#6 (Alon Or-bach, November 11, 2015)
   - Resolved issue 6 and proposed resolution to issue 4 (section 3.7.4)
   - Added new issue 10 with proposed resolution

#5 (Alon Or-bach, May 12, 2015)
   - Updated section 3.10.1.2, changed resolution to issue 9

#4 (Alon Or-bach, April 15, 2015)
   - Added issue 9 and a typo fix

#3 (Alon Or-bach, April 09, 2015)
   - Added issue 7 and 8, wording on what content expected during mode switch

#2 (Alon Or-bach, March 09, 2015)
   - Cleanup, rename to XXX_set_render_buffer_mode

#1 (Alon Or-bach, March 04, 2015)
   - Initial draft