1Name 2 3 EXT_buffer_age 4 5Name Strings 6 7 EGL_EXT_buffer_age 8 9Notice 10 11 Copyright 2011,2012 Intel Cooperation 12 13IP Status 14 15 No known IP claims. 16 17Contributors 18 19 Robert Bragg 20 Neil Roberts 21 Tapani Pälli 22 Kristian Høgsberg 23 Acorn Pooley 24 James Jones 25 26Contacts 27 28 Robert Bragg, Intel (robert.bragg 'at' intel.com) 29 30Status 31 32 Complete. 33 34Version 35 36 12 - June 13, 2013 37 38Number 39 40 EGL Extension #52 41 42Dependencies 43 44 Requires EGL 1.4 45 46 This extension is written against the wording of the EGL 1.4 47 Specification. 48 49Overview 50 51 The aim of this extension is to expose enough information to 52 applications about how the driver manages the set of front and 53 back buffers associated with a given surface to allow applications 54 to re-use the contents of old frames and minimize how much must be 55 redrawn for the next frame. 56 57 There are lots of different ways for a driver to manage these 58 buffers, from double buffering, different styles of triple 59 buffering and even n-buffering or simply single buffer rendering. 60 We also need to consider that power management events or memory 61 pressure events might also result in some of the buffers not 62 currently in-use being freed. 63 64 This extension lets applications query the age of the back buffer 65 contents for an EGL surface as the number of frames elapsed since 66 the contents were most recently defined. The back buffer can 67 either be reported as invalid (has an age of 0) or it may be 68 reported to contain the contents from n frames prior to the 69 current frame. 70 71 Once the application has queried the buffer age, the age of 72 contents remains valid until the end of the frame for all pixels 73 that continue to pass the pixel ownership test. 74 75 For many use-cases this extension can provide an efficient 76 alternative to using the EGL_BUFFER_PRESERVED swap behaviour. The 77 EGL_BUFFER_PRESERVED swap behaviour adds a direct dependency for 78 any frame n on frame n - 1 which can affect the pipelining of 79 multiple frames but also implies a costly copy-back of data to 80 initialize the back-buffer at the start of each frame. 81 82 For example if you consider a double buffered application drawing 83 a small spinning icon, but everything else in the scene is static. 84 If we know that 2 buffers are continuously being recycled each 85 time eglSwapBuffers is called then even though 100s of frames may 86 need to be drawn to animate the icon it can be seen that the two 87 buffers are remaining unchanged except within the bounds of the 88 icon. In this scenario ideally the application would simply 89 perform an incremental update of the old buffer instead of 90 redundantly redrawing all the static parts of the scene. The 91 problem up until now though has been that EGL doesn't report how 92 buffers may be recycled so it wasn't safe for applications to try 93 and reuse their contents. Now applications can keep track of all 94 the regions that have changed over the last n frames and by 95 knowing the age of the buffer they know how to efficiently repair 96 buffers that are re-cycled instead of redrawing the entire scene. 97 98New Procedures and Functions 99 100 None 101 102New Tokens 103 104 EGL_BUFFER_AGE_EXT 0x313D 105 106Additions to Section 2.2 of the EGL 1.4 Specification (Rendering 107Contexts and drawing surfaces) 108 109 Add the following text to a new subsection titled "Pixel 110 Ownership Test" after the subsection titled "Interaction With 111 Native Rendering": 112 113 A fragment produced by a client api through rasterization 114 with windows coordinates (x, y) only modifies the pixel in the 115 rendering surface at that location if it passes the pixel 116 ownership test defined by the native window system. 117 118 The pixel ownership test determines if the pixel at location 119 (x, y) in a rendering surface is currently owned by the client 120 api (more precisely, by this its context). If it is not, the 121 native window system decides the fate of the incoming 122 fragment. Possible results are that the fragment is discarded 123 or that some subset of the subsequent per-fragment operations 124 are applied to the fragment. This test allows the window 125 system to control the client api behavior, for instance, when 126 a window surface is obscured. 127 128 The pixel ownership test can only fail for window surfaces, 129 not for pixmap surfaces or pbuffer surfaces. 130 131 Most native window systems will be able to guarantee that no 132 fragment will ever fail the pixel ownership test, but a 133 notable exception to this is the X11 window system where, 134 depending on the driver, the pixel ownership test may fail 135 when portions of a window are obscured. 136 137Additions to Section 3.5 of the EGL 1.4 Specification (Rendering Surfaces) 138 139 Add the following to the table of "Queryable surface attributes 140 and types": 141 142 +----------------------+---------+-----------------------------+ 143 | Attribute | Type | Description | 144 +----------------------+---------+-----------------------------+ 145 | EGL_BUFFER_AGE_EXT | Integer | Age of back-buffer contents | 146 +----------------------+---------+-----------------------------+ 147 Table aaa: Queryable surface attributes and types. 148 149 150 Add the following text to the subsection titled "Surface 151 Attributes" in the description for eglQuerySurface 152 153 Querying EGL_BUFFER_AGE_EXT returns the age of the color 154 contents of the current back-buffer as the number of frames 155 elapsed since it was most recently defined. Applications can, 156 under certain conditions described below, use this age to 157 safely rely on the contents of old back- buffers to 158 potentially reduce the amount of redrawing they do each frame. 159 A frame is the period between calls to any of the functions in 160 table 3.X, hereafter referred to as "frame boundaries." 161 162 Function name 163 -------------------- 164 eglSwapBuffers 165 166 Table 3.X, Frame Boundary Functions 167 168 Buffers' ages are initialized to 0 at buffer creation time. 169 When a frame boundary is reached, the following occurs before 170 any exchanging or copying of color buffers: 171 172 * The current back buffer's age is set to 1. 173 * Any other color buffers' ages are incremented by 1 if 174 their age was previously greater than 0. 175 176 For the purposes of buffer age tracking, a buffer's content 177 is considered defined when its age is a value greater than 0. 178 179 For example, with a double buffered surface and an 180 implementation that swaps via buffer exchanges, the age would 181 usually be 2. With a triple buffered surface the age would 182 usually be 3. An age of 1 means the previous swap was 183 implemented as a copy. An age of 0 means the buffer has only 184 just been initialized and the contents are undefined. Single 185 buffered surfaces have no frame boundaries and therefore 186 always have an age of 0. 187 188 Frame boundaries are the only events that can set a buffer's 189 age to a positive value. Once EGL_BUFFER_AGE_EXT has been 190 queried then it can be assumed that the age will remain valid 191 until the next frame boundary. EGL implementations are 192 permitted, but not required, to reset the buffer age in 193 response to pixel ownership test changes for any pixels within 194 the drawable, or if new pixels are added to or removed from 195 the drawable, i.e., the drawable is resized. A reset of this 196 nature does not affect the age of content for pixels that pass 197 the pixel ownership test before and after the event that 198 caused the reset. In other words, applications can assume 199 that no event will invalidate the content of pixels that 200 continuously pass the pixel ownership test between when the 201 buffer age was queried and the following frame boundary. 202 203 It is up to applications to track pixel ownership using data 204 collected from relevant window system events, such as 205 configuration and expose events on X11. 206 207 If the EGL implementation decides to free un-used back-buffers 208 when the system is under memory pressure or in response to 209 power-management events then EGL will return an age of 0 when 210 it allocates a new buffer at the start of a new frame. 211 212 If the EGL_BUFFER_PRESERVED swap behaviour is in use then 213 it can be assumed that the age will always be 1. It is 214 recommended where possible though that the 215 EGL_BUFFER_PRESERVED swap behaviour not be used since it can 216 have severe performance consequences. Keeping track of the 217 buffer age and the regions that have changed over the last 2 218 or 3 frames instead can often replace the need for using 219 EGL_BUFFER_PRESERVED. 220 221 EGL_BUFFER_AGE_EXT state is a property of the EGL surface that 222 owns the buffers and lives in the address space of the 223 application. That is, if an EGL surface has been created from 224 a native window or pixmap that may be shared between 225 processes, the buffer age is not guaranteed to be synchronized 226 across the processes. Binding and unbinding a surface to and 227 from one or more contexts in the same address space will not 228 affect the ages of any buffers in that surface. 229 230 Add the following text to last paragraph of the subsection titled 231 "Surface Attributes" in the description for eglQuerySurface 232 errors. 233 234 If querying EGL_BUFFER_AGE_EXT and <surface> is not bound as 235 the draw surface to the calling threads current context 236 an EGL_BAD_SURFACE error is generated. 237 238Dependencies on OpenGL ES 239 240 None 241 242Dependencies on OpenVG 243 244 None 245 246Issues 247 248 1) What are the semantics if EGL_BUFFER_PRESERVED is in use 249 250 RESOLVED: The age will always be 1 in this case. More 251 clarification about this was added along with the 252 recommendation to use the buffer age to reuse buffers instead 253 of EGL_BUFFER_PRESERVED when possible to avoid the 254 in-efficiencies of introducing a dependency for each frame on 255 the previous frame. 256 257 2) How can an application know that all pixels of a re-usable 258 buffer were originally owned by the current context? 259 260 RESOLVED: It is up to the application to track pixel ownership 261 using existing window system specific events, such as X11 262 expose or configure notify events. 263 264 3) What are the semantics if the buffer age attribute is queried for 265 a surface that isn't bound to the calling thread's context as the 266 draw surface? 267 268 RESOLVED: we report an EGL_BAD_SURFACE error as is similarly 269 done when calling eglSwapBuffers for such a surface. 270 271 4) What is the buffer age of a single buffered surface? 272 273 RESOLVED: 0. This falls out implicitly from the buffer age 274 calculations, which dictate that a buffer's age starts at 0, 275 and is only incremented by frame boundaries. Since frame 276 boundary functions do not affect single buffered surfaces, 277 their age will always be 0. 278 279 5) What guarantees are provided after querying the buffer age? 280 281 RESOLVED: The buffer age of pixels which continue to pass the 282 pixel ownership test must remain valid until the next frame 283 boundary otherwise applications can't be absolutely sure of 284 the consistency of their rendered content. Implementations 285 may reset the queryable age of the buffer when pixel ownership 286 changes occur. This is further clarified in section 3.5 287 288Revision History 289 290 Version 1, 25/07/2011 291 - First draft 292 Version 2, 03/08/2011 293 - Clarified semantics for using EGL_BUFFER_PRESERVED 294 Version 3, 01/09/2011 295 - Fixed a prototype inconsistency 296 Version 4, 03/11/2011 297 - Split out the buffer age parts from EGL_INTEL_start_frame 298 Version 5, 20/03/2012 299 - Document that once the age is queried it remains valid until 300 the end of the frame so we can remove the need for a separate 301 EGL_EXT_start_frame extension. 302 Version 6, 20/03/2012 303 - Clarify that only buffers who's contents were fully owned by 304 the context are tracked. 305 Version 7, 20/03/2012 306 - Document that an error will be generated if querying the age 307 for a surface not bound to the current context. 308 Version 8, 25/08/2012 309 - Update in line with changes made to the GLX_EXT_buffer_age draft spec 310 including more relaxed pixel ownership requirements and explicit 311 clarification of the buffer age calculation. 312 Version 9 20/09/2012 313 - Update in line with changes made to the EGL_EXT_buffer age 314 draft space 315 Version 10 29/11/2012 316 - Add pixel ownership test section and other minor 317 clarifications 318 Version 11 13/12/2012 319 - Allocated enumerant and marked complete. 320 Version 12, 13/06/2013, Chad Versace <chad.versace@intel.com> 321 - Remove the "all rights reserved" clause from the copyright notice. The 322 removal does not change the copyright notice's semantics, since the 323 clause is already implied by any unadorned copyright notice. But, the 324 removal does diminish the likelihood of unwarranted caution in readers 325 of the spec. 326 - Add "IP Status" section to explicitly state that this extension has no 327 knonw IP claims. 328 Version 13, 14/10/2021, Guanzhong Chen 329 - Fix an incorrect token name 330