1Name 2 3 EXT_swap_buffers_with_damage 4 5Name Strings 6 7 EGL_EXT_swap_buffers_with_damage 8 9IP Status 10 11 No known IP claims. 12 13Contributors 14 15 Robert Bragg 16 Tapani Pälli 17 Kristian Høgsberg 18 Benjamin Franzke 19 Ian Stewart 20 James Jones 21 22Contacts 23 24 Robert Bragg, Intel (robert.bragg 'at' intel.com) 25 26Status 27 28 Published 29 30Version 31 32 Version 11, February 20, 2020 33 34Number 35 36 EGL Extension #55 37 38Dependencies 39 40 Requires EGL 1.4 41 42 This extension is written against the wording of the EGL 1.4 43 Specification. 44 45Overview 46 47 This extension provides a means to issue a swap buffers request to 48 display the contents of the current back buffer and also specify a 49 list of damage rectangles that can be passed to a system 50 compositor so it can minimize how much it has to recompose. 51 52 This should be used in situations where an application is only 53 animating a small portion of a surface since it enables the 54 compositor to avoid wasting time recomposing parts of the surface 55 that haven't changed. 56 57New Procedures and Functions 58 59 EGLBoolean eglSwapBuffersWithDamageEXT ( 60 EGLDisplay dpy, 61 EGLSurface surface, 62 const EGLint *rects, 63 EGLint n_rects); 64 65New Tokens 66 67 None 68 69Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) 70 71 Add the following text to subsection 3.9.1 titled "Posting to a 72 Window" after the description of eglSwapBuffers. 73 74 As an alternative to eglSwapBuffers use: 75 76 EGLBoolean eglSwapBuffersWithDamageEXT ( 77 EGLDisplay dpy, 78 EGLSurface surface, 79 const EGLint *rects, 80 EGLint n_rects); 81 82 to do the same thing as eglSwapBuffers but additionally report 83 a list of rectangles that define the region that has truly 84 changed since the last frame. To be clear; the entire contents 85 of the back buffer will still be swapped to the front so 86 applications using this API must still ensure that the entire 87 back buffer is consistent. The rectangles are only a hint for 88 the system compositor so it can avoid recomposing parts of the 89 surface that haven't really changed. 90 <rects> points to a list of integers in groups of four that 91 each describe a rectangle in screen coordinates in this 92 layout: {x, y, width, height}. The rectangles are specified 93 relative to the bottom-left of the surface and the x and y 94 components of each rectangle specify the bottom-left position 95 of that rectangle. <n_rects> determines how many groups of 4 96 integers can be read from <rects>. It is not necessary to 97 avoid overlaps of the specified rectangles. 98 If <n_rects> is 0 then <rects> is ignored and the entire 99 surface is implicitly damaged and the behaviour is equivalent 100 to calling eglSwapBuffers. 101 The error conditions checked for are the same as for the 102 eglSwapBuffers api. 103 104 Modify the first paragraph of Section 3.9.1 titled "Native Window 105 Resizing" 106 107 "If the native window corresponding to <surface> has been 108 resized prior to the swap, <surface> must be resized to match. 109 <surface> will normally be resized by the EGL implementation 110 at the time the native window is resized. If the 111 implementation cannot do this transparently to the client, 112 then eglSwapBuffers and eglSwapBuffersWithDamageEXT must 113 detect the change and resize surface prior to copying its 114 pixels to the native window. In this case the meaningfulness 115 of any damage rectangles forwarded by 116 eglSwapBuffersWithDamageEXT to the native window system is 117 undefined." 118 119 Modify the following sentences in Section 3.9.3, page 51 (Posting 120 Semantics) 121 122 Paragraph 2, first sentence: 123 124 "If <dpy> and <surface> are the display and surface for the 125 calling thread's current context, eglSwapBuffers, 126 eglSwapBuffersWithDamageEXT, and eglCopyBuffers perform an 127 implicit flush operation on the context (glFlush for OpenGL or 128 OpenGL ES context, vgFlush for an OpenVG context)." 129 130 Paragraph 3, first sentence: 131 132 "The destination of a posting operation (a visible window, for 133 eglSwapBuffers or eglSwapBuffersWithDamageEXT, or a native 134 pixmap, for eglCopyBuffers) should have the same number of 135 components and component sizes as the color buffer it's being 136 copied from." 137 138 Paragraph 6, first two sentences: 139 140 "The function 141 142 EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint 143 interval); 144 145 specifies the minimum number of video frame periods per color 146 buffer post operation for the window associated with the 147 current context. The interval takes effect when eglSwapBuffers 148 or eglSwapBuffersWithDamageEXT is first called subsequent to 149 the eglSwapInterval call." 150 151 Modify the following sentences in Section 3.9.4, page 52 (Posting 152 Errors) 153 154 Paragraph 1, first sentence: 155 156 "eglSwapBuffers, eglSwapBuffersWithDamageEXT, and 157 eglCopyBuffers return EGL_FALSE on failure." 158 159 Paragraph 1, seventh sentence: 160 161 "If eglSwapBuffers or eglSwapBuffersWithDamageEXT are called 162 and the native window associated with <surface> is no longer 163 valid, an EGL_BAD_NATIVE_WINDOW error is generated. If 164 eglSwapBuffersWithDamageEXT is called and <n_rects>, is less 165 than zero or <n_rects> is greater than zero but <rects> is 166 NULL, EGL_BAD_PARAMETER is generated." 167 168Dependencies on OpenGL ES 169 170 None 171 172Dependencies on OpenVG 173 174 None 175 176Issues 177 1781) Do applications have to make sure the rectangles don't overlap? 179 180 RESOLVED: No, that would be inconvenient for applications and we 181 see no difficulty for implementations to supporting overlapping 182 rectangles. 183 1842) Would it be valid for an implementation to discard the list of 185 rectangles internally and work just in terms of the 186 eglSwapBuffers api? 187 188 RESOLVED: Yes, the rectangles are only there for optimization 189 purposes so although it wouldn't be beneficial to applications if 190 it was convenient at times then it would be compliant for an 191 implementation to discard the rectangles and just call 192 eglSwapBuffers instead. The error conditions that should be 193 checked for are compatible with the requirements for 194 eglSwapBuffers. 195 1963) What origin should be used for damage rectangles? 197 198 RESOLVED: Bottom left since this is consistent with all other 199 uses of 2D window coordinates in EGL and OpenGL that specify a 200 bottom left origin. 201 202 Originally this specification was written with a top-left origin 203 for the damage rectangles even though it was known to be 204 inconsistent and that was because most window systems use a 205 top-left origin and there are some awkward semantic details 206 related to handling native window resizing that we had hoped to 207 simplify. 208 209 This extension and also several other existing EGL extensions 210 struggle to guarantee a reliable behaviour in response to native 211 window resizing which can happen asynchronously on some platforms 212 and this can make it difficult for applications to avoid certain 213 visual artefacts. 214 215 The crux of the problem is that when a native window is 216 asynchronously resized then the window system may maintain the old 217 buffer contents with respect to a different origin than EGL's 218 bottom left origin. For this extension that means that EGL damage 219 rectangles that are intended to map to specific surface contents 220 may end up mapping to different contents when a native window is 221 resized because the rectangles and buffer contents will be moved in 222 different directions in relation to the new window size. 223 224 In the end we decided that this issue isn't simply solved by 225 choosing to use a top-left origin and so we can instead aim for 226 consistency and clarify what guarantees we offer in relation to 227 native window resizing separate from this issue. 228 2294) What guarantees do we provide about the meaningfulness of EGL 230 damage rectangles that are forwarded to the native window system 231 when presenting to a native window that has been resized? 232 233 RESOLVED: The meaningfulness of those forwarded damage rectangles 234 is undefined since this simplifies the implementation requirements 235 and we saw very little benefit to applications from providing 236 stricter guarantees. 237 238 The number of applications that would be able to avoid fully 239 redrawing the contents of a window in response to a window resize 240 is expected to be so low that there would be almost no benefit to 241 defining strict guarantees here. 242 243 Since EGL already states that the contents of window surface 244 buffers become undefined when a native window has been resized, 245 this limitation doesn't introduce any new issue for applications 246 to consider. Applications should already fully redraw buffer 247 contents in response to a native window resize, unless they are 248 following some platform specific documentation that provides 249 additional guarantees. 250 251 For an example of the implementation details that make this an 252 awkward issue to provide guarantees for we can consider X11 based 253 platforms where native windows can be resized asynchronously with 254 respect to a client side EGL surface: 255 256 With X11 there may be multiple "gravity" transformations that can 257 affect how surface buffer content is positioned with respect to a 258 new native window size; there is the core X "bit gravity" and 259 there is the EGL driver gravity that determines how a surface's 260 contents with one size should be mapped to a native window with a 261 different size. Without very careful cooperation between the EGL 262 driver and the core X implementation and without the right 263 architecture to be able to do transforms atomically with respect 264 to different clients that may enact a window resize then it is not 265 possible to reliably map EGL damage rectangles to native window 266 coordinates. 267 268 The disadvantage of a driver that is not able to reliably map EGL 269 damage rectangles to native window coordinates is that a native 270 compositor may re-compose the wrong region of window. This may 271 result in a temporary artefact until the full window gets redrawn 272 and then re-composed. X11 already suffers other similar transient 273 artefacts when resizing windows. 274 275 The authors of this spec believe that even if a driver can't do 276 reliable mappings of EGL damage rectangles then compositors would 277 be able mitigate the majority of related artefacts by ignoring 278 sub-window damage during an interactive window resize. 279 280 The authors of this spec believe that that if an X11 driver did 281 want to reliably map EGL damage rectangles to the native window 282 coordinates then that may be technically feasible depending on the 283 driver architecture. For reference one approach that had been 284 considered (but not tested) is as follows: 285 286 1) When eglSwapBuffersWithDamageEXT is called, send EGL damage 287 rectangles from the client to a driver component within the 288 xserver un-transformed in EGL window surface coordinates with a 289 bottom-left origin. 290 291 2) Within the X server the driver component should look at the 292 bit-gravity of a window and use the bit-gravity convention to 293 copy EGL surface content to the front-buffer of a native window. 294 295 3) Within the X server the driver component should use the same 296 gravity transform that was used to present the surface content 297 to also transform the EGL damage rectangle coordinates. 298 299 Note that because this transform is done in the xserver then 300 this is implicitly synchronized with all clients that would 301 otherwise be able to enact an asynchronous window resize. 302 303 304Revision History 305 306 Version 1, 29/07/2011 307 - First draft 308 Version 2, 03/08/2011 309 - Clarify that the rectangles passed may overlap 310 Version 3, 01/09/2011 311 - Fix a missing '*' in prototype to make rects a pointer 312 Version 4, 11,02,2012 313 - Clarify that implementing in terms of eglSwapBuffers would be 314 compliant. 315 Version 5, 11,02,2012 316 - Tweak the cases where we report BAD_PARAMETER errors 317 Version 6, 05/02/2013 318 - Specify more thorough updates across the EGL 1.4 spec 319 wherever it relates to the eglSwapBuffers api 320 - Clarify that passing <n_rects> of 0 behaves as if 321 eglSwapBuffers were called. 322 Version 7, 14/02/2013 323 - Specify that a bottom-left origin should be used for rectangles 324 Version 8, 19/03/2013 325 - Add Ian and James as contributors 326 - Add an issue explaining why we changed to a bottom-left origin 327 - Clarify that the behaviour is undefined when presenting to a 328 native window that has been resized. 329 - Document the awkward details that would be involved in 330 providing more strict guarantees when presenting to a native 331 window that has been resized. 332 Version 9, 12/06/2013, Chad Versace <chad.versace@intel.com> 333 - Remove the "all rights reserved" clause from the copyright notice. The 334 removal does not change the copyright notice's semantics, since the 335 clause is already implied by any unadorned copyright notice. But, the 336 removal does diminish the likelihood of unwarranted caution in readers 337 of the spec. 338 - Add "IP Status" section to explicitly state that this extension has no 339 knonw IP claims. 340 Version 10, 23/10/2014, Jon Leech 341 - Remove copyright after signoff from Intel. 342 Version 11, 20/02/2020, Jon Leech 343 - Constify rects parameter (EGL-Registry issue 98). 344