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

First Edition

Edited by

Jon Leech

Khronos Group

Abstract

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

Table of Contents

1. Introduction
2. Use Cases for Buffer Preservation
3. Color Buffer Preservation Queries and Controls
4. No Control of Auxillary Buffer Preservation; Compatibility + Issues
5. EGL Extensions for Control of Ancillary Buffer Preservation +
A. Glossary
B. Document History
C. Acknowledgements

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