blob: 717d1d03a1d2080ff3718a659167770af913c3ad [file] [log] [blame]
Name Strings
IP Status
No known IP claims.
Robert Bragg
Tapani Pälli
Kristian Høgsberg
Benjamin Franzke
Ian Stewart
James Jones
Robert Bragg, Intel (robert.bragg 'at'
10 - October 23, 2014
EGL Extension #55
Requires EGL 1.4
This extension is written against the wording of the EGL 1.4
This extension provides a means to issue a swap buffers request to
display the contents of the current back buffer and also specify a
list of damage rectangles that can be passed to a system
compositor so it can minimize how much it has to recompose.
This should be used in situations where an application is only
animating a small portion of a surface since it enables the
compositor to avoid wasting time recomposing parts of the surface
that haven't changed.
New Procedures and Functions
EGLBoolean eglSwapBuffersWithDamageEXT (
EGLDisplay dpy,
EGLSurface surface,
EGLint *rects,
EGLint n_rects);
New Tokens
Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Add the following text to subsection 3.9.1 titled "Posting to a
Window" after the description of eglSwapBuffers.
As an alternative to eglSwapBuffers use:
EGLBoolean eglSwapBuffersWithDamageEXT (
EGLDisplay dpy,
EGLSurface surface,
EGLint *rects,
EGLint n_rects);
to do the same thing as eglSwapBuffers but additionally report
a list of rectangles that define the region that has truly
changed since the last frame. To be clear; the entire contents
of the back buffer will still be swapped to the front so
applications using this API must still ensure that the entire
back buffer is consistent. The rectangles are only a hint for
the system compositor so it can avoid recomposing parts of the
surface that haven't really changed.
<rects> points to a list of integers in groups of four that
each describe a rectangle in screen coordinates in this
layout: {x, y, width, height}. The rectangles are specified
relative to the bottom-left of the surface and the x and y
components of each rectangle specify the bottom-left position
of that rectangle. <n_rects> determines how many groups of 4
integers can be read from <rects>. It is not necessary to
avoid overlaps of the specified rectangles.
If <n_rects> is 0 then <rects> is ignored and the entire
surface is implicitly damaged and the behaviour is equivalent
to calling eglSwapBuffers.
The error conditions checked for are the same as for the
eglSwapBuffers api.
Modify the first paragraph of Section 3.9.1 titled "Native Window
"If the native window corresponding to <surface> has been
resized prior to the swap, <surface> must be resized to match.
<surface> will normally be resized by the EGL implementation
at the time the native window is resized. If the
implementation cannot do this transparently to the client,
then eglSwapBuffers and eglSwapBuffersWithDamageEXT must
detect the change and resize surface prior to copying its
pixels to the native window. In this case the meaningfulness
of any damage rectangles forwarded by
eglSwapBuffersWithDamageEXT to the native window system is
Modify the following sentences in Section 3.9.3, page 51 (Posting
Paragraph 2, first sentence:
"If <dpy> and <surface> are the display and surface for the
calling thread's current context, eglSwapBuffers,
eglSwapBuffersWithDamageEXT, and eglCopyBuffers perform an
implicit flush operation on the context (glFlush for OpenGL or
OpenGL ES context, vgFlush for an OpenVG context)."
Paragraph 3, first sentence:
"The destination of a posting operation (a visible window, for
eglSwapBuffers or eglSwapBuffersWithDamageEXT, or a native
pixmap, for eglCopyBuffers) should have the same number of
components and component sizes as the color buffer it's being
copied from."
Paragraph 6, first two sentences:
"The function
EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint
specifies the minimum number of video frame periods per color
buffer post operation for the window associated with the
current context. The interval takes effect when eglSwapBuffers
or eglSwapBuffersWithDamageEXT is first called subsequent to
the eglSwapInterval call."
Modify the following sentences in Section 3.9.4, page 52 (Posting
Paragraph 1, first sentence:
"eglSwapBuffers, eglSwapBuffersWithDamageEXT, and
eglCopyBuffers return EGL_FALSE on failure."
Paragraph 1, seventh sentence:
"If eglSwapBuffers or eglSwapBuffersWithDamageEXT are called
and the native window associated with <surface> is no longer
valid, an EGL_BAD_NATIVE_WINDOW error is generated. If
eglSwapBuffersWithDamageEXT is called and <n_rects>, is less
than zero or <n_rects> is greater than zero but <rects> is
NULL, EGL_BAD_PARAMETER is generated."
Dependencies on OpenGL ES
Dependencies on OpenVG
1) Do applications have to make sure the rectangles don't overlap?
RESOLVED: No, that would be inconvenient for applications and we
see no difficulty for implementations to supporting overlapping
2) Would it be valid for an implementation to discard the list of
rectangles internally and work just in terms of the
eglSwapBuffers api?
RESOLVED: Yes, the rectangles are only there for optimization
purposes so although it wouldn't be beneficial to applications if
it was convenient at times then it would be compliant for an
implementation to discard the rectangles and just call
eglSwapBuffers instead. The error conditions that should be
checked for are compatible with the requirements for
3) What origin should be used for damage rectangles?
RESOLVED: Bottom left since this is consistent with all other
uses of 2D window coordinates in EGL and OpenGL that specify a
bottom left origin.
Originally this specification was written with a top-left origin
for the damage rectangles even though it was known to be
inconsistent and that was because most window systems use a
top-left origin and there are some awkward semantic details
related to handling native window resizing that we had hoped to
This extension and also several other existing EGL extensions
struggle to guarantee a reliable behaviour in response to native
window resizing which can happen asynchronously on some platforms
and this can make it difficult for applications to avoid certain
visual artefacts.
The crux of the problem is that when a native window is
asynchronously resized then the window system may maintain the old
buffer contents with respect to a different origin than EGL's
bottom left origin. For this extension that means that EGL damage
rectangles that are intended to map to specific surface contents
may end up mapping to different contents when a native window is
resized because the rectangles and buffer contents will be moved in
different directions in relation to the new window size.
In the end we decided that this issue isn't simply solved by
choosing to use a top-left origin and so we can instead aim for
consistency and clarify what guarantees we offer in relation to
native window resizing separate from this issue.
4) What guarantees do we provide about the meaningfulness of EGL
damage rectangles that are forwarded to the native window system
when presenting to a native window that has been resized?
RESOLVED: The meaningfulness of those forwarded damage rectangles
is undefined since this simplifies the implementation requirements
and we saw very little benefit to applications from providing
stricter guarantees.
The number of applications that would be able to avoid fully
redrawing the contents of a window in response to a window resize
is expected to be so low that there would be almost no benefit to
defining strict guarantees here.
Since EGL already states that the contents of window surface
buffers become undefined when a native window has been resized,
this limitation doesn't introduce any new issue for applications
to consider. Applications should already fully redraw buffer
contents in response to a native window resize, unless they are
following some platform specific documentation that provides
additional guarantees.
For an example of the implementation details that make this an
awkward issue to provide guarantees for we can consider X11 based
platforms where native windows can be resized asynchronously with
respect to a client side EGL surface:
With X11 there may be multiple "gravity" transformations that can
affect how surface buffer content is positioned with respect to a
new native window size; there is the core X "bit gravity" and
there is the EGL driver gravity that determines how a surface's
contents with one size should be mapped to a native window with a
different size. Without very careful cooperation between the EGL
driver and the core X implementation and without the right
architecture to be able to do transforms atomically with respect
to different clients that may enact a window resize then it is not
possible to reliably map EGL damage rectangles to native window
The disadvantage of a driver that is not able to reliably map EGL
damage rectangles to native window coordinates is that a native
compositor may re-compose the wrong region of window. This may
result in a temporary artefact until the full window gets redrawn
and then re-composed. X11 already suffers other similar transient
artefacts when resizing windows.
The authors of this spec believe that even if a driver can't do
reliable mappings of EGL damage rectangles then compositors would
be able mitigate the majority of related artefacts by ignoring
sub-window damage during an interactive window resize.
The authors of this spec believe that that if an X11 driver did
want to reliably map EGL damage rectangles to the native window
coordinates then that may be technically feasible depending on the
driver architecture. For reference one approach that had been
considered (but not tested) is as follows:
1) When eglSwapBuffersWithDamageEXT is called, send EGL damage
rectangles from the client to a driver component within the
xserver un-transformed in EGL window surface coordinates with a
bottom-left origin.
2) Within the X server the driver component should look at the
bit-gravity of a window and use the bit-gravity convention to
copy EGL surface content to the front-buffer of a native window.
3) Within the X server the driver component should use the same
gravity transform that was used to present the surface content
to also transform the EGL damage rectangle coordinates.
Note that because this transform is done in the xserver then
this is implicitly synchronized with all clients that would
otherwise be able to enact an asynchronous window resize.
Revision History
Version 1, 29/07/2011
- First draft
Version 2, 03/08/2011
- Clarify that the rectangles passed may overlap
Version 3, 01/09/2011
- Fix a missing '*' in prototype to make rects a pointer
Version 4, 11,02,2012
- Clarify that implementing in terms of eglSwapBuffers would be
Version 5, 11,02,2012
- Tweak the cases where we report BAD_PARAMETER errors
Version 6, 05/02/2013
- Specify more thorough updates across the EGL 1.4 spec
wherever it relates to the eglSwapBuffers api
- Clarify that passing <n_rects> of 0 behaves as if
eglSwapBuffers were called.
Version 7, 14/02/2013
- Specify that a bottom-left origin should be used for rectangles
Version 8, 19/03/2013
- Add Ian and James as contributors
- Add an issue explaining why we changed to a bottom-left origin
- Clarify that the behaviour is undefined when presenting to a
native window that has been resized.
- Document the awkward details that would be involved in
providing more strict guarantees when presenting to a native
window that has been resized.
Version 9, 12/06/2013, Chad Versace <>
- Remove the "all rights reserved" clause from the copyright notice. The
removal does not change the copyright notice's semantics, since the
clause is already implied by any unadorned copyright notice. But, the
removal does diminish the likelihood of unwarranted caution in readers
of the spec.
- Add "IP Status" section to explicitly state that this extension has no
knonw IP claims.
Version 10, 23/10/2014, Jon Leech
- Remove copyright after signoff from Intel.