upstream-man-pages/man2/glXSwapBuffers.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glXSwapBuffers">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glXSwapBuffers</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glXSwapBuffers</refname>
  17         <refpurpose>exchange front and back buffers</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glXSwapBuffers</function></funcdef>
  23                 <paramdef>Display * <parameter>dpy</parameter></paramdef>
  24                 <paramdef>GLXDrawable <parameter>drawable</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27     </refsynopsisdiv>
  28     <!-- eqn: ignoring delim $$ -->
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>dpy</parameter></term>
  33             <listitem>
  34                 <para>
  35                     Specifies the connection to the X server.
  36                 </para>
  37             </listitem>
  38         </varlistentry>
  39         <varlistentry>
  40             <term><parameter>drawable</parameter></term>
  41             <listitem>
  42                 <para>
  43                     Specifies the drawable whose buffers are to be swapped.
  44                 </para>
  45             </listitem>
  46         </varlistentry>
  47         </variablelist>
  48     </refsect1>
  49     <refsect1 id="description"><title>Description</title>
  50         <para>
  51             <function>glXSwapBuffers</function> promotes the contents of the back buffer of <parameter>drawable</parameter> to become
  52             the contents of the front buffer of <parameter>drawable</parameter>.
  53             The contents of the back buffer then become undefined.
  54             The update typically takes place during the vertical retrace of
  55             the monitor,
  56             rather than immediately after <function>glXSwapBuffers</function> is called.
  57         </para>
  58         <para>
  59             <function>glXSwapBuffers</function> performs an implicit <citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry> before it returns.
  60             Subsequent OpenGL commands may be issued immediately after calling <function>glXSwapBuffers</function>,
  61             but are not executed until the buffer exchange is completed.
  62         </para>
  63         <para>
  64             If <parameter>drawable</parameter> was not created with respect to a double-buffered visual,
  65             <function>glXSwapBuffers</function> has no effect,
  66             and no error is generated.
  67         </para>
  68     </refsect1>
  69     <refsect1 id="notes"><title>Notes</title>
  70         <para>
  71             The contents of the back buffer become undefined after
  72             a swap. Note that this applies to pixel buffers as well as windows.
  73         </para>
  74         <para>
  75             All GLX rendering contexts share the same notion of which are front buffers
  76             and which are back buffers.
  77             One consequence is that when multiple clients are rendering to the same
  78             double-buffered window,
  79             all of them should finish rendering before one of them issues the command
  80             to swap buffers.
  81             The clients are responsible for implementing this synchronization.
  82             Typically this is accomplished by executing <citerefentry><refentrytitle>glFinish</refentrytitle></citerefentry> and then
  83             using a semaphore in shared memory to rendezvous before swapping.
  84         </para>
  85     </refsect1>
  86     <refsect1 id="errors"><title>Errors</title>
  87         <para>
  88             <constant>GLXBadDrawable</constant> is generated if <parameter>drawable</parameter> is not a valid GLX drawable.
  89         </para>
  90         <para>
  91             <constant>GLXBadCurrentWindow</constant> is generated if <parameter>dpy</parameter> and <parameter>drawable</parameter> are
  92             respectively the display and drawable associated with the current
  93             context of the calling thread, and <parameter>drawable</parameter> identifies a window that
  94             is no longer valid.
  95         </para>
  96     </refsect1>
  97     <refsect1 id="seealso"><title>See Also</title>
  98         <para>
  99             <citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry>
 100         </para>
 101     </refsect1>
 102     <refsect1 id="Copyright"><title>Copyright</title>
 103         <para>
 104             Copyright <trademark class="copyright"></trademark> 1991-2006
 105             Silicon Graphics, Inc. This document is licensed under the SGI
 106             Free Software B License. For details, see
 107             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 108         </para>
 109     </refsect1>
 110 </refentry>