1<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 2 buffer</a></em> preservation issues across 3 <code class="code">eglSwapBuffers</code>, including recent changes to 4 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 5 Issues </a></span></dt><dt><span class="section"><a href="#extensions">5. EGL Extensions for Control of Ancillary Buffer Preservation 6 </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 7 the preservation of the contents of the color buffer and 8 ancillary buffers (depth, stencil, and alpha mask) of the 9 surface being swapped. Some applications may rely on buffer 10 contents being preserved. This note discusses scenarios in 11 which buffer preservation is desirable, describes all the EGL 12 entry points and attributes relevant to buffer preservation, 13 and describes a change in preservation behavior made in the 14 <a class="ulink" href="http://www.khronos.org/registry/egl/" target="_top"> EGL 1.4 15 Specification </a> update of February 23, 2010. This 16 change may require changes to certain applications which rely 17 on ancillary buffer preservation and are being moved to new 18 platforms or new EGL implementations. </p><p> Many applications do not require buffer preservation, since 19 they clear all buffers being used and completely redraw their 20 contents for each frame. Such applications need not consider 21 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 22 application which wishes to build up an image step by step by 23 drawing multiple layers, and to display the partial images 24 resulting from each each successive layer being drawn. 25 </p><p> If color and ancillary buffer contents are known to be 26 preserved across <code class="code">eglSwapBuffers</code>, such an 27 application can construct and display each step by drawing 28 only the most recent layer and performing 29 <code class="code">eglSwapBuffers</code>. </p><p> If buffer contents are not known to be preserved, the 30 application can instead, for each frame being displayed, 31 redraw all layers up to the most recent. Alternatively, the 32 application may explicitly save the contents of required 33 buffers by reading them back (with e.g. 34 <code class="code">glReadPixels</code>) prior to 35 <code class="code">eglSwapBuffers</code>, and restore them (with e.g. 36 <code class="code">glDrawPixels</code> or drawing a textured quad) prior 37 to drawing the next layer. However, both of these approaches 38 are likely to incur significant performance penalties. 39 </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 40 color buffer contents of a surface, call </p><p> <code class="code"> 41 eglQuerySurface(dpy, surface, EGL_SWAP_BEHAVIOR, &value); 42 </code> </p><p> where <code class="code">surface</code> is the <span class="type">EGLSurface</span> 43 being queried, <code class="code">dpy</code> is the 44 <span class="type">EGLDisplay</span> <code class="code">surface</code> belongs to, and 45 <code class="code">value</code> is a pointer to an <span class="type">EGLint</span>. On 46 success, <code class="code">*value</code> will contain either 47 <code class="constant">EGL_BUFFER_PRESERVED</code>, indicating that 48 color buffer contents are preserved, or 49 <code class="constant">EGL_BUFFER_DESTROYED</code>, indicating that 50 color buffer contents are not preserved. </p><p> Some surfaces allow applications to control whether or not 51 the color buffer contents are preserved. If 52 <code class="constant">EGL_SWAP_BEHAVIOR_PRESERVED_BIT</code> is set 53 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of the 54 <span class="type">EGLConfig</span> used to create <code class="code">surface</code>, 55 then calling </p><p> <code class="code"> 56 eglSurfaceAttrib(dpy, surface, EGL_SWAP_BEHAVIOR, 57 EGL_BUFFER_PRESERVED) 58 </code> </p><p> will cause color buffer contents to be preserved across 59 future calls to <code class="code">eglSwapBuffers</code>, while calling 60 </p><p> <code class="code"> 61 eglSurfaceAttrib(dpy, surface, EGL_SWAP_BEHAVIOR, 62 EGL_BUFFER_DESTOYED) 63 </code> </p><p> will cause color buffer contents to not be preserved. When 64 this control is available, there may be a significant 65 performance penalty for requesting color buffer preservation. 66 </p><p> If <code class="constant">EGL_SWAP_BEHAVIOR_PRESERVED_BIT</code> is 67 not set in the <code class="constant">EGL_SURFACE_TYPE</code> 68 attribute, then control of color buffer preservation is not 69 allowed for this surface. In this case, calling 70 <code class="code">eglSurfaceAttrib</code> with <code class="code">attribute</code> 71 <code class="constant">EGL_SWAP_BEHAVIOR</code> will fail and generate 72 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 73 Issues </h2></div></div></div><p> In versions of the EGL 1.4 Specification prior to February 23, 74 2010, the specification implied that the color buffer 75 preservation behavior described above also applied to ancillary 76 (depth, stencil, and alpha mask) buffer contents. The 77 Specification of February 23, 2010 revises the buffer 78 preservation queries and controls and explicitly states that 79 they only apply to the color buffer. </p><p> As a result, the EGL 1.4 API has no way to determine or 80 control whether <code class="code">eglSwapBuffers</code> will preserve 81 ancillary buffer contents. Some implementations do so and 82 some do not. We know that this is a backwards-incompatible 83 change. The change was made because some common hardware 84 incurs very high penalties for ancillary buffer preservation. 85 Despite what prior versions of the Specification said, EGL 86 implementations on these devices often did not preserve 87 ancillary buffers. Khronos felt that developers would be 88 better off if we explicitly acknowledged this situation. 89 </p><p> This change in the Specification is not expected to result in 90 changes to implementations, and therefore driver updates are 91 unlikely to adversely affect any application which relies on 92 ancillary buffer preservation. However, developers of such 93 applications must be aware that when porting to another 94 platform, they may find that ancillary buffer contents are 95 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 96 </h2></div></div></div><p> The EGL Working Group is currently developing an EGL extension 97 which will allow explicitly control over ancillary buffer 98 preservation in a fashion similar to color buffer preservation. 99 We expect this extension specification to be completed later in 100 2010. Vendors will then choose whether or not to implement the 101 extension in their drivers. The extension specification will 102 be published in the 103 <a class="ulink" href="http://www.khronos.org/registry/egl/" target="_top"> Khronos 104 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 105 color buffer. These may include the depth and/or stencil 106 buffers for use by OpenGL ES, and the alpha mask buffer for 107 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 108 Pooley, Ben Bowman, Ian Romanick, Mark Callow, and Maurice Ribble. 109 Additional thanks to Mark Callow for the Docbook stylesheets and 110 build process used to build this document</p></div></div></body></html> 111
