1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglSwapBuffers"> 2 <info> 3 <copyright> 4 <year>2003-2014</year> 5 <holder>The Khronos Group Inc.</holder> 6 </copyright> 7 </info> 8 <refmeta> 9 <refentrytitle>eglSwapBuffers</refentrytitle> 10 <manvolnum>3G</manvolnum> 11 </refmeta> 12 <refnamediv> 13 <refname>eglSwapBuffers</refname> 14 <refpurpose> 15 post <acronym>EGL</acronym> surface color buffer to a native window 16 </refpurpose> 17 </refnamediv> 18 <refsynopsisdiv> 19 <title>C Specification</title> 20 <funcsynopsis> 21 <funcprototype> 22 <funcdef>EGLBoolean <function>eglSwapBuffers</function></funcdef> 23 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 24 <paramdef>EGLSurface <parameter>surface</parameter></paramdef> 25 </funcprototype> 26 </funcsynopsis> 27 </refsynopsisdiv> 28 <refsect1 xml:id="parameters"><title>Parameters</title> 29 <variablelist> 30 <varlistentry> 31 <term><parameter>display</parameter></term> 32 <listitem> 33 <para> 34 Specifies the EGL display connection. 35 </para> 36 </listitem> 37 </varlistentry> 38 <varlistentry> 39 <term><parameter>surface</parameter></term> 40 <listitem> 41 <para> 42 Specifies the EGL drawing surface whose buffers are to be swapped. 43 </para> 44 </listitem> 45 </varlistentry> 46 </variablelist> 47 </refsect1> 48 <refsect1 xml:id="description"><title>Description</title> 49 <para> 50 If <parameter>surface</parameter> is a back-buffered window 51 surface, then the color 52 buffer is copied (posted) to the native window associated with that 53 surface. If <parameter>surface</parameter> is a single-buffered 54 window, pixmap, or pixel buffer surface, 55 <function>eglSwapBuffers</function> has no effect. 56 </para> 57 <para> 58 The contents of ancillary buffers are always undefined after 59 calling <function>eglSwapBuffers</function>. The contents of the 60 color buffer are undefined if the value of the 61 <constant>EGL_SWAP_BEHAVIOR</constant> attribute of 62 <parameter>surface</parameter> is not 63 <constant>EGL_BUFFER_PRESERVED</constant>. The value of 64 <constant>EGL_SWAP_BEHAVIOR</constant> can be set for some 65 surfaces using 66 <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>. 67 <constant>EGL_SWAP_BEHAVIOR</constant> applies only to the color 68 buffer. EGL has no way to specify or query whether or not 69 ancillary buffers are preserved, and applications should not 70 rely on this behavior. 71 </para> 72 <para> 73 <function>eglSwapBuffers</function> performs an implicit 74 flush operation on the context (<function>glFlush</function> 75 for an OpenGL ES or OpenGL context, 76 <function>vgFlush</function> for an OpenVG context) bound to 77 <parameter>surface</parameter> before swapping. Subsequent 78 client API commands may be issued on that context 79 immediately after calling 80 <function>eglSwapBuffers</function>, but are not executed 81 until the buffer exchange is completed. 82 </para> 83 </refsect1> 84 <refsect1 xml:id="resize"><title>Native Window Resizing</title> 85 <para> 86 If the native window corresponding to 87 <parameter>surface</parameter> has been resized prior to the 88 swap, <parameter>surface</parameter> must be resized to match. 89 <parameter>surface</parameter> will normally be resized by the 90 EGL implementation at the time the native window is resized. If 91 the implementation cannot do this transparently to the client, 92 then <function>eglSwapBuffers</function> must detect the change 93 and resize surface prior to copying its pixels to the native 94 window. If <parameter>surface</parameter> shrinks as a result of 95 resizing, some rendered pixels are lost. If 96 <parameter>surface</parameter> grows, the newly allocated buffer 97 contents are undefined. The resizing behavior described here 98 only maintains consistency of EGL surfaces and native windows; 99 clients are still responsible for detecting window size changes 100 (using platform-specific means) and changing their viewport and 101 scissor regions accordingly. 102 </para> 103 </refsect1> 104 <refsect1 xml:id="notes"><title>Notes</title> 105 <para> 106 Attribute <constant>EGL_SWAP_BEHAVIOR</constant> is supported 107 only if the EGL version is 1.2 or greater. In earlier versions, 108 behavior is as though the attribute exists, and always has the 109 value <constant>EGL_BUFFER_DESTROYED</constant>. 110 </para> 111 <para> 112 The EGL 1.4 specification was updated to acknowledge that 113 ancillary buffers are not necessarily preserved after a swap, 114 and that the <constant>EGL_SWAP_BEHAVIOR</constant> attribute 115 applies only to the color buffer. This change in the 116 specification acknowledged the behavior of many shipping 117 implementations, and is not intended to result in behavior 118 changes in any existing implementation. 119 </para> 120 </refsect1> 121 <refsect1 xml:id="errors"><title>Errors</title> 122 <para> 123 <constant>EGL_FALSE</constant> is returned if swapping of the 124 surface buffers fails, <constant>EGL_TRUE</constant> otherwise. 125 </para> 126 <para> 127 <constant>EGL_BAD_DISPLAY</constant> is generated if 128 <parameter>display</parameter> is not an EGL display connection. 129 </para> 130 <para> 131 <constant>EGL_NOT_INITIALIZED</constant> is generated if 132 <parameter>display</parameter> has not been initialized. 133 </para> 134 <para> 135 <constant>EGL_BAD_SURFACE</constant> is generated if 136 <parameter>surface</parameter> is not an EGL drawing surface. 137 </para> 138 <para> 139 <constant>EGL_CONTEXT_LOST</constant> is generated if a power management 140 event has occurred. The application must destroy all contexts and 141 reinitialise OpenGL ES state and objects to continue rendering. 142 </para> 143 </refsect1> 144 <refsect1 xml:id="seealso"><title>See Also</title> 145 <para> 146 <function>glFlush</function>, 147 <citerefentry><refentrytitle>eglCopyBuffers</refentrytitle></citerefentry>, 148 <function>vgFlush</function> 149 </para> 150 </refsect1> 151 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 152</refentry> 153