102f4aeb0Sopenharmony_ci<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 202f4aeb0Sopenharmony_ci buffer</a></em> preservation issues across 302f4aeb0Sopenharmony_ci <code class="code">eglSwapBuffers</code>, including recent changes to 402f4aeb0Sopenharmony_ci 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 502f4aeb0Sopenharmony_ci Issues </a></span></dt><dt><span class="section"><a href="#extensions">5. EGL Extensions for Control of Ancillary Buffer Preservation 602f4aeb0Sopenharmony_ci </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 702f4aeb0Sopenharmony_ci the preservation of the contents of the color buffer and 802f4aeb0Sopenharmony_ci ancillary buffers (depth, stencil, and alpha mask) of the 902f4aeb0Sopenharmony_ci surface being swapped. Some applications may rely on buffer 1002f4aeb0Sopenharmony_ci contents being preserved. This note discusses scenarios in 1102f4aeb0Sopenharmony_ci which buffer preservation is desirable, describes all the EGL 1202f4aeb0Sopenharmony_ci entry points and attributes relevant to buffer preservation, 1302f4aeb0Sopenharmony_ci and describes a change in preservation behavior made in the 1402f4aeb0Sopenharmony_ci <a class="ulink" href="http://www.khronos.org/registry/egl/" target="_top"> EGL 1.4 1502f4aeb0Sopenharmony_ci Specification </a> update of February 23, 2010. This 1602f4aeb0Sopenharmony_ci change may require changes to certain applications which rely 1702f4aeb0Sopenharmony_ci on ancillary buffer preservation and are being moved to new 1802f4aeb0Sopenharmony_ci platforms or new EGL implementations. </p><p> Many applications do not require buffer preservation, since 1902f4aeb0Sopenharmony_ci they clear all buffers being used and completely redraw their 2002f4aeb0Sopenharmony_ci contents for each frame. Such applications need not consider 2102f4aeb0Sopenharmony_ci 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 2202f4aeb0Sopenharmony_ci application which wishes to build up an image step by step by 2302f4aeb0Sopenharmony_ci drawing multiple layers, and to display the partial images 2402f4aeb0Sopenharmony_ci resulting from each each successive layer being drawn. 2502f4aeb0Sopenharmony_ci </p><p> If color and ancillary buffer contents are known to be 2602f4aeb0Sopenharmony_ci preserved across <code class="code">eglSwapBuffers</code>, such an 2702f4aeb0Sopenharmony_ci application can construct and display each step by drawing 2802f4aeb0Sopenharmony_ci only the most recent layer and performing 2902f4aeb0Sopenharmony_ci <code class="code">eglSwapBuffers</code>. </p><p> If buffer contents are not known to be preserved, the 3002f4aeb0Sopenharmony_ci application can instead, for each frame being displayed, 3102f4aeb0Sopenharmony_ci redraw all layers up to the most recent. Alternatively, the 3202f4aeb0Sopenharmony_ci application may explicitly save the contents of required 3302f4aeb0Sopenharmony_ci buffers by reading them back (with e.g. 3402f4aeb0Sopenharmony_ci <code class="code">glReadPixels</code>) prior to 3502f4aeb0Sopenharmony_ci <code class="code">eglSwapBuffers</code>, and restore them (with e.g. 3602f4aeb0Sopenharmony_ci <code class="code">glDrawPixels</code> or drawing a textured quad) prior 3702f4aeb0Sopenharmony_ci to drawing the next layer. However, both of these approaches 3802f4aeb0Sopenharmony_ci are likely to incur significant performance penalties. 3902f4aeb0Sopenharmony_ci </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 4002f4aeb0Sopenharmony_ci color buffer contents of a surface, call </p><p> <code class="code"> 4102f4aeb0Sopenharmony_ci eglQuerySurface(dpy, surface, EGL_SWAP_BEHAVIOR, &value); 4202f4aeb0Sopenharmony_ci </code> </p><p> where <code class="code">surface</code> is the <span class="type">EGLSurface</span> 4302f4aeb0Sopenharmony_ci being queried, <code class="code">dpy</code> is the 4402f4aeb0Sopenharmony_ci <span class="type">EGLDisplay</span> <code class="code">surface</code> belongs to, and 4502f4aeb0Sopenharmony_ci <code class="code">value</code> is a pointer to an <span class="type">EGLint</span>. On 4602f4aeb0Sopenharmony_ci success, <code class="code">*value</code> will contain either 4702f4aeb0Sopenharmony_ci <code class="constant">EGL_BUFFER_PRESERVED</code>, indicating that 4802f4aeb0Sopenharmony_ci color buffer contents are preserved, or 4902f4aeb0Sopenharmony_ci <code class="constant">EGL_BUFFER_DESTROYED</code>, indicating that 5002f4aeb0Sopenharmony_ci color buffer contents are not preserved. </p><p> Some surfaces allow applications to control whether or not 5102f4aeb0Sopenharmony_ci the color buffer contents are preserved. If 5202f4aeb0Sopenharmony_ci <code class="constant">EGL_SWAP_BEHAVIOR_PRESERVED_BIT</code> is set 5302f4aeb0Sopenharmony_ci in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of the 5402f4aeb0Sopenharmony_ci <span class="type">EGLConfig</span> used to create <code class="code">surface</code>, 5502f4aeb0Sopenharmony_ci then calling </p><p> <code class="code"> 5602f4aeb0Sopenharmony_ci eglSurfaceAttrib(dpy, surface, EGL_SWAP_BEHAVIOR, 5702f4aeb0Sopenharmony_ci EGL_BUFFER_PRESERVED) 5802f4aeb0Sopenharmony_ci </code> </p><p> will cause color buffer contents to be preserved across 5902f4aeb0Sopenharmony_ci future calls to <code class="code">eglSwapBuffers</code>, while calling 6002f4aeb0Sopenharmony_ci </p><p> <code class="code"> 6102f4aeb0Sopenharmony_ci eglSurfaceAttrib(dpy, surface, EGL_SWAP_BEHAVIOR, 6202f4aeb0Sopenharmony_ci EGL_BUFFER_DESTOYED) 6302f4aeb0Sopenharmony_ci </code> </p><p> will cause color buffer contents to not be preserved. When 6402f4aeb0Sopenharmony_ci this control is available, there may be a significant 6502f4aeb0Sopenharmony_ci performance penalty for requesting color buffer preservation. 6602f4aeb0Sopenharmony_ci </p><p> If <code class="constant">EGL_SWAP_BEHAVIOR_PRESERVED_BIT</code> is 6702f4aeb0Sopenharmony_ci not set in the <code class="constant">EGL_SURFACE_TYPE</code> 6802f4aeb0Sopenharmony_ci attribute, then control of color buffer preservation is not 6902f4aeb0Sopenharmony_ci allowed for this surface. In this case, calling 7002f4aeb0Sopenharmony_ci <code class="code">eglSurfaceAttrib</code> with <code class="code">attribute</code> 7102f4aeb0Sopenharmony_ci <code class="constant">EGL_SWAP_BEHAVIOR</code> will fail and generate 7202f4aeb0Sopenharmony_ci 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 7302f4aeb0Sopenharmony_ci Issues </h2></div></div></div><p> In versions of the EGL 1.4 Specification prior to February 23, 7402f4aeb0Sopenharmony_ci 2010, the specification implied that the color buffer 7502f4aeb0Sopenharmony_ci preservation behavior described above also applied to ancillary 7602f4aeb0Sopenharmony_ci (depth, stencil, and alpha mask) buffer contents. The 7702f4aeb0Sopenharmony_ci Specification of February 23, 2010 revises the buffer 7802f4aeb0Sopenharmony_ci preservation queries and controls and explicitly states that 7902f4aeb0Sopenharmony_ci they only apply to the color buffer. </p><p> As a result, the EGL 1.4 API has no way to determine or 8002f4aeb0Sopenharmony_ci control whether <code class="code">eglSwapBuffers</code> will preserve 8102f4aeb0Sopenharmony_ci ancillary buffer contents. Some implementations do so and 8202f4aeb0Sopenharmony_ci some do not. We know that this is a backwards-incompatible 8302f4aeb0Sopenharmony_ci change. The change was made because some common hardware 8402f4aeb0Sopenharmony_ci incurs very high penalties for ancillary buffer preservation. 8502f4aeb0Sopenharmony_ci Despite what prior versions of the Specification said, EGL 8602f4aeb0Sopenharmony_ci implementations on these devices often did not preserve 8702f4aeb0Sopenharmony_ci ancillary buffers. Khronos felt that developers would be 8802f4aeb0Sopenharmony_ci better off if we explicitly acknowledged this situation. 8902f4aeb0Sopenharmony_ci </p><p> This change in the Specification is not expected to result in 9002f4aeb0Sopenharmony_ci changes to implementations, and therefore driver updates are 9102f4aeb0Sopenharmony_ci unlikely to adversely affect any application which relies on 9202f4aeb0Sopenharmony_ci ancillary buffer preservation. However, developers of such 9302f4aeb0Sopenharmony_ci applications must be aware that when porting to another 9402f4aeb0Sopenharmony_ci platform, they may find that ancillary buffer contents are 9502f4aeb0Sopenharmony_ci 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 9602f4aeb0Sopenharmony_ci </h2></div></div></div><p> The EGL Working Group is currently developing an EGL extension 9702f4aeb0Sopenharmony_ci which will allow explicitly control over ancillary buffer 9802f4aeb0Sopenharmony_ci preservation in a fashion similar to color buffer preservation. 9902f4aeb0Sopenharmony_ci We expect this extension specification to be completed later in 10002f4aeb0Sopenharmony_ci 2010. Vendors will then choose whether or not to implement the 10102f4aeb0Sopenharmony_ci extension in their drivers. The extension specification will 10202f4aeb0Sopenharmony_ci be published in the 10302f4aeb0Sopenharmony_ci <a class="ulink" href="http://www.khronos.org/registry/egl/" target="_top"> Khronos 10402f4aeb0Sopenharmony_ci 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 10502f4aeb0Sopenharmony_ci color buffer. These may include the depth and/or stencil 10602f4aeb0Sopenharmony_ci buffers for use by OpenGL ES, and the alpha mask buffer for 10702f4aeb0Sopenharmony_ci 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 10802f4aeb0Sopenharmony_ci Pooley, Ben Bowman, Ian Romanick, Mark Callow, and Maurice Ribble. 10902f4aeb0Sopenharmony_ci Additional thanks to Mark Callow for the Docbook stylesheets and 11002f4aeb0Sopenharmony_ci build process used to build this document</p></div></div></body></html> 111
