blob: 9b72af40b42b2b905e3745a211518df8106f3da8 [file] [log] [blame]
Name Strings
Alon Or-bach
John Carmack
Cass Everitt
Michael Gold
James Jones
Jesse Hall
Ray Smith
Alon Or-bach, Samsung Electronics (alon.orbach 'at'
IP Status
No known claims.
Copyright (c) 2016 The Khronos Group Inc. Copyright terms at
Approved by the EGL Working Group on January 28, 2016
Ratified by the Khronos Board of Promoters on March 11, 2016
Version 12, January 29, 2016
EGL Extension #96
Extension Type
EGL display extension
EGL 1.2 or later is required.
Written based on the EGL 1.5 specification (August 27, 2014).
New Types
New Procedures and Functions
New Tokens
Accepted as a new value for the EGL_SURFACE_TYPE EGLConfig attribute:
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:
EGL_RENDER_BUFFER attribute of a surface can be toggled between front
buffer and back buffer rendering using eglSurfaceAttrib (see section
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, 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
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 "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.
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
3) How often do we expect the switch between single and back buffering to
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
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
RESOLVED: This is as set out in section
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
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 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 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 to reflect this
- Added new issue 11 to reflect concerns about interactions between multiple
- 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, 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