<?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 id="glXMakeCurrent">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glXMakeCurrent</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glXMakeCurrent</refname>
        <refpurpose>attach a GLX context to a window or a GLX pixmap</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>Bool <function>glXMakeCurrent</function></funcdef>
                <paramdef>Display * <parameter>dpy</parameter></paramdef>
                <paramdef>GLXDrawable <parameter>drawable</parameter></paramdef>
                <paramdef>GLXContext <parameter>ctx</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>dpy</parameter></term>
            <listitem>
                <para>
                    Specifies the connection to the X server.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>drawable</parameter></term>
            <listitem>
                <para>
                    Specifies a GLX drawable.
                    Must be either an X window ID or a GLX pixmap ID.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>ctx</parameter></term>
            <listitem>
                <para>
                    Specifies a GLX rendering context that is to be attached to <parameter>drawable</parameter>.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glXMakeCurrent</function> does two things:
            It makes <parameter>ctx</parameter> the current GLX rendering context of the calling thread,
            replacing the previously current context if there was one,
            and it attaches <parameter>ctx</parameter> to a GLX drawable,
            either a window or a GLX pixmap.
            As a result of these two actions,
            subsequent GL rendering calls
            use rendering context <parameter>ctx</parameter> to modify GLX drawable <parameter>drawable</parameter> (for
            reading and writing).
            Because <function>glXMakeCurrent</function> always replaces the current rendering context with <parameter>ctx</parameter>,
            there can be only one current context per thread.
        </para>
        <para>
            Pending commands to the
            previous context, if any, are flushed before it is released.
        </para>
        <para>
            The first time <parameter>ctx</parameter> is made current to any thread,
            its viewport is set to the full size of <parameter>drawable</parameter>.
            Subsequent calls by any thread to <function>glXMakeCurrent</function> with <parameter>ctx</parameter>
            have no effect on its viewport.
        </para>
        <para>
            To release the current context without assigning a new one,
            call <function>glXMakeCurrent</function> with <parameter>drawable</parameter> set to <constant>None</constant> and <parameter>ctx</parameter>
            set to <constant>NULL</constant>.
        </para>
        <para>
            <function>glXMakeCurrent</function> returns <constant>True</constant> if it is successful,
            <constant>False</constant> otherwise.
            If <constant>False</constant> is returned, the previously current rendering context
            and drawable (if any) remain unchanged.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            A <emphasis>process</emphasis> is a single-execution environment,
            implemented in a single address space,
            consisting of one or more threads.
        </para>
        <para>
            A <emphasis>thread</emphasis> is one of a set of subprocesses that share
            a single address space,
            but maintain separate program counters,
            stack spaces,
            and other related global data.
            A <emphasis>thread</emphasis> that is the only member of its subprocess group
            is equivalent to a <emphasis>process</emphasis>.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>BadMatch</constant> is generated if <parameter>drawable</parameter> was not
            created with the same X screen and visual as <parameter>ctx</parameter>.
            It is also generated if <parameter>drawable</parameter> is <constant>None</constant> and <parameter>ctx</parameter> is not
            <constant>NULL</constant>.
        </para>
        <para>
            <constant>BadAccess</constant> is generated if <parameter>ctx</parameter> was current to another thread
            at the time <function>glXMakeCurrent</function> was called.
        </para>
        <para>
            <constant>GLXBadDrawable</constant> is generated if <parameter>drawable</parameter> is not a valid GLX drawable.
        </para>
        <para>
            <constant>GLXBadContext</constant> is generated if <parameter>ctx</parameter> is not a valid GLX context.
        </para>
        <para>
            <constant>GLXBadContextState</constant> is generated if <function>glXMakeCurrent</function> is executed between
            the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
        </para>
        <para>
            <constant>GLXBadContextState</constant> is also generated if the rendering context current
            to the calling thread has GL renderer state <constant>GLX_FEEDBACK</constant> or
            <constant>GLX_SELECT</constant>.
        </para>
        <para>
            <constant>GLXBadCurrentWindow</constant> is generated if there are pending GL
            commands for the previous context and the current drawable is
            a window that is no longer valid.
        </para>
        <para>
            <constant>BadAlloc</constant> may be generated if the server has delayed allocation
            of ancillary buffers until <function>glXMakeCurrent</function> is called, only to find that it has
            insufficient resources to complete the allocation.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glXCreateContext</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXCreateGLXPixmap</refentrytitle></citerefentry>
            <citerefentry><refentrytitle>glXGetCurrentContext</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXGetCurrentDisplay</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXGetCurrentDrawable</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXGetCurrentReadDrawable</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
        </para>
    </refsect1>
</refentry>
