Calling eglSwapBuffers may or may not result in the preservation of the contents of the color buffer and ancillary buffers (depth, stencil, and alpha mask) of the surface being swapped. Some applications may rely on buffer contents being preserved. This note discusses scenarios in which buffer preservation is desirable, describes all the EGL entry points and attributes relevant to buffer preservation, and describes a change in preservation behavior made in the EGL 1.4 Specification update of February 23, 2010. This change may require changes to certain applications which rely on ancillary buffer preservation and are being moved to new platforms or new EGL implementations.

Many applications do not require buffer preservation, since they clear all buffers being used and completely redraw their contents for each frame. Such applications need not consider the issues discussed in this note.

An example of the use of buffer preservation is an application which wishes to build up an image step by step by drawing multiple layers, and to display the partial images resulting from each each successive layer being drawn.

If color and ancillary buffer contents are known to be preserved across eglSwapBuffers, such an application can construct and display each step by drawing only the most recent layer and performing eglSwapBuffers.

If buffer contents are not known to be preserved, the application can instead, for each frame being displayed, redraw all layers up to the most recent. Alternatively, the application may explicitly save the contents of required buffers by reading them back (with e.g. glReadPixels) prior to eglSwapBuffers, and restore them (with e.g. glDrawPixels or drawing a textured quad) prior to drawing the next layer. However, both of these approaches are likely to incur significant performance penalties.

To determine if eglSwapBuffers will preserve color buffer contents of a surface, call

eglQuerySurface(dpy, surface, EGL_SWAP_BEHAVIOR, &value);

where surface is the EGLSurface being queried, dpy is the EGLDisplay surface belongs to, and value is a pointer to an EGLint. On success, *value will contain either EGL_BUFFER_PRESERVED, indicating that color buffer contents are preserved, or EGL_BUFFER_DESTROYED, indicating that color buffer contents are not preserved.

Some surfaces allow applications to control whether or not the color buffer contents are preserved. If EGL_SWAP_BEHAVIOR_PRESERVED_BIT is set in the EGL_SURFACE_TYPE attribute of the EGLConfig used to create surface, then calling

eglSurfaceAttrib(dpy, surface, EGL_SWAP_BEHAVIOR, EGL_BUFFER_PRESERVED)

will cause color buffer contents to be preserved across future calls to eglSwapBuffers, while calling

eglSurfaceAttrib(dpy, surface, EGL_SWAP_BEHAVIOR, EGL_BUFFER_DESTOYED)

will cause color buffer contents to not be preserved. When this control is available, there may be a significant performance penalty for requesting color buffer preservation.

If EGL_SWAP_BEHAVIOR_PRESERVED_BIT is not set in the EGL_SURFACE_TYPE attribute, then control of color buffer preservation is not allowed for this surface. In this case, calling eglSurfaceAttrib with attribute EGL_SWAP_BEHAVIOR will fail and generate an EGL_BAD_MATCH error.

In versions of the EGL 1.4 Specification prior to February 23, 2010, the specification implied that the color buffer preservation behavior described above also applied to ancillary (depth, stencil, and alpha mask) buffer contents. The Specification of February 23, 2010 revises the buffer preservation queries and controls and explicitly states that they only apply to the color buffer.

As a result, the EGL 1.4 API has no way to determine or control whether eglSwapBuffers will preserve ancillary buffer contents. Some implementations do so and some do not. We know that this is a backwards-incompatible change. The change was made because some common hardware incurs very high penalties for ancillary buffer preservation. Despite what prior versions of the Specification said, EGL implementations on these devices often did not preserve ancillary buffers. Khronos felt that developers would be better off if we explicitly acknowledged this situation.

This change in the Specification is not expected to result in changes to implementations, and therefore driver updates are unlikely to adversely affect any application which relies on ancillary buffer preservation. However, developers of such applications must be aware that when porting to another platform, they may find that ancillary buffer contents are not preserved.

The EGL Working Group is currently developing an EGL extension which will allow explicitly control over ancillary buffer preservation in a fashion similar to color buffer preservation. We expect this extension specification to be completed later in 2010. Vendors will then choose whether or not to implement the extension in their drivers. The extension specification will be published in the Khronos Registry when it is finalized.