<?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="glXGetConfig">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glXGetConfig</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glXGetConfig</refname>
        <refpurpose>return information about GLX visuals</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>int <function>glXGetConfig</function></funcdef>
                <paramdef>Display * <parameter>dpy</parameter></paramdef>
                <paramdef>XVisualInfo * <parameter>vis</parameter></paramdef>
                <paramdef>int <parameter>attrib</parameter></paramdef>
                <paramdef>int * <parameter>value</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>vis</parameter></term>
            <listitem>
                <para>
                    Specifies the visual to be queried.
                    It is a pointer to an <constant>XVisualInfo</constant> structure,
                    not a visual ID or a pointer to a <constant>Visual</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>attrib</parameter></term>
            <listitem>
                <para>
                    Specifies the visual attribute to be returned.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>value</parameter></term>
            <listitem>
                <para>
                    Returns the requested value.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glXGetConfig</function> sets <parameter>value</parameter> to the <parameter>attrib</parameter> value of windows or GLX pixmaps
            created with respect to <parameter>vis</parameter>.
            <function>glXGetConfig</function> returns an error code if it fails for any reason.
            Otherwise, zero is returned.
        </para>
        <para>
            <parameter>attrib</parameter> is one of the following:
        </para>
        <para>
        </para>
        <variablelist>
            <varlistentry>
                <term><constant>GLX_USE_GL</constant></term>
                <listitem>
                    <para>
                        <constant>True</constant> if OpenGL rendering is supported by this visual,
                        <constant>False</constant> otherwise.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_BUFFER_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits per color buffer.
                        For RGBA visuals, <constant>GLX_BUFFER_SIZE</constant> is the sum of
                        <constant>GLX_RED_SIZE</constant>,
                        <constant>GLX_GREEN_SIZE</constant>,
                        <constant>GLX_BLUE_SIZE</constant>, and
                        <constant>GLX_ALPHA_SIZE</constant>.
                        For color index visuals, <constant>GLX_BUFFER_SIZE</constant> is the size of the
                        color indexes.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_LEVEL</constant></term>
                <listitem>
                    <para>
                        Frame buffer level of the visual.
                        Level zero is the default frame buffer.
                        Positive levels correspond to frame buffers that overlay the default buffer,
                        and negative levels correspond to frame buffers that underlay the default
                        buffer.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_RGBA</constant></term>
                <listitem>
                    <para>
                        <constant>True</constant> if color buffers store red, green, blue, and alpha values.
                        <constant>False</constant> if they store color indexes.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_DOUBLEBUFFER</constant></term>
                <listitem>
                    <para>
                        <constant>True</constant> if color buffers exist in front/back pairs that can be swapped,
                        <constant>False</constant> otherwise.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_STEREO</constant></term>
                <listitem>
                    <para>
                        <constant>True</constant> if color buffers exist in left/right pairs,
                        <constant>False</constant> otherwise.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_AUX_BUFFERS</constant></term>
                <listitem>
                    <para>
                        Number of auxiliary color buffers that are available.
                        Zero indicates that no auxiliary color buffers exist.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_RED_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits of red stored in each color buffer.
                        Undefined if <constant>GLX_RGBA</constant> is <constant>False</constant>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_GREEN_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits of green stored in each color buffer.
                        Undefined if <constant>GLX_RGBA</constant> is <constant>False</constant>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_BLUE_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits of blue stored in each color buffer.
                        Undefined if <constant>GLX_RGBA</constant> is <constant>False</constant>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ALPHA_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits of alpha stored in each color buffer.
                        Undefined if <constant>GLX_RGBA</constant> is <constant>False</constant>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_DEPTH_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits in the depth buffer.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_STENCIL_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits in the stencil buffer.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ACCUM_RED_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits of red stored in the accumulation buffer.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ACCUM_GREEN_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits of green stored in the accumulation buffer.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ACCUM_BLUE_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits of blue stored in the accumulation buffer.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ACCUM_ALPHA_SIZE</constant></term>
                <listitem>
                    <para>
                        Number of bits of alpha stored in the accumulation buffer.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            The X protocol allows a single visual ID to be instantiated with
            different numbers of bits per pixel.
            Windows or GLX pixmaps that will be rendered with OpenGL, however,
            must be instantiated with a color buffer depth of <constant>GLX_BUFFER_SIZE</constant>.
        </para>
        <para>
            Although a GLX implementation can export many visuals that support GL
            rendering,
            it must support 
            at least one RGBA visual. This visual must have at 
            least one color buffer,
            a stencil buffer of at least 1 bit,
            a depth buffer of at least 12 bits,
            and an accumulation buffer.
            Alpha bitplanes are optional in this visual.
            However,
            its color buffer size must be as great as that of the
            deepest <constant>TrueColor</constant>, <constant>DirectColor</constant>,
            <constant>PseudoColor</constant>, or <constant>StaticColor</constant> visual supported on level zero,
            and it must itself be made available on level zero.
        </para>
        <para>
            In addition, if the X server exports a <constant>PseudoColor</constant> 
            or <constant>StaticColor</constant> visual on framebuffer level 0, a color index 
            visual is also required on that level.
            It must have  
            at least one color buffer,
            a stencil buffer of at least 1 bit,
            and a depth buffer of at least 12 bits.
            This visual must 
            have as many 
            color bitplanes as the deepest
            <constant>PseudoColor</constant> or <constant>StaticColor</constant> visual supported on level 0.
        </para>
        <para>
            Applications are best written to select the visual that most closely
            meets their requirements.
            Creating windows or GLX pixmaps with unnecessary buffers can result in
            reduced rendering performance as well as poor resource allocation.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <constant>XVisualInfo</constant> is defined in <emphasis>Xutil.h.</emphasis>
            It is a structure that includes <emphasis>visual</emphasis>, <emphasis>visualID</emphasis>, <emphasis>screen</emphasis>, and
            <emphasis>depth</emphasis> elements.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GLX_NO_EXTENSION</constant> is returned if <parameter>dpy</parameter> does not support the GLX
            extension.
        </para>
        <para>
            <constant>GLX_BAD_SCREEN</constant> is returned if the screen of <parameter>vis</parameter> does not correspond
            to a screen.
        </para>
        <para>
            <constant>GLX_BAD_ATTRIBUTE</constant> is returned if <parameter>attrib</parameter> is not a valid GLX attribute.
        </para>
        <para>
            <constant>GLX_BAD_VISUAL</constant> is returned if <parameter>vis</parameter> doesn't support GLX and an
            attribute other than <constant>GLX_USE_GL</constant> is requested.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glXChooseVisual</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXCreateContext</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>
