| Name |
| |
| KHR_partial_update |
| |
| Name Strings |
| |
| EGL_KHR_partial_update |
| |
| Contributors |
| |
| Ray Smith |
| Tom Cooksey |
| James Jones |
| Chad Versace |
| Jesse Hall |
| |
| Contact |
| |
| Ray Smith, ARM (Raymond.Smith 'at' arm.com) |
| |
| IP Status |
| |
| No known claims. |
| |
| Notice |
| |
| Copyright (c) 2014 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| Status |
| |
| Complete. |
| Approved by the EGL Working Group on September 17, 2014. |
| Approved by the Khronos Board of Promoters on November 7, 2014. |
| |
| Version |
| |
| Version 12, September 12, 2014 |
| |
| Number |
| |
| EGL Extension #83 |
| |
| Extension Type |
| |
| EGL display extension |
| |
| Dependencies |
| |
| EGL 1.4 or later is required. |
| |
| Written based on the EGL 1.5 specification (March 12, 2014). |
| |
| The behavior of part of this extension is different depending on whether the |
| EGL_EXT_buffer_age extension is also present. |
| |
| This extension trivially interacts with EGL_KHR_swap_buffers_with_damage and |
| EGL_EXT_swap_buffers_with_damage. This extension is worded against the KHR |
| version, but the interactions with the EXT version are identical. |
| |
| New Procedures and Functions |
| |
| |
| EGLBoolean eglSetDamageRegionKHR(EGLDisplay dpy, |
| EGLSurface surface, |
| EGLint *rects, |
| EGLint n_rects); |
| |
| New Tokens |
| |
| Accepted in the <attribute> parameter of eglQuerySurface: |
| |
| EGL_BUFFER_AGE_KHR 0x313D |
| |
| Overview |
| |
| The aim of this extension is to allow efficient partial updates for postable |
| surfaces. It allows implementations to completely avoid processing areas of |
| the surface which have not changed between frames, allowing increased |
| efficiency. |
| |
| It does so by providing information and guarantees about the content of the |
| current back buffer which allow the application to "repair" only areas that |
| have become out of date since the particular back buffer was last used. |
| |
| The information provided is in the form of the "age" of the buffer, that is, |
| how many frames ago it was last used as the back buffer for the surface. If |
| the application tracks what changes it has made to the surface since this |
| back buffer was last used, it can bring the entire back buffer up to date by |
| only re-rendering the areas it knows to be out of date. |
| |
| Use of this extension provides a more efficient alternative to |
| EGL_BUFFER_PRESERVED swap behaviour. EGL_BUFFER_PRESERVED typically implies |
| an expensive full-frame copy at the beginning of the frame, as well as a |
| dependency on the previous frame. Usage of this extension avoids both and |
| requires only the necessary updates to a back buffer to be made. |
| |
| Terminology |
| |
| This extension and the EGL_KHR_swap_buffers_with_damage extension both use |
| the word "damage" for subtly but significantly different purposes: |
| |
| "Surface damage" is what the EGL_KHR_swap_buffers_with_damage extension |
| is concerned with. This is the area of the *surface* that changes between |
| frames for that surface. It concerns the differences between two buffers - |
| the current back buffer and the current front buffer. It is useful only to |
| the consumer. |
| |
| "Buffer damage" is what the EGL_KHR_partial_update extension is concerned |
| with. This is the area of a particular buffer that has changed since that |
| same buffer was last used. As it only concerns changes to a single buffer, |
| there is no dependency on the next or previous frames or any other buffer. |
| It therefore cannot be used to infer anything about changes to the surface, |
| which requires linking one frame or buffer to another. Buffer damage is |
| therefore only useful to the producer. |
| |
| Following are examples of the two different damage types. Note that the |
| final surface content is the same in both cases, but the damaged areas |
| differ according to the type of damage being discussed. |
| |
| Surface damage example (EGL_KHR_swap_buffers_with_damage) |
| |
| The surface damage for frame n is the difference between frame n and frame |
| (n-1), and represents the area that a compositor must recompose. |
| |
| Frame 0 Frame 1 Frame 2 Frame 3 Frame 4 |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| | | |#########| |#########| |#########| |#########| |
| | | | | |#########| |#########| |#########| Final surface |
| | | | | | | |#########| |#########| content |
| | | | | | | | | |#########| |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| |@@@@@@@@@| |@@@@@@@@@| | | | | | | |
| |@@@@@@@@@| | | |@@@@@@@@@| | | | | Surface damage |
| |@@@@@@@@@| | | | | |@@@@@@@@@| | | |
| |@@@@@@@@@| | | | | | | |@@@@@@@@@| |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| |
| Buffer damage example (EGL_KHR_partial_update) |
| |
| The buffer damage for a frame is the area changed since that same buffer was |
| last used. If the buffer has not been used before, the buffer damage is the |
| entire area of the buffer. |
| |
| The buffer marked with an 'X' in the top left corner is the buffer that is |
| being used for that frame. This is the buffer to which the buffer age and |
| the buffer damage relate. |
| |
| Note that this example shows a double buffered surface - the actual number |
| of buffers could be different and variable throughout the lifetime of the |
| surface. The age *must* therefore be queried for every frame. |
| |
| Frame 0 Frame 1 Frame 2 Frame 3 Frame 4 |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| | | |#########| |#########| |#########| |#########| |
| | | | | |#########| |#########| |#########| Final surface |
| | | | | | | |#########| |#########| content |
| | | | | | | | | |#########| |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| |
| X---------+ +---------+ X---------+ +---------+ X---------+ |
| | | | | |#########| |#########| |#########| |
| | | | | |#########| |#########| |#########| Buffer 1 content |
| | | | | | | | | |#########| |
| | | | | | | | | |#########| |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| |
| X---------+ +---------+ X---------+ +---------+ |
| |#########| |#########| |#########| |#########| |
| | | | | |#########| |#########| Buffer 2 content |
| | | | | |#########| |#########| |
| | | | | | | | | |
| +---------+ +---------+ +---------+ +---------+ |
| |
| 0 0 2 2 2 Buffer age |
| |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| | | | | |
| |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| |@@@@@@@@@| | | Buffer damage |
| |@@@@@@@@@| |@@@@@@@@@| | | |@@@@@@@@@| |@@@@@@@@@| |
| |@@@@@@@@@| |@@@@@@@@@| | | | | |@@@@@@@@@| |
| +---------+ +---------+ +---------+ +---------+ +---------+ |
| |
| |
| Add a new section entitled "Partial updates to postable surfaces" to section |
| 3.5: |
| |
| The "damage region" defines the area of the buffer to which all rendering |
| commands must be restricted. It applies only for surfaces which can be |
| posted, as described in section 3.10, and only when the swap behavior is |
| EGL_BUFFER_DESTROYED. |
| |
| The contents of the buffer outside of the damage region may always be relied |
| upon to contain the same content as the last time they were defined for the |
| current back buffer. See section 3.5.6 for how to query when the current |
| back buffer was last used, and therefore what those contents are. |
| |
| If EGL_EXT_buffer_age is supported, the contents of the buffer inside the |
| damage region may also be relied upon to contain the same content as the |
| last time they were defined for the current back buffer. If |
| EGL_EXT_buffer_age is not supported, the contents of the buffer inside the |
| damage region are always undefined after calling eglSwapBuffers. |
| |
| Setting the damage region appropriately can be used to efficiently update |
| only the necessary areas inbetween frames. |
| |
| After posting the back buffer, the damage region is set to the full |
| dimensions of the surface. The damage region can only be changed by the |
| application before any client API commands that draw to the surface have |
| been made. After this, the damage region is frozen until the back buffer is |
| posted again. |
| |
| Use the command |
| EGLBoolean eglSetDamageRegionKHR( |
| EGLDisplay dpy, |
| EGLSurface surface, |
| EGLint *rects, |
| EGLint n_rects) |
| |
| to set the damage region. |
| |
| The damage region for <surface> is set to the area described by <n_rects> and |
| <rects> if all of the following conditions are met: |
| |
| * <surface> is the current draw surface of the calling thread |
| * <surface> is a postable surface |
| * There have been no client API commands which result with rendering to |
| <surface> since eglSwapBuffers was last called with <surface>, or since |
| <surface> was created in case eglSwapBuffers has not yet been called with |
| <surface>. |
| * The surface's swap behavior is EGL_BUFFER_DESTROYED |
| |
| <n_rects> specifies the number of rectangles comprising the damage region. |
| <rects> is a pointer to a list of values describing the rectangles. The list |
| should consist of <n_rects> groups of four values, with each group |
| representing a single rectangle in surface coordinates in the form {x, y, |
| width, height}. Coordinates are specified relative to the lower left corner |
| of the surface. It is not necessary to avoid overlaps of the specified |
| rectangles. Rectangles that lie (partially) outside of the current surface |
| dimensions (as queryable via the EGL_WIDTH and EGL_HEIGHT attributes) will |
| be clamped to the current surface dimensions. |
| |
| If <n_rects> is zero, <rects> is ignored and the damage region is set to the |
| full dimensions of the surface. |
| |
| If <n_rects> is not zero but the rectangles in <rects> describe a region of |
| zero area after clamping, the damage region is set to the empty region. |
| |
| If <rects> contains more than (4 * <n_rects>) values, the remaining values |
| are ignored. If <rects> contains fewer than (4 * <n_rects>) values, the |
| behavior is undefined, up to and including program termination. |
| |
| At all times, any client API rendering which falls outside of the damage |
| region results in undefined framebuffer contents for the entire framebuffer. |
| It is the client's responsibility to ensure that rendering is confined to |
| the current damage area. |
| |
| If any client API commands resulting in rendering to <surface> have been |
| issued since eglSwapBuffers was last called with <surface>, or since the |
| surface was created in case eglSwapBuffers has not yet been called on it, |
| attempting to set the damage region will result in undefined framebuffer |
| contents for the entire framebuffer. |
| |
| Errors |
| ------ |
| eglSetDamageRegionKHR returns EGL_FALSE on failure: |
| * If <surface> is not a postable surface, an EGL_BAD_MATCH error is |
| generated |
| * If <surface> is not the current draw surface for the calling thread, an |
| EGL_BAD_MATCH error is generated |
| * If the value of EGL_SWAP_BEHAVIOR for <surface> is not |
| EGL_BUFFER_DESTROYED, an EGL_BAD_MATCH error is generated |
| * If eglSetDamageRegionKHR has already been called on <surface> since the |
| most recent frame boundary, an EGL_BAD_ACCESS error is generated |
| * If the EGL_BUFFER_AGE_KHR attribute of <surface> has not been queried |
| since the most recent frame boundary, an EGL_BAD_ACCESS error is generated |
| |
| Add before the final paragraph in section 3.5.6 "Surface Attributes": |
| |
| Querying EGL_BUFFER_AGE_KHR returns the age of the color contents of the |
| current back buffer as the number of frames elapsed since it was most |
| recently defined. Under certain conditions described below, applications |
| can, in conjunction with the surface's damage region (see section 3.5.1), |
| use this age to safely rely on the contents of old back buffers to reduce |
| the amount of redrawing they do each frame. |
| |
| To query the age of a surface, it must be the current draw surface for the |
| calling thread. |
| |
| Function name |
| -------------------- |
| eglSwapBuffers |
| eglSwapBuffersWithDamageKHR |
| |
| Table 3.X, Frame Boundary Functions |
| |
| Buffers' ages are initialized to 0 at buffer creation time. When a frame |
| boundary is reached, the following occurs before any exchanging or copying |
| of color buffers: |
| |
| * The current back buffer's age is set to 1. |
| * Any other color buffers' ages are incremented by 1 if |
| their age was previously greater than 0. |
| |
| For example, with a double buffered surface and an implementation that swaps |
| via buffer exchanges, the age would usually be 2. With a triple buffered |
| surface the age would usually be 3. An age of 1 usually means the previous |
| swap was implemented as a copy. An age of 0 means the buffer has only just |
| been initialized and the contents are undefined. Single buffered surfaces |
| have no frame boundaries and therefore always have an age of 0. |
| |
| Where specified in terms of the current damage region (see section 3.5.6), |
| the relevant part of a buffer's content is considered defined when the |
| buffer's age is a value greater than 0. |
| |
| Frame boundaries are the only events that can set a buffer's age to a |
| positive value. Once EGL_BUFFER_AGE_KHR has been queried then it can be |
| assumed that the age will remain valid until the next frame boundary. EGL |
| implementations are permitted, but not required, to reset the buffer age in |
| response to pixel ownership test changes for any pixels within the drawable, |
| or if new pixels are added to or removed from the drawable, i.e., the |
| drawable is resized. A reset of this nature does not affect the age of |
| content for pixels that pass the pixel ownership test before and after the |
| event that caused the reset. In other words, applications can assume that |
| no event will invalidate the content of pixels that continuously pass the |
| pixel ownership test between when the buffer age was queried and the |
| following frame boundary. It is up to applications to track pixel ownership |
| using data collected from relevant window system events, such as |
| configuration and expose events on the X11 platform. |
| |
| EGL_BUFFER_AGE_KHR state is a property of the EGL surface that owns the |
| buffers and lives in the address space of the application. That is, if an |
| EGL surface has been created from a native window or pixmap that may be |
| shared between processes, the buffer age is not guaranteed to be |
| synchronized across the processes. Binding and unbinding a surface to and |
| from one or more contexts in the same address space will not affect the ages |
| of any buffers in that surface. |
| |
| Add to the list of errors for eglQuerySurface at the end of section 3.5.6 |
| "Surface Attributes": |
| |
| If <attribute> is EGL_BUFFER_AGE_KHR and <surface> is not the current draw |
| surface for the calling thread, an EGL_BAD_SURFACE error is generated. |
| |
| Add to the end of section 3.10.1.1 "Native Window Resizing": |
| |
| If eglSetDamageRegionKHR has been called with anything other than zero for |
| <n_rects>, a surface resize will cause the damage region to become |
| undefined. This will effectively cause the entire framebuffer content to |
| become undefined until the next frame. |
| |
| Dependencies on EGL_KHR_swap_buffers_with_damage |
| |
| If EGL_KHR_swap_buffers_with_damage is not supported, all references to |
| eglSwapBuffersWithDamageKHR are removed. |
| |
| Issues |
| |
| 1) What should happen if the client renders outside of the damage area? |
| |
| RESOLVED: The entire framebuffer content will be undefined. |
| |
| DISCUSSION: The definedness of different parts of the buffer varies across |
| implementations, making it hard to define, and providing any more specific |
| information may encourage improper and non-portable use of this extension. |
| |
| 2) How does this interact with EGL_EXT_buffer_age? |
| |
| RESOLVED: The initial content of the damage area differs depending on |
| whether EGL_EXT_buffer_age is present or not, making this extension fully |
| backwards compatible with EGL_EXT_buffer_age, while not depending on it. |
| |
| 3) How does this interact with EGL_KHR_swap_buffers_with_damage? |
| |
| RESOLVED: It does not interact materially with |
| EGL_KHR_swap_buffers_with_damage, except for the trivial interaction with |
| eglSwapBuffersWithDamageKHR being a frame boundary function if the extension |
| is also supported. |
| |
| DISCUSSION: This extension only provides a way to efficiently update the |
| back buffer for a surface. It does not have any effect on the subsequent |
| posting of that buffer. For maximum efficiency, applications should use both |
| EGL_KHR_partial_update and EGL_KHR_swap_buffers_with_damage simultaneously. |
| |
| 4) How does this interact with EGL_BUFFER_PRESERVED? |
| |
| RESOLVED: It is an error to call eglSetDamageRegionKHR with a surface with |
| EGL_BUFFER_PRESERVED swap behavior. However, it is not an error to query the |
| age of the buffer in this case. |
| |
| DISCUSSION: A layered extension will be proposed to guarantee that the age |
| of a buffer is always 1 after the first frame for a surface. This will |
| provide similar (but not identical) semantics to EGL_BUFFER_PRESERVED for |
| applications that need it. |
| |
| 5) How does surface resizing affect the damage region? |
| |
| RESOLVED: The damage region becomes undefined if a surface resize occurs |
| after it has been set to anything except the full buffer. Because rendering |
| outside the damage area results in undefined framebuffer contents, this |
| effectively means that the entire framebuffer content becomes undefined |
| until the next frame. |
| |
| 6) What happens if the damage region is set after any client rendering |
| commands? |
| |
| OPTION 1: An error is returned. Detecting this condition is non-trivial in |
| some implementations. |
| |
| OPTION 2: The entire framebuffer contents become undefined. |
| |
| RESOLVED: Option 2. |
| |
| 7) Should the entire region be provided in advance of any rendering, or should |
| each region be supplied immediately before the rendering commands for that |
| region, and multiple regions can be defined per frame? |
| |
| RESOLVED: The entire region must be provided in advance of any rendering. |
| |
| 8) What should be the behavior if eglSetDamageRegionKHR is called multiple |
| times before the first rendering command? |
| |
| RESOLVED: This is an error. The entire region must be provided during a |
| single call, with no overwrite or modify behavior needed. |
| |
| 9) Is it allowed to set the damage region when the buffer age has not been |
| queried? |
| |
| RESOLVED: This is an error. This could only make sense when the damage |
| region is the entire buffer, which it is initially anyway. Otherwise the |
| undamaged area needs to be defined to an age that the application doesn't |
| know about. It's not clear that this would ever be useful to the |
| application, because it can't know at this point which areas it needs to |
| update. |
| |
| 10) What is the behavior if, after clamping, the damage region is empty? |
| |
| RESOLVED: The damage region is set to empty. |
| |
| |
| Revision History |
| |
| Version 1, 28/01/2014 |
| - Initial draft |
| Version 2, 05/02/2014 |
| - Removed clip behavior, replaced with undefined framebuffer contents if |
| client renders outside of given damage region |
| - Renamed to EGL_KHR_partial_update from EGL_KHR_frame_clip |
| - Added detailed parameter descriptions and error conditions |
| - Added dependency on GL_XXX_damage_region |
| - Defined interactions with EGL_EXT_buffer_age |
| Version 3, 04/03/2014 |
| - Removed dependency on GL_XXX_damage_region |
| - Changed error on defining damage region after drawcalls to be undefined |
| rendering results instead |
| - Redefined interactions with EGL_EXT_buffer_age to allow both to exist |
| Version 4, 20/03/2014 |
| - Modified language to allow use with EGLStream producer surfaces |
| - Clarified that surface must be the current *draw* surface |
| - Changed n_rects=0 behavior to set the damage region to the entire surface |
| - Clarified that rendering outside the damage region results in the entire |
| framebuffer becoming undefined |
| Version 5, 20/03/2014 |
| - Updated to be based on EGL 1.5 spec |
| Version 6, 23/04/2014 |
| -Added the pixel ownership logic from EGL_EXT_buffer_age |
| -Ported over the detailed description of buffer age from EGL_EXT_buffer_age |
| -Added a "New Functions" and "New Tokens" section. |
| -Added dependencies on EGL_EXT_swap_buffers_with_damage |
| Version 7, 20/05/2014 |
| - Removing a couple of now-obsolete sentences |
| - An age of 1 *usually* means the previous swap was implemented as a copy. |
| - Reworded "For the purposes of buffer age tracking..." to reference the |
| conditions under which the different parts of the buffer are actually |
| defined, which depend on the damage region |
| Version 8, 20/05/2014 |
| - Added issues list |
| Version 9, 12/08/2014 |
| - Removed outdated modification to "Posting to a Window" |
| - Changed names and order of rects/n_rects to match |
| EGL_EXT_swap_buffers_with_damage |
| - Resolved issue 3 on EGL_EXT_swap_buffers_with_damage interactions |
| - Resolved issue 4 on EGL_BUFFER_PRESERVED swap behavior |
| - Resolved issue 5 on surface resize behavior |
| - Resolved issue 7 on multiple calls to eglSetDamageRegionKHR |
| - Added issue 8 and suggested resolution |
| - Added issue 9 and suggested resolution |
| - Added issue 10 and suggested resolution |
| Version 10, 19/08/2014 |
| - Added section on terminology and damage types |
| Version 11, 10/09/2014 |
| - Resolved outstanding issues |
| Version 12, 12/09/2014 |
| - Added the restriction that you can only query the age of a surface while |
| it is the current draw surface. |
| Version 13, 18/09/2015 |
| - Marked as a Display extension |
| - Changed remaining references to EGL_EXT_swap_buffers_with_damage to |
| EGL_KHR_swap_buffers_with_damage |
