diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_mutable_render_buffer.txt')
| -rw-r--r-- | glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_mutable_render_buffer.txt | 325 |
1 files changed, 325 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_mutable_render_buffer.txt b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_mutable_render_buffer.txt new file mode 100644 index 0000000..9b72af4 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_mutable_render_buffer.txt @@ -0,0 +1,325 @@ +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 |