upstream-doc/man2/glXMakeCurrent.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="glXMakeCurrent">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glXMakeCurrent</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glXMakeCurrent</refname>
  17         <refpurpose>attach a GLX context to a window or a GLX pixmap</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>Bool <function>glXMakeCurrent</function></funcdef>
  23                 <paramdef>Display * <parameter>dpy</parameter></paramdef>
  24                 <paramdef>GLXDrawable <parameter>drawable</parameter></paramdef>
  25                 <paramdef>GLXContext <parameter>ctx</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28     </refsynopsisdiv>
  29     <!-- eqn: ignoring delim $$ -->
  30     <refsect1 id="parameters"><title>Parameters</title>
  31         <variablelist>
  32         <varlistentry>
  33             <term><parameter>dpy</parameter></term>
  34             <listitem>
  35                 <para>
  36                     Specifies the connection to the X server.
  37                 </para>
  38             </listitem>
  39         </varlistentry>
  40         <varlistentry>
  41             <term><parameter>drawable</parameter></term>
  42             <listitem>
  43                 <para>
  44                     Specifies a GLX drawable.
  45                     Must be either an X window ID or a GLX pixmap ID.
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         <varlistentry>
  50             <term><parameter>ctx</parameter></term>
  51             <listitem>
  52                 <para>
  53                     Specifies a GLX rendering context that is to be attached to <parameter>drawable</parameter>.
  54                 </para>
  55             </listitem>
  56         </varlistentry>
  57         </variablelist>
  58     </refsect1>
  59     <refsect1 id="description"><title>Description</title>
  60         <para>
  61             <function>glXMakeCurrent</function> does two things:
  62             It makes <parameter>ctx</parameter> the current GLX rendering context of the calling thread,
  63             replacing the previously current context if there was one,
  64             and it attaches <parameter>ctx</parameter> to a GLX drawable,
  65             either a window or a GLX pixmap.
  66             As a result of these two actions,
  67             subsequent GL rendering calls
  68             use rendering context <parameter>ctx</parameter> to modify GLX drawable <parameter>drawable</parameter> (for
  69             reading and writing).
  70             Because <function>glXMakeCurrent</function> always replaces the current rendering context with <parameter>ctx</parameter>,
  71             there can be only one current context per thread.
  72         </para>
  73         <para>
  74             Pending commands to the
  75             previous context, if any, are flushed before it is released.
  76         </para>
  77         <para>
  78             The first time <parameter>ctx</parameter> is made current to any thread,
  79             its viewport is set to the full size of <parameter>drawable</parameter>.
  80             Subsequent calls by any thread to <function>glXMakeCurrent</function> with <parameter>ctx</parameter>
  81             have no effect on its viewport.
  82         </para>
  83         <para>
  84             To release the current context without assigning a new one,
  85             call <function>glXMakeCurrent</function> with <parameter>drawable</parameter> set to <constant>None</constant> and <parameter>ctx</parameter>
  86             set to <constant>NULL</constant>.
  87         </para>
  88         <para>
  89             <function>glXMakeCurrent</function> returns <constant>True</constant> if it is successful,
  90             <constant>False</constant> otherwise.
  91             If <constant>False</constant> is returned, the previously current rendering context
  92             and drawable (if any) remain unchanged.
  93         </para>
  94     </refsect1>
  95     <refsect1 id="notes"><title>Notes</title>
  96         <para>
  97             A <emphasis>process</emphasis> is a single-execution environment,
  98             implemented in a single address space,
  99             consisting of one or more threads.
 100         </para>
 101         <para>
 102             A <emphasis>thread</emphasis> is one of a set of subprocesses that share
 103             a single address space,
 104             but maintain separate program counters,
 105             stack spaces,
 106             and other related global data.
 107             A <emphasis>thread</emphasis> that is the only member of its subprocess group
 108             is equivalent to a <emphasis>process</emphasis>.
 109         </para>
 110     </refsect1>
 111     <refsect1 id="errors"><title>Errors</title>
 112         <para>
 113             <constant>BadMatch</constant> is generated if <parameter>drawable</parameter> was not
 114             created with the same X screen and visual as <parameter>ctx</parameter>.
 115             It is also generated if <parameter>drawable</parameter> is <constant>None</constant> and <parameter>ctx</parameter> is not
 116             <constant>NULL</constant>.
 117         </para>
 118         <para>
 119             <constant>BadAccess</constant> is generated if <parameter>ctx</parameter> was current to another thread
 120             at the time <function>glXMakeCurrent</function> was called.
 121         </para>
 122         <para>
 123             <constant>GLXBadDrawable</constant> is generated if <parameter>drawable</parameter> is not a valid GLX drawable.
 124         </para>
 125         <para>
 126             <constant>GLXBadContext</constant> is generated if <parameter>ctx</parameter> is not a valid GLX context.
 127         </para>
 128         <para>
 129             <constant>GLXBadContextState</constant> is generated if <function>glXMakeCurrent</function> is executed between
 130             the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 131         </para>
 132         <para>
 133             <constant>GLXBadContextState</constant> is also generated if the rendering context current
 134             to the calling thread has GL renderer state <constant>GLX_FEEDBACK</constant> or
 135             <constant>GLX_SELECT</constant>.
 136         </para>
 137         <para>
 138             <constant>GLXBadCurrentWindow</constant> is generated if there are pending GL
 139             commands for the previous context and the current drawable is
 140             a window that is no longer valid.
 141         </para>
 142         <para>
 143             <constant>BadAlloc</constant> may be generated if the server has delayed allocation
 144             of ancillary buffers until <function>glXMakeCurrent</function> is called, only to find that it has
 145             insufficient resources to complete the allocation.
 146         </para>
 147     </refsect1>
 148     <refsect1 id="seealso"><title>See Also</title>
 149         <para>
 150             <citerefentry><refentrytitle>glXCreateContext</refentrytitle></citerefentry>,
 151             <citerefentry><refentrytitle>glXCreateGLXPixmap</refentrytitle></citerefentry>
 152             <citerefentry><refentrytitle>glXGetCurrentContext</refentrytitle></citerefentry>,
 153             <citerefentry><refentrytitle>glXGetCurrentDisplay</refentrytitle></citerefentry>,
 154             <citerefentry><refentrytitle>glXGetCurrentDrawable</refentrytitle></citerefentry>,
 155             <citerefentry><refentrytitle>glXGetCurrentReadDrawable</refentrytitle></citerefentry>,
 156             <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry>
 157         </para>
 158     </refsect1>
 159     <refsect1 id="Copyright"><title>Copyright</title>
 160         <para>
 161             Copyright <trademark class="copyright"></trademark> 1991-2006
 162             Silicon Graphics, Inc. This document is licensed under the SGI
 163             Free Software B License. For details, see
 164             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 165         </para>
 166     </refsect1>
 167 </refentry>