<?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="glXChooseVisual">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glXChooseVisual</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glXChooseVisual</refname>
        <refpurpose>return a visual that matches specified attributes</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>XVisualInfo* <function>glXChooseVisual</function></funcdef>
                <paramdef>Display * <parameter>dpy</parameter></paramdef>
                <paramdef>int <parameter>screen</parameter></paramdef>
                <paramdef>int * <parameter>attribList</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>screen</parameter></term>
            <listitem>
                <para>
                    Specifies the screen number.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>attribList</parameter></term>
            <listitem>
                <para>
                    Specifies a list of boolean attributes and integer attribute/value pairs.
                    The last attribute must be <constant>None</constant>.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glXChooseVisual</function> returns a pointer to an XVisualInfo structure describing the visual
            that best meets a minimum specification.
            The boolean GLX attributes of the visual that is returned will match the
            specified values,
            and the integer GLX attributes will meet or exceed the specified
            minimum values. 
            If all other attributes are equivalent, then TrueColor and PseudoColor
            visuals have priority over DirectColor and StaticColor visuals,
            respectively.
            If no conforming visual exists, <constant>NULL</constant> is returned.
            To free the data returned by this function, use <function>XFree</function>.
        </para>
        <para>
            All boolean GLX attributes default to <constant>False</constant>
            except <constant>GLX_USE_GL</constant>,
            which defaults to <constant>True</constant>.
            All integer GLX attributes default to zero.
            Default specifications are superseded by attributes included in <parameter>attribList</parameter>.
            Boolean attributes included in <parameter>attribList</parameter> are understood to be <constant>True</constant>.
            Integer attributes and enumerated type attributes are followed immediately 
            by the corresponding desired or
            minimum value.
            The list must be terminated with <constant>None</constant>.
        </para>
        <para>
            The interpretations of the various GLX visual attributes are as follows:
        </para>
        <variablelist>
            <varlistentry>
                <term><constant>GLX_USE_GL</constant></term>
                <listitem>
                    <para>
                        Ignored.
                        Only visuals that can be rendered with GLX are considered.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_BUFFER_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative integer that indicates the desired
                        color index buffer size.
                        The smallest index buffer of at least the specified size is preferred.
                        Ignored if <constant>GLX_RGBA</constant> is asserted.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_LEVEL</constant></term>
                <listitem>
                    <para>
                        Must be followed by an integer buffer-level specification.
                        This specification is honored exactly.
                        Buffer level zero corresponds to the main frame buffer of the display.
                        Buffer level one is the first overlay frame buffer, level two the second
                        overlay frame buffer, and so on.
                        Negative buffer levels correspond to underlay frame buffers.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_RGBA</constant></term>
                <listitem>
                    <para>
                        If present,
                        only TrueColor and DirectColor visuals are considered.
                        Otherwise,
                        only PseudoColor and StaticColor visuals are considered.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_DOUBLEBUFFER</constant></term>
                <listitem>
                    <para>
                        If present,
                        only double-buffered visuals are considered.
                        Otherwise,
                        only single-buffered visuals are considered.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_STEREO</constant></term>
                <listitem>
                    <para>
                        If present,
                        only stereo visuals are considered.
                        Otherwise,
                        only monoscopic visuals are considered.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_AUX_BUFFERS</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative integer that indicates the desired
                        number of auxiliary buffers.
                        Visuals with the 
                        smallest number of auxiliary buffers that meets or exceeds
                        the specified number are preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_RED_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        the smallest available red buffer is preferred.
                        Otherwise, the largest available red buffer of at least the minimum size
                        is preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_GREEN_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        the smallest available green buffer is preferred.
                        Otherwise, the largest available green buffer of at least the minimum size
                        is preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_BLUE_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        the smallest available blue buffer is preferred.
                        Otherwise, the largest available blue buffer of at least the minimum size
                        is preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ALPHA_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        the smallest available alpha buffer is preferred.
                        Otherwise, the largest available alpha buffer of at least the minimum size
                        is preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_DEPTH_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        visuals with no depth buffer are preferred.
                        Otherwise, the largest available depth buffer of at least the minimum size
                        is preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_STENCIL_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative integer that indicates the desired
                        number of stencil bitplanes.
                        The smallest stencil buffer of at least the specified size is preferred.
                        If the desired value is zero,
                        visuals with no stencil buffer are preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ACCUM_RED_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        visuals with no red accumulation buffer are preferred.
                        Otherwise, the largest possible red accumulation buffer
                        of at least the minimum size is preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ACCUM_GREEN_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        visuals with no green accumulation buffer are preferred.
                        Otherwise, the largest possible green accumulation buffer
                        of at least the minimum size is preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ACCUM_BLUE_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        visuals with no blue accumulation buffer are preferred.
                        Otherwise, the largest possible blue accumulation buffer
                        of at least the minimum size is preferred.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_ACCUM_ALPHA_SIZE</constant></term>
                <listitem>
                    <para>
                        Must be followed by a nonnegative minimum size specification.
                        If this value is zero,
                        visuals with no alpha accumulation buffer are preferred.
                        Otherwise, the largest possible alpha accumulation buffer
                        of at least the minimum size is preferred.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="examples"><title>Examples</title>
        <para>
        </para>
        <variablelist>
            <varlistentry>
                <term><parameter>attribList</parameter> =</term>
                <listitem>
                    <para>
                        {<constant>GLX_RGBA</constant>,
                        <constant>GLX_RED_SIZE</constant>, 4,
                        <constant>GLX_GREEN_SIZE</constant>, 4,
                        <constant>GLX_BLUE_SIZE</constant>, 4,
                        <constant>None</constant>};
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            Specifies a single-buffered RGB visual in the normal frame buffer,
            not an overlay or underlay buffer.
            The returned visual supports at least four bits each of red,
            green, and blue,
            and possibly no bits of alpha.
            It does not support color index mode,
            double-buffering, or stereo display.
            It may or may not have one or more auxiliary color buffers,
            a depth buffer,
            a stencil buffer,
            or an accumulation buffer.
        </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>
        <para>
            <function>glXChooseVisual</function> is implemented as a client-side utility using only <function>XGetVisualInfo</function>
            and <citerefentry><refentrytitle>glXGetConfig</refentrytitle></citerefentry>.
            Calls to these two routines can be used to implement selection algorithms
            other than the generic one implemented by <function>glXChooseVisual</function>.
        </para>
        <para>
            GLX implementations are strongly discouraged,
            but not proscribed,
            from changing the selection algorithm used by <function>glXChooseVisual</function>.
            Therefore, selections may change from release to release
            of the client-side library.
        </para>
        <para>
            There is no direct filter for picking only visuals that
            support GLXPixmaps.
            GLXPixmaps are supported for visuals whose
            <constant>GLX_BUFFER_SIZE</constant>
            is one of the pixmap depths supported by the X server.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>NULL</constant> is returned if an undefined GLX attribute is encountered in
            <parameter>attribList</parameter>.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glXCreateContext</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXGetConfig</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>
