xref: /third_party/EGL/sdk/docs/man/docbook4/eglSwapBuffers.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
                            "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry xml:base="" id="eglSwapBuffers">
    <refentryinfo>
         <copyright>
             <year>2003-2014</year>
             <holder>The Khronos Group Inc.</holder>
         </copyright>
    </refentryinfo>
    <refmeta>
        <refentrytitle>eglSwapBuffers</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>eglSwapBuffers</refname>
        <refpurpose>
            post <acronym>EGL</acronym> surface color buffer to a native window
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>EGLBoolean <function>eglSwapBuffers</function></funcdef>
                <paramdef>EGLDisplay <parameter>display</parameter></paramdef>
                <paramdef>EGLSurface <parameter>surface</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
            <varlistentry>
                <term><parameter>display</parameter></term>
                <listitem>
                    <para>
                        Specifies the EGL display connection.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><parameter>surface</parameter></term>
                <listitem>
                    <para>
                        Specifies the EGL drawing surface whose buffers are to be swapped.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            If <parameter>surface</parameter> is a window surface,
            <function>eglSwapBuffers</function> posts its color buffer
            to the associated native window.
        </para>
        <para>
            The contents of ancillary buffers are always undefined after
            calling <function>eglSwapBuffers</function>. The contents of
            the color buffer are left unchanged if the value of the
            <constant>EGL_SWAP_BEHAVIOR</constant> attribute of
            <parameter>surface</parameter> is
            <constant>EGL_BUFFER_PRESERVED</constant>, and are undefined
            if the value is <constant>EGL_BUFFER_DESTROYED</constant>.
            The value of <constant>EGL_SWAP_BEHAVIOR</constant> can be
            set for some surfaces using
            <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>.
        </para>
        <para>
            <function>eglSwapBuffers</function> performs an implicit
            flush operation on the context (<function>glFlush</function>
            for an OpenGL ES or OpenGL context,
            <function>vgFlush</function> for an OpenVG context) bound to
            <parameter>surface</parameter> before swapping. Subsequent
            client API commands may be issued on that context
            immediately after calling
            <function>eglSwapBuffers</function>, but are not executed
            until the buffer exchange is completed.
        </para>
        <para>
            If <parameter>surface</parameter> is a pixel buffer or a pixmap,
            <function>eglSwapBuffers</function>
            has no effect, and no error is generated.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            Attribute <constant>EGL_SWAP_BEHAVIOR</constant> is
            supported only if the EGL version is 1.2 or greater. In
            earlier versions, behavior is as though the attribute
            exists, and always has the value
            <constant>EGL_BUFFER_DESTROYED</constant>.
        </para>
        <para>
            The EGL 1.4 specification was updated to acknowledge that
            ancillary buffers are not necessarily preserved after a
            swap, and that the <constant>EGL_SWAP_BEHAVIOR</constant>
            attribute applies only to the color buffer. This change in
            the specification acknowledged the behavior of many shipping
            implementations, and is not intended to result in behavior
            changes in any existing implementation. Applications which
            require preservation of ancillary buffers across a swap
            should be aware that not all implementations can preserve
            them, and that EGL 1.4 has no way to query whether or not
            they are preserved.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>EGL_FALSE</constant> is returned if swapping of the
            surface buffers fails, <constant>EGL_TRUE</constant> otherwise.
        </para>
        <para>
            <constant>EGL_BAD_DISPLAY</constant> is generated if
            <parameter>display</parameter> is not an EGL display connection.
        </para>
        <para>
            <constant>EGL_NOT_INITIALIZED</constant> is generated if
            <parameter>display</parameter> has not been initialized.
        </para>
        <para>
            <constant>EGL_BAD_SURFACE</constant> is generated if
            <parameter>surface</parameter> is not an EGL drawing surface.
        </para>
        <para>
            <constant>EGL_CONTEXT_LOST</constant> is generated if a power management
            event has occurred. The application must destroy all contexts and
            reinitialise OpenGL ES state and objects to continue rendering.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>eglCopyBuffers</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect3 id="Copyright"><title></title>
        <!-- Content included from copyright.inc.xsl -->
        <imageobject>
                <imagedata fileref="KhronosLogo.jpg" format="jpg" />
        </imageobject>
        <para />
    </refsect3>
</refentry>