1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
<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>
|
