1Name 2 3 KHR_mutable_render_buffer 4 5Name Strings 6 7 EGL_KHR_mutable_render_buffer 8 9Contributors 10 11 Alon Or-bach 12 John Carmack 13 Cass Everitt 14 Michael Gold 15 James Jones 16 Jesse Hall 17 Ray Smith 18 19Contact 20 21 Alon Or-bach, Samsung Electronics (alon.orbach 'at' samsung.com) 22 23IP Status 24 25 No known claims. 26 27Notice 28 29 Copyright (c) 2016 The Khronos Group Inc. Copyright terms at 30 http://www.khronos.org/registry/speccopyright.html 31 32Status 33 34 Approved by the EGL Working Group on January 28, 2016 35 Ratified by the Khronos Board of Promoters on March 11, 2016 36 37Version 38 39 Version 12, January 29, 2016 40 41Number 42 43 EGL Extension #96 44 45Extension Type 46 47 EGL display extension 48 49Dependencies 50 51 EGL 1.2 or later is required. 52 53 Written based on the EGL 1.5 specification (August 27, 2014). 54 55New Types 56 57 None 58 59New Procedures and Functions 60 61 None 62 63New Tokens 64 65 Accepted as a new value for the EGL_SURFACE_TYPE EGLConfig attribute: 66 67 EGL_MUTABLE_RENDER_BUFFER_BIT_KHR 0x00001000 68 69Overview 70 71 The aim of this extension is to allow toggling of front-buffer rendering 72 for window surfaces after their initial creation. 73 74 This allows for implementations to switch between back-buffered and single- 75 buffered rendering without requiring re-creation of the surface. It is not 76 expected for toggling to be a frequent event. 77 78 This extension does not guarantee when rendering results appear on-screen. 79 To avoid incorrect results, applications will need to use mechanisms not 80 included in this extension to synchronize rendering with the display. This 81 functionality is not covered by this extension, and vendors are encouraged 82 to provide guidelines on how this is achieved on their implementation. 83 84Add to the list of supported tokens for EGL_SURFACE_TYPE in section 3.4 85"Configuration Management", page 23: 86 87 If EGL_MUTABLE_RENDER_BUFFER_BIT_KHR is set in EGL_SURFACE_TYPE, then the 88 EGL_RENDER_BUFFER attribute of a surface can be toggled between front 89 buffer and back buffer rendering using eglSurfaceAttrib (see section 90 3.5.6). 91 92Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6 93"Surface Attributes", page 43: 94 95 If attribute is EGL_RENDER_BUFFER, then value specifies whether to render 96 to a back buffer by specifying EGL_BACK_BUFFER, or directly to the front 97 buffer by specifying EGL_SINGLE_BUFFER. The change to which buffer is 98 rendered to takes effect at the subsequent eglSwapBuffers call, as 99 described in section 3.10.1.2, and changes are considered pending up until 100 that point. 101 102 If attribute is EGL_RENDER_BUFFER, and the EGL_SURFACE_TYPE attribute of 103 the EGLConfig used to create surface does not contain 104 EGL_MUTABLE_RENDER_BUFFER_BIT_KHR, or the windowing system is unable to 105 support the requested rendering mode, an EGL_BAD_MATCH error is generated 106 and the EGL_RENDER_BUFFER state is left unchanged. 107 108Modify the following sentence in section 3.5.6 "Surface Attributes", page 45: 109 110 Querying EGL_RENDER_BUFFER returns the buffer which client API rendering 111 is requested to use. For a window surface, this is the attribute value 112 specified when the surface was created or last set via eglSurfaceAttrib. 113 114Modify the third bullet describing eglQueryContext in section 3.7.4, page 63: 115 116 If the context is bound to a window surface, then either EGL_BACK_BUFFER 117 or EGL_SINGLE_BUFFER may be returned. The value returned depends on 118 both the buffer requested by the setting of the EGL_RENDER_BUFFER property 119 of the surface (which may be queried by calling eglQuerySurface - see 120 section 3.5.6), and on the client API (not all client APIs support 121 single-buffer rendering to window surfaces). Some client APIs allow control 122 of whether rendering goes to the front or back buffer for back buffered 123 surfaces. This client API-specific choice is not reflected in the returned 124 value, which only describes the buffer that will be rendered to by default 125 if not overridden by the client API. If the EGL_RENDER_BUFFER attribute of 126 a surface is changed by calling eglSurfaceAttrib, the value returned by 127 eglQueryContext will change once eglSwapBuffers is called, as described in 128 section 3.10.1.2. 129 130Modify the following sentence in section 3.10.1 "Posting to a Window", page 79: 131 132 If surface is a single-buffered window, pixmap, or pbuffer surface for which 133 there is a pending change to the EGL_RENDER_BUFFER attribute, eglSwapBuffers 134 performs an implicit flush operation on the context and effects the 135 attribute change. If surface is a single-buffered window, pixmap, or pbuffer 136 surface for which there is no pending change to the EGL_RENDER_BUFFER 137 attribute, eglSwapBuffers has no effect. 138 139Add a new section 3.10.1.2 "Handling of render buffer attribute changes" 140 141 If there is a pending change to the EGL_RENDER_BUFFER attribute of a 142 surface, as described in section 3.5.6, the change to which buffer is 143 rendered to takes effect at the subsequent eglSwapBuffers call. 144 145 When switching to single-buffered from back-buffered rendering and the 146 surface's EGL_SWAP_BEHAVIOR attribute is set to EGL_BUFFER_DESTROYED, the 147 back buffers are considered to be undefined after calling eglSurfaceAttrib. 148 Only draw calls after this eglSurfaceAttrib call are guaranteed to affect 149 the back buffer content. If it is set to EGL_BUFFER_PRESERVED, the back 150 buffer contents are unaffected. At the next eglSwapBuffers call, the back 151 buffer is posted as the front buffer. After this, any draw calls take 152 effect on the front buffer. 153 154 When switching to back-buffered from single-buffered rendering, any draw 155 calls up until the next eglSwapBuffers call continues to affect the front 156 buffer, and this initial eglSwapBuffers call does not affect the window 157 content. The back buffer is considered to be undefined at this point, no 158 matter what the EGL_SWAP_BEHAVIOR attribute of the surface is set to. Once 159 the pending change has taken place during this initial eglSwapBuffers call, 160 further rendering affects the back buffer. 161 162 If the EGL_RENDER_BUFFER attribute is changed twice or more in succession 163 without new content rendered to the surface as described above, undefined 164 content may appear on-screen. 165 166 167Issues 168 169 1) When should the switch between rendering modes occur? 170 171 RESOLVED: The switch should take effect after the subsequent eglSwapBuffers 172 call. The operation of the subsequent eglSwapBuffers call is according to 173 the current state (i.e the state before the eglSurfaceAttrib call), not the 174 pending state. 175 176 When switching to EGL_SINGLE_BUFFER, the current state is EGL_BACK_BUFFER 177 and therefore eglSwapBuffers posts the current back buffer. After this any 178 rendering takes effect on the front buffer. 179 180 When switching to EGL_BACK_BUFFER, the current state is EGL_SINGLE_BUFFER 181 and therefore eglSwapBuffers only flushes the current context. After this 182 any rendering takes effect on the back buffer. 183 184 2) If this extension is advertised, should all surface configurations with 185 EGL_WINDOW_BIT in EGL_SURFACE_TYPE be required to support it? 186 187 RESOLVED: No. Add a config bit to indicate support for EGL_RENDER_BUFFER 188 toggling. If toggle performed when not supported, EGL_BAD_MATCH error is 189 generated. 190 191 3) How often do we expect the switch between single and back buffering to 192 occur? 193 194 RESOLVED: It is not expected for the toggle to be a frequent call. For 195 example, we expect it to be called once when enabling a VR accessory and 196 once when disabling it. 197 198 4) Do we need to reword section 3.7.4 (page 63)? 199 200 RESOLVED: Yes. Modified to explain how some client APIs can still override 201 the behavior and what value eglQueryContext is expected to return for 202 EGL_RENDER_BUFFER. 203 204 5) Why not enable this via the client API, like OpenGL does via glDrawBuffer? 205 206 RESOLVED: This would not be possible on some platforms, where the swap chain 207 is controlled via EGL. 208 209 6) Is this extension a client or display extension? 210 211 RESOLVED: This is a display extension. 212 213 7) What state are back buffers after switching between single and back buffered 214 rendering? 215 216 RESOLVED: This is as set out in section 3.10.1.2. 217 218 8) What guarantees of an onscreen update does this extension make? 219 220 RESOLVED: This extension does not make any additional guarantees to the 221 equivalent behavior of a window surface with EGL_RENDER_BUFFER set to the 222 same value at creation of the surface. When a surface is single-buffered, 223 any API call which is specified to explicitly or implicitly flush is 224 expected to affect the on-screen content in finite time, but no timing 225 guarantees are provided. 226 227 It is recommended that if ancillary buffers are not required, they are 228 invalidated before flushing to reduce unnecessary memory transfers on some 229 implementations (e.g. by calling glInvalidateFramebuffer for OpenGL ES). 230 231 9) Should an implicit flush occur when eglSwapBuffers is called on a 232 single-buffered surface? 233 234 RESOLVED: Only when there is a pending EGL_RENDER_BUFFER change which will 235 be affected by this eglSwapBuffers call. Contexts must be flushed when 236 changing render targets. 237 238 10) How does toggling EGL_RENDER_BUFFER affect client APIs? 239 240 RESOLVED: Changing the value of EGL_RENDER_BUFFER should result in the same 241 behavior in client APIs as binding a window surface with that mode to the 242 current context. For example, in OpenGL, it is akin to switching from a 243 drawable with a back buffer and front buffer to a drawable with only a 244 front buffer, or vice versa. 245 246 Note the effect of such an operation on the draw buffer and framebuffer 247 completeness, if applicable, is client API specific. OpenGL ES applications 248 will see no change and will be able to continue rendering without updating 249 the draw buffer, as OpenGL ES exposes only one renderable surface, 250 regardless of single or back-buffered drawables. OpenGL applications should 251 update the current draw buffer using glDrawBuffers() or similar commands to 252 ensure rendering targets the correct buffer after toggling 253 EGL_RENDER_BUFFER. 254 255 11) How should interaction between multiple window surfaces be handled? 256 257 RESOLVED: This is left to platform vendors to define. Implementations may 258 choose to restrict use of front buffer rendering to forbid interaction 259 between multiple windows, or provide a buffer that is read by the display 260 or compositing hardware but not the final composited results to prevent 261 security concerns or undefined content. 262 263 12) How should the name of the extension be? 264 265 RESOLVED: EGL_KHR_mutable_render_buffer 266 267 268Revision History 269 270#12 (Jon Leech, January 29, 2016) 271 - Assign enumerant value 272 - Update Status block 273 274#11 (Alon Or-bach, January 28, 2016) 275 - Updated issue 1 to be consistent with new resolution to issue 9 276 - Marked issues 7, 8 and 10 as resolved 277 278#10 (Alon Or-bach, January 28, 2016) 279 - Renamed extension to EGL_KHR_mutable_render_buffer, resolving issue 12 280 - Updates issue 7 resolution to just refer to spec 281 - Cleaned up section 3.10.1.2 wording 282 - Added wording to overview on lack of guarantee of rendering results 283 284#9 (Alon Or-bach, January 22, 2016) 285 - Marked issues 1, 9 and 11 as resolved 286 - Updated issue 4 to reflect previously agreed wording for section 3.7.4 287 - Updated issue 8 to indicate no new flush guarantees made by this extension 288 - New proposed resolution to issue 7 and modified section 3.10.1.2 to vary 289 whether back buffer content are undefined based on swap behavior 290 - Updated issue 10 with wording to explain differing client API behaviors 291 - Added error condition for windowing systems unable to support a requested 292 rendering mode in section 3.5.6 293 - New proposed resolution to issue 12 for extension naming 294 - Minor updates to wording (attribute instead of mode, overview phrasing) 295 296#8 (Ray Smith, January 5, 2016) 297 - Revert issue 1 resolution to that in revision 6, adding wording to section 298 3.10.1 to make eglSwapBuffers effect pending state changes even for single 299 buffered surfaces. 300 301#7 (Alon Or-bach, December 17, 2015) 302 - New proposed resolution to issue 1 (explicit flush as update boundary), 303 updating the wording of 3.5.6, 3.7.4 3.10.1.2 to reflect this 304 - Added new issue 11 to reflect concerns about interactions between multiple 305 windows 306 - Added new issue 12 to determine extension name 307 308#6 (Alon Or-bach, November 11, 2015) 309 - Resolved issue 6 and proposed resolution to issue 4 (section 3.7.4) 310 - Added new issue 10 with proposed resolution 311 312#5 (Alon Or-bach, May 12, 2015) 313 - Updated section 3.10.1.2, changed resolution to issue 9 314 315#4 (Alon Or-bach, April 15, 2015) 316 - Added issue 9 and a typo fix 317 318#3 (Alon Or-bach, April 09, 2015) 319 - Added issue 7 and 8, wording on what content expected during mode switch 320 321#2 (Alon Or-bach, March 09, 2015) 322 - Cleanup, rename to XXX_set_render_buffer_mode 323 324#1 (Alon Or-bach, March 04, 2015) 325 - Initial draft 326