367 lines
16 KiB
XML
367 lines
16 KiB
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="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>
|