upstream-man-pages/man2/glXMakeContextCurrent.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="glXMakeContextCurrent">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glXMakeContextCurrent</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glXMakeContextCurrent</refname>
  17         <refpurpose>attach a GLX context to a GLX drawable</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>Bool <function>glXMakeContextCurrent</function></funcdef>
  23                 <paramdef>Display * <parameter>display</parameter></paramdef>
  24                 <paramdef>GLXDrawable <parameter>draw</parameter></paramdef>
  25                 <paramdef>GLXDrawable <parameter>read</parameter></paramdef>
  26                 <paramdef>GLXContext <parameter>ctx</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <!-- eqn: ignoring delim $$ -->
  31     <refsect1 id="parameters"><title>Parameters</title>
  32         <variablelist>
  33         <varlistentry>
  34             <term><parameter>display</parameter></term>
  35             <listitem>
  36                 <para>
  37                     Specifies the connection to the X server.
  38                 </para>
  39             </listitem>
  40         </varlistentry>
  41         <varlistentry>
  42             <term><parameter>draw</parameter></term>
  43             <listitem>
  44                 <para>
  45                     Specifies a GLX drawable to render into.
  46                     Must be an XID representing a GLXWindow, GLXPixmap, or GLXPbuffer.
  47                 </para>
  48             </listitem>
  49         </varlistentry>
  50         <varlistentry>
  51             <term><parameter>read</parameter></term>
  52             <listitem>
  53                 <para>
  54                     Specifies a GLX drawable to read from.
  55                     Must be an XID representing a GLXWindow, GLXPixmap, or GLXPbuffer.
  56                 </para>
  57             </listitem>
  58         </varlistentry>
  59         <varlistentry>
  60             <term><parameter>ctx</parameter></term>
  61             <listitem>
  62                 <para>
  63                     Specifies the GLX context to be bound to <parameter>read</parameter> and <parameter>ctx</parameter>.
  64                 </para>
  65             </listitem>
  66         </varlistentry>
  67         </variablelist>
  68     </refsect1>
  69     <refsect1 id="description"><title>Description</title>
  70         <para>
  71             <function>glXMakeContextCurrent</function> binds <parameter>ctx</parameter> to the current rendering thread and to the <parameter>draw</parameter>
  72             and <parameter>read</parameter> GLX drawables. <parameter>draw</parameter> and <parameter>read</parameter> may be the same.
  73         </para>
  74         <para>
  75             <parameter>draw</parameter> is used for all OpenGL operations except:
  76         </para>
  77         <para>
  78             Any pixel data that are read based on the value of <constant>GLX_READ_BUFFER</constant>.
  79             Note that accumulation operations use the value of <constant>GLX_READ_BUFFER</constant>,
  80             but are not allowed unless <parameter>draw</parameter> is identical to <parameter>read</parameter>.
  81         </para>
  82         <para>
  83             Any depth values that are retrieved by <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>.
  84         </para>
  85         <para>
  86             Any stencil values that are retrieved by <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> or
  87             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>.
  88         </para>
  89         <para>
  90             Frame buffer values are taken from <parameter>draw</parameter>.
  91         </para>
  92         <para>
  93             If the current rendering thread has a current rendering context, that
  94             context is flushed and replaced by <parameter>ctx</parameter>.
  95         </para>
  96         <para>
  97             The first time that <parameter>ctx</parameter> is made current, the viewport and scissor
  98             dimensions are set to the size of the <parameter>draw</parameter> drawable.  The viewport
  99             and scissor are not modified when <parameter>ctx</parameter> is subsequently made current.
 100         </para>
 101         <para>
 102             To release the current context without assigning a new one,
 103             call <function>glXMakeContextCurrent</function> with <parameter>draw</parameter> and <parameter>read</parameter> set to <constant>None</constant> and <parameter>ctx</parameter>
 104             set to <constant>NULL</constant>.
 105         </para>
 106         <para>
 107             <function>glXMakeContextCurrent</function> returns <constant>True</constant> if it is successful,
 108             <constant>False</constant> otherwise.
 109             If <constant>False</constant> is returned, the previously current rendering context
 110             and drawable (if any) remain unchanged.
 111         </para>
 112     </refsect1>
 113     <refsect1 id="notes"><title>Notes</title>
 114         <para>
 115             <function>glXMakeContextCurrent</function> is available only if the GLX version is 1.3 or greater.
 116         </para>
 117         <para>
 118             If the GLX version is 1.1 or 1.0, the GL version must be 1.0.
 119             If the GLX version is 1.2, then the GL version must be 1.1.
 120             If the GLX version is 1.3, then the GL version must be 1.2.
 121         </para>
 122         <para>
 123         </para>
 124     </refsect1>
 125     <refsect1 id="errors"><title>Errors</title>
 126         <para>
 127             <constant>BadMatch</constant> is generated if <parameter>draw</parameter> and <parameter>read</parameter> are not compatible.
 128         </para>
 129         <para>
 130             <constant>BadAccess</constant> is generated if <parameter>ctx</parameter> is current to some other
 131             thread.
 132         </para>
 133         <para>
 134             <constant>GLXContextState</constant> is generated if there is a current rendering
 135             context and its render mode is either <constant>GLX_FEEDBACK</constant> or
 136             <constant>GLX_SELECT</constant>.
 137         </para>
 138         <para>
 139             <constant>GLXBadContext</constant> is generated if <parameter>ctx</parameter> is not a valid GLX
 140             rendering context.
 141         </para>
 142         <para>
 143             <constant>GLXBadDrawable</constant> is generated if <parameter>draw</parameter> or <parameter>read</parameter> is not a valid
 144             GLX drawable.
 145         </para>
 146         <para>
 147             <constant>GLXBadWindow</constant> is generated if the underlying X window for either
 148             <parameter>draw</parameter> or <parameter>read</parameter> is no longer valid.
 149         </para>
 150         <para>
 151             <constant>GLXBadCurrentDrawable</constant> is generated if the previous context of
 152             the calling thread has unflushed commands and the previous drawable is
 153             no longer valid.
 154         </para>
 155         <para>
 156             <constant>BadAlloc</constant> is generated if the X server does not have enough
 157             resources to allocate the buffers.
 158         </para>
 159         <para>
 160             <constant>BadMatch</constant> is generated if:
 161         </para>
 162         <para>
 163             <parameter>draw</parameter> and <parameter>read</parameter> cannot fit into frame buffer memory simultaneously.
 164         </para>
 165         <para>
 166             <parameter>draw</parameter> or <parameter>read</parameter> is a GLXPixmap and <parameter>ctx</parameter> is a direct-rendering
 167             context.
 168         </para>
 169         <para>
 170             <parameter>draw</parameter> or <parameter>read</parameter> is a GLXPixmap and <parameter>ctx</parameter> was previously bound to a
 171             GLXWindow or GLXPbuffer.
 172         </para>
 173         <para>
 174             <parameter>draw</parameter> or <parameter>read</parameter> is a GLXWindow or GLXPbuffer and <parameter>ctx</parameter> was
 175             previously bound to a GLXPixmap.
 176         </para>
 177     </refsect1>
 178     <refsect1 id="seealso"><title>See Also</title>
 179         <para>
 180             <citerefentry><refentrytitle>glXCreateNewContext</refentrytitle></citerefentry>,
 181             <citerefentry><refentrytitle>glXCreateWindow</refentrytitle></citerefentry>,
 182             <citerefentry><refentrytitle>glXCreatePixmap</refentrytitle></citerefentry>,
 183             <citerefentry><refentrytitle>glXCreatePbuffer</refentrytitle></citerefentry>,
 184             <citerefentry><refentrytitle>glXDestroyContext</refentrytitle></citerefentry>,
 185             <citerefentry><refentrytitle>glXGetCurrentContext</refentrytitle></citerefentry>,
 186             <citerefentry><refentrytitle>glXGetCurrentDisplay</refentrytitle></citerefentry>,
 187             <citerefentry><refentrytitle>glXGetCurrentDrawable</refentrytitle></citerefentry>,
 188             <citerefentry><refentrytitle>glXGetCurrentReadDrawable</refentrytitle></citerefentry>,
 189             <citerefentry><refentrytitle>glXMakeCurrent</refentrytitle></citerefentry>
 190         </para>
 191     </refsect1>
 192     <refsect1 id="Copyright"><title>Copyright</title>
 193         <para>
 194             Copyright <trademark class="copyright"></trademark> 1991-2006
 195             Silicon Graphics, Inc. This document is licensed under the SGI
 196             Free Software B License. For details, see
 197             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 198         </para>
 199     </refsect1>
 200 </refentry>