Opentk/Source/Bind/Specifications/Docs/GL/glXMakeContextCurrent.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 id="glXMakeContextCurrent">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glXMakeContextCurrent</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glXMakeContextCurrent</refname>
        <refpurpose>attach a GLX context to a GLX drawable</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>Bool <function>glXMakeContextCurrent</function></funcdef>
                <paramdef>Display * <parameter>display</parameter></paramdef>
                <paramdef>GLXDrawable <parameter>draw</parameter></paramdef>
                <paramdef>GLXDrawable <parameter>read</parameter></paramdef>
                <paramdef>GLXContext <parameter>ctx</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>display</parameter></term>
            <listitem>
                <para>
                    Specifies the connection to the X server.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>draw</parameter></term>
            <listitem>
                <para>
                    Specifies a GLX drawable to render into.
                    Must be an XID representing a GLXWindow, GLXPixmap, or GLXPbuffer.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>read</parameter></term>
            <listitem>
                <para>
                    Specifies a GLX drawable to read from.
                    Must be an XID representing a GLXWindow, GLXPixmap, or GLXPbuffer.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>ctx</parameter></term>
            <listitem>
                <para>
                    Specifies the GLX context to be bound to <parameter>read</parameter> and <parameter>ctx</parameter>.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glXMakeContextCurrent</function> binds <parameter>ctx</parameter> to the current rendering thread and to the <parameter>draw</parameter>
            and <parameter>read</parameter> GLX drawables. <parameter>draw</parameter> and <parameter>read</parameter> may be the same.
        </para>
        <para>
            <parameter>draw</parameter> is used for all OpenGL operations except:
        </para>
        <para>
            Any pixel data that are read based on the value of <constant>GLX_READ_BUFFER</constant>.
            Note that accumulation operations use the value of <constant>GLX_READ_BUFFER</constant>,
            but are not allowed unless <parameter>draw</parameter> is identical to <parameter>read</parameter>.
        </para>
        <para>
            Any depth values that are retrieved by <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>.
        </para>
        <para>
            Any stencil values that are retrieved by <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> or
            <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>.
        </para>
        <para>
            Frame buffer values are taken from <parameter>draw</parameter>.
        </para>
        <para>
            If the current rendering thread has a current rendering context, that
            context is flushed and replaced by <parameter>ctx</parameter>.
        </para>
        <para>
            The first time that <parameter>ctx</parameter> is made current, the viewport and scissor
            dimensions are set to the size of the <parameter>draw</parameter> drawable.  The viewport
            and scissor are not modified when <parameter>ctx</parameter> is subsequently made current.
        </para>
        <para>
            To release the current context without assigning a new one,
            call <function>glXMakeContextCurrent</function> with <parameter>draw</parameter> and <parameter>read</parameter> set to <constant>None</constant> and <parameter>ctx</parameter>
            set to <constant>NULL</constant>.
        </para>
        <para>
            <function>glXMakeContextCurrent</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>
            <function>glXMakeContextCurrent</function> is available only if the GLX version is 1.3 or greater.
        </para>
        <para>
            If the GLX version is 1.1 or 1.0, the GL version must be 1.0.
            If the GLX version is 1.2, then the GL version must be 1.1.
            If the GLX version is 1.3, then the GL version must be 1.2.
        </para>
        <para>
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>BadMatch</constant> is generated if <parameter>draw</parameter> and <parameter>read</parameter> are not compatible.
        </para>
        <para>
            <constant>BadAccess</constant> is generated if <parameter>ctx</parameter> is current to some other
            thread.
        </para>
        <para>
            <constant>GLXContextState</constant> is generated if there is a current rendering
            context and its render mode is either <constant>GLX_FEEDBACK</constant> or
            <constant>GLX_SELECT</constant>.
        </para>
        <para>
            <constant>GLXBadContext</constant> is generated if <parameter>ctx</parameter> is not a valid GLX
            rendering context.
        </para>
        <para>
            <constant>GLXBadDrawable</constant> is generated if <parameter>draw</parameter> or <parameter>read</parameter> is not a valid 
            GLX drawable.
        </para>
        <para>
            <constant>GLXBadWindow</constant> is generated if the underlying X window for either
            <parameter>draw</parameter> or <parameter>read</parameter> is no longer valid.
        </para>
        <para>
            <constant>GLXBadCurrentDrawable</constant> is generated if the previous context of
            the calling thread has unflushed commands and the previous drawable is
            no longer valid.
        </para>
        <para>
            <constant>BadAlloc</constant> is generated if the X server does not have enough
            resources to allocate the buffers.
        </para>
        <para>
            <constant>BadMatch</constant> is generated if:
        </para>
        <para>
            <parameter>draw</parameter> and <parameter>read</parameter> cannot fit into frame buffer memory simultaneously.
        </para>
        <para>
            <parameter>draw</parameter> or <parameter>read</parameter> is a GLXPixmap and <parameter>ctx</parameter> is a direct-rendering
            context.
        </para>
        <para>
            <parameter>draw</parameter> or <parameter>read</parameter> is a GLXPixmap and <parameter>ctx</parameter> was previously bound to a
            GLXWindow or GLXPbuffer.
        </para>
        <para>
            <parameter>draw</parameter> or <parameter>read</parameter> is a GLXWindow or GLXPbuffer and <parameter>ctx</parameter> was
            previously bound to a GLXPixmap.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glXCreateNewContext</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXCreateWindow</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXCreatePixmap</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXCreatePbuffer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXDestroyContext</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXGetCurrentContext</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXGetCurrentDisplay</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXGetCurrentDrawable</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXGetCurrentReadDrawable</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXMakeCurrent</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>