<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>EGL Technical Note #1 - EGL 1.4 and Ancillary Buffer Preservation</title><link rel="stylesheet" href="igstyle.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><meta name="description" content="Summarizes ancillary buffer preservation issues across eglSwapBuffers, including recent changes to behavior defined by the EGL 1.4 Specification."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="article" title="EGL Technical Note #1 - EGL 1.4 and Ancillary Buffer Preservation"><div class="titlepage"><div><div><h2 class="title"><a name="id2598382"></a>EGL Technical Note #1 - EGL 1.4 and Ancillary Buffer Preservation</h2></div><div><p class="edition"> First Edition</p></div><div><p class="releaseinfo"></p></div><div><div class="authorgroup"><div class="editor"><h4 class="editedby">Edited by</h4><h3 class="editor"><span class="firstname">Jon</span> <span class="surname">Leech</span></h3><div class="affiliation"><span class="orgname">Khronos Group<br></span></div></div></div></div><div><p class="copyright">Copyright © 2010 The Khronos Group Inc.</p></div><div><a href="legal.html">Legal Notice</a></div><div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p> Summarizes <em class="glossterm"><a class="glossterm" href="#ancillary" title="Ancillary Buffers">ancillary | |
buffer</a></em> preservation issues across | |
<code class="code">eglSwapBuffers</code>, including recent changes to | |
behavior defined by the EGL 1.4 Specification. </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#introduction">1. Introduction</a></span></dt><dt><span class="section"><a href="#usecases">2. Use Cases for Buffer Preservation </a></span></dt><dt><span class="section"><a href="#bufquery">3. Color Buffer Preservation Queries and Controls </a></span></dt><dt><span class="section"><a href="#nocontrol">4. No Control of Auxillary Buffer Preservation; Compatibility | |
Issues </a></span></dt><dt><span class="section"><a href="#extensions">5. EGL Extensions for Control of Ancillary Buffer Preservation | |
</a></span></dt><dt><span class="appendix"><a href="#id2602337">A. Glossary</a></span></dt><dt><span class="appendix"><a href="#id2595698">B. Document History</a></span></dt><dt><span class="appendix"><a href="#id2585500">C. Acknowledgements</a></span></dt></dl></div><div class="mediaobject" align="center"><img src="Khronos-1600-Transparent-May07.png" align="middle" width="270" alt="Khronos Group logo"></div><div class="section" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>1. Introduction</h2></div></div></div><p> Calling <code class="code">eglSwapBuffers</code> 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 | |
<a class="ulink" href="http://www.khronos.org/registry/egl/" target="_top"> EGL 1.4 | |
Specification </a> 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. </p><p> 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. </p></div><div class="section" title="2. Use Cases for Buffer Preservation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usecases"></a>2. Use Cases for Buffer Preservation </h2></div></div></div><p> 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. | |
</p><p> If color and ancillary buffer contents are known to be | |
preserved across <code class="code">eglSwapBuffers</code>, such an | |
application can construct and display each step by drawing | |
only the most recent layer and performing | |
<code class="code">eglSwapBuffers</code>. </p><p> 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. | |
<code class="code">glReadPixels</code>) prior to | |
<code class="code">eglSwapBuffers</code>, and restore them (with e.g. | |
<code class="code">glDrawPixels</code> or drawing a textured quad) prior | |
to drawing the next layer. However, both of these approaches | |
are likely to incur significant performance penalties. | |
</p></div><div class="section" title="3. Color Buffer Preservation Queries and Controls"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bufquery"></a>3. Color Buffer Preservation Queries and Controls </h2></div></div></div><p> To determine if <code class="code">eglSwapBuffers</code> will preserve | |
color buffer contents of a surface, call </p><p> <code class="code"> | |
eglQuerySurface(dpy, surface, EGL_SWAP_BEHAVIOR, &value); | |
</code> </p><p> where <code class="code">surface</code> is the <span class="type">EGLSurface</span> | |
being queried, <code class="code">dpy</code> is the | |
<span class="type">EGLDisplay</span> <code class="code">surface</code> belongs to, and | |
<code class="code">value</code> is a pointer to an <span class="type">EGLint</span>. On | |
success, <code class="code">*value</code> will contain either | |
<code class="constant">EGL_BUFFER_PRESERVED</code>, indicating that | |
color buffer contents are preserved, or | |
<code class="constant">EGL_BUFFER_DESTROYED</code>, indicating that | |
color buffer contents are not preserved. </p><p> Some surfaces allow applications to control whether or not | |
the color buffer contents are preserved. If | |
<code class="constant">EGL_SWAP_BEHAVIOR_PRESERVED_BIT</code> is set | |
in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of the | |
<span class="type">EGLConfig</span> used to create <code class="code">surface</code>, | |
then calling </p><p> <code class="code"> | |
eglSurfaceAttrib(dpy, surface, EGL_SWAP_BEHAVIOR, | |
EGL_BUFFER_PRESERVED) | |
</code> </p><p> will cause color buffer contents to be preserved across | |
future calls to <code class="code">eglSwapBuffers</code>, while calling | |
</p><p> <code class="code"> | |
eglSurfaceAttrib(dpy, surface, EGL_SWAP_BEHAVIOR, | |
EGL_BUFFER_DESTOYED) | |
</code> </p><p> 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. | |
</p><p> If <code class="constant">EGL_SWAP_BEHAVIOR_PRESERVED_BIT</code> is | |
not set in the <code class="constant">EGL_SURFACE_TYPE</code> | |
attribute, then control of color buffer preservation is not | |
allowed for this surface. In this case, calling | |
<code class="code">eglSurfaceAttrib</code> with <code class="code">attribute</code> | |
<code class="constant">EGL_SWAP_BEHAVIOR</code> will fail and generate | |
an <code class="constant">EGL_BAD_MATCH</code> error. </p></div><div class="section" title="4. No Control of Auxillary Buffer Preservation; Compatibility Issues"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nocontrol"></a>4. No Control of Auxillary Buffer Preservation; Compatibility | |
Issues </h2></div></div></div><p> 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. </p><p> As a result, the EGL 1.4 API has no way to determine or | |
control whether <code class="code">eglSwapBuffers</code> 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. | |
</p><p> 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. </p></div><div class="section" title="5. EGL Extensions for Control of Ancillary Buffer Preservation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="extensions"></a>5. EGL Extensions for Control of Ancillary Buffer Preservation | |
</h2></div></div></div><p> 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 | |
<a class="ulink" href="http://www.khronos.org/registry/egl/" target="_top"> Khronos | |
Registry</a> when it is finalized. </p></div><div class="appendix" title="A. Glossary"><h2 class="title" style="clear: both"><a name="id2602337"></a>A. Glossary</h2><div class="glosslist"><dl><dt><a name="ancillary"></a>Ancillary Buffers</dt><dd><p> Buffers of an <span class="type">EGLSurface</span> 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. </p></dd></dl></div></div><div class="appendix" title="B. Document History"><h2 class="title" style="clear: both"><a name="id2595698"></a>B. Document History</h2><div class="revhistory"><table border="0" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 1.0</td><td align="left">March 30, 2010</td><td align="left">jpl</td></tr><tr><td class="revremark" align="left" colspan="3">Public Release.</td></tr></table></div></div><div class="appendix" title="C. Acknowledgements"><h2 class="title" style="clear: both"><a name="id2585500"></a>C. Acknowledgements</h2><p>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</p></div></div></body></html> |