Description: Summarizes ancillary buffer preservation issues across eglSwapBuffers, including recent changes to behavior defined by the EGL 1.4 Specification.

## EGL Technical Note #1 - EGL 1.4 and Ancillary Buffer Preservation

First Edition

#### Edited by

### Jon Leech

Khronos Group

Copyright © 2010 The Khronos Group Inc.

Legal Notice

Abstract

Summarizes ancillary buffer preservation issues across `eglSwapBuffers`, including recent changes to behavior defined by the EGL 1.4 Specification.

## 1. Introduction

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.

## 2. Use Cases for Buffer Preservation

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.

## 3. Color Buffer Preservation Queries and Controls

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.

## 4. No Control of Auxillary Buffer Preservation; Compatibility Issues

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.

## 5. EGL Extensions for Control of Ancillary Buffer Preservation

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.

## A. Glossary

Ancillary Buffers

  Buffers of an EGLSurface other than the color buffer. These may include the depth and/or stencil buffers for use by OpenGL ES, and the alpha mask buffer for use by OpenVG.

## B. Document History

Revision History
Revision 1.0 | March 30, 2010 | jpl
Public Release.

## C. Acknowledgements

Members of the Khronos EGL Working Group, especially Acorn Pooley, Ben Bowman, Ian Romanick, Mark Callow, and Maurice Ribble. Additional thanks to Mark Callow for the Docbook stylesheets and build process used to build this document