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 window surface, 51 <function>eglSwapBuffers</function> posts its color buffer 52 to the associated native window. 53 </para> 54 <para> 55 The contents of ancillary buffers are always undefined after 56 calling <function>eglSwapBuffers</function>. The contents of 57 the color buffer are left unchanged if the value of the 58 <constant>EGL_SWAP_BEHAVIOR</constant> attribute of 59 <parameter>surface</parameter> is 60 <constant>EGL_BUFFER_PRESERVED</constant>, and are undefined 61 if the value is <constant>EGL_BUFFER_DESTROYED</constant>. 62 The value of <constant>EGL_SWAP_BEHAVIOR</constant> can be 63 set for some surfaces using 64 <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>. 65 </para> 66 <para> 67 <function>eglSwapBuffers</function> performs an implicit 68 flush operation on the context (<function>glFlush</function> 69 for an OpenGL ES or OpenGL context, 70 <function>vgFlush</function> for an OpenVG context) bound to 71 <parameter>surface</parameter> before swapping. Subsequent 72 client API commands may be issued on that context 73 immediately after calling 74 <function>eglSwapBuffers</function>, but are not executed 75 until the buffer exchange is completed. 76 </para> 77 <para> 78 If <parameter>surface</parameter> is a pixel buffer or a pixmap, 79 <function>eglSwapBuffers</function> 80 has no effect, and no error is generated. 81 </para> 82 </refsect1> 83 <refsect1 xml:id="notes"><title>Notes</title> 84 <para> 85 Attribute <constant>EGL_SWAP_BEHAVIOR</constant> is 86 supported only if the EGL version is 1.2 or greater. In 87 earlier versions, behavior is as though the attribute 88 exists, and always has the value 89 <constant>EGL_BUFFER_DESTROYED</constant>. 90 </para> 91 <para> 92 The EGL 1.4 specification was updated to acknowledge that 93 ancillary buffers are not necessarily preserved after a 94 swap, and that the <constant>EGL_SWAP_BEHAVIOR</constant> 95 attribute applies only to the color buffer. This change in 96 the specification acknowledged the behavior of many shipping 97 implementations, and is not intended to result in behavior 98 changes in any existing implementation. Applications which 99 require preservation of ancillary buffers across a swap 100 should be aware that not all implementations can preserve 101 them, and that EGL 1.4 has no way to query whether or not 102 they are preserved. 103 </para> 104 </refsect1> 105 <refsect1 xml:id="errors"><title>Errors</title> 106 <para> 107 <constant>EGL_FALSE</constant> is returned if swapping of the 108 surface buffers fails, <constant>EGL_TRUE</constant> otherwise. 109 </para> 110 <para> 111 <constant>EGL_BAD_DISPLAY</constant> is generated if 112 <parameter>display</parameter> is not an EGL display connection. 113 </para> 114 <para> 115 <constant>EGL_NOT_INITIALIZED</constant> is generated if 116 <parameter>display</parameter> has not been initialized. 117 </para> 118 <para> 119 <constant>EGL_BAD_SURFACE</constant> is generated if 120 <parameter>surface</parameter> is not an EGL drawing surface. 121 </para> 122 <para> 123 <constant>EGL_CONTEXT_LOST</constant> is generated if a power management 124 event has occurred. The application must destroy all contexts and 125 reinitialise OpenGL ES state and objects to continue rendering. 126 </para> 127 </refsect1> 128 <refsect1 xml:id="seealso"><title>See Also</title> 129 <para> 130 <citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry>, 131 <citerefentry><refentrytitle>eglCopyBuffers</refentrytitle></citerefentry> 132 </para> 133 </refsect1> 134 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 135</refentry> 136