GLXCHOOSEVISUAL() MachTen Programmer’s Manual GLXCHOOSEVISUAL()

NAME
glXChooseVisual - return a visual that matches specified
attributes

C SPECIFICATION
XVisualInfo* glXChooseVisual( Display *dpy,
int screen,
int *attribList )

delim $$

PARAMETERS
dpy Specifies the connection to the X server.

screen Specifies the screen number.

attribList Specifies a list of boolean attributes and
integer attribute/value pairs. The last
attribute must be None.

DESCRIPTION
glXChooseVisual returns a pointer to an XVisualInfo struc-
ture describing the visual that best meets a minimum spec-
ification. The boolean GLX attributes of the visual that
is returned will match the specified values, and the inte-
ger GLX attributes will meet or exceed the specified mini-
mum 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, NULL is returned. To free the
data returned by this function, use XFree.

All boolean GLX attributes default to False except
GLX_USE_GL, which defaults to True. All integer GLX
attributes default to zero. Default specifications are
superseded by attributes included in attribList. Boolean
attributes included in attribList are understood to be
True. Integer attributes and enumerated type attributes
are followed immediately by the corresponding desired or
minimum value. The list must be terminated with None.

The interpretations of the various GLX visual attributes
are as follows:

GLX_USE_GL Ignored. Only visuals that can be
rendered with GLX are considered.

GLX_BUFFER_SIZE Must be followed by a nonnegative
integer that indicates the desired
color index buffer size. The small-
est index buffer of at least the
specified size is preferred.
Ignored if GLX_RGBA is asserted.

GLX_LEVEL 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 over-
lay frame buffer, level two the sec-
ond overlay frame buffer, and so on.
Negative buffer levels correspond to
underlay frame buffers.

GLX_RGBA If present, only TrueColor and
DirectColor visuals are considered.
Otherwise, only PseudoColor and
StaticColor visuals are considered.

GLX_DOUBLEBUFFER If present, only double-buffered
visuals are considered. Otherwise,
only single-buffered visuals are
considered.

GLX_STEREO If present, only stereo visuals are
considered. Otherwise, only mono-
scopic visuals are considered.

GLX_AUX_BUFFERS Must be followed by a nonnegative
integer that indicates the desired
number of auxiliary buffers. Visu-
als with the smallest number of
auxiliary buffers that meets or
exceeds the specified number are
preferred.

GLX_RED_SIZE Must be followed by a nonnegative
minimum size specification. If this
value is zero, the smallest avail-
able red buffer is preferred. Oth-
erwise, the largest available red
buffer of at least the minimum size
is preferred.

GLX_GREEN_SIZE Must be followed by a nonnegative
minimum size specification. If this
value is zero, the smallest avail-
able green buffer is preferred.
Otherwise, the largest available
green buffer of at least the minimum
size is preferred.

GLX_BLUE_SIZE Must be followed by a nonnegative
minimum size specification. If this
value is zero, the smallest avail-
able blue buffer is preferred. Oth-
erwise, the largest available blue
buffer of at least the minimum size
is preferred.

GLX_ALPHA_SIZE Must be followed by a nonnegative
minimum size specification. If this
value is zero, the smallest avail-
able alpha buffer is preferred.
Otherwise, the largest available
alpha buffer of at least the minimum
size is preferred.

GLX_DEPTH_SIZE 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.

GLX_STENCIL_SIZE 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 pre-
ferred.

GLX_ACCUM_RED_SIZE 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.

GLX_ACCUM_GREEN_SIZE 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.

GLX_ACCUM_BLUE_SIZE 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.

GLX_ACCUM_ALPHA_SIZE 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.

EXAMPLES
attribList =
{GLX_RGBA, GLX_RED_SIZE, 4, GLX_GREEN_SIZE, 4,
GLX_BLUE_SIZE, 4, None};

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.

NOTES
XVisualInfo is defined in Xutil.h. It is a structure that
includes visual, visualID, screen, and depth elements.

glXChooseVisual is implemented as a client-side utility
using only XGetVisualInfo and glXGetConfig. Calls to
these two routines can be used to implement selection
algorithms other than the generic one implemented by glX-
ChooseVisual.

GLX implementers are strongly discouraged, but not pro-
scribed, from changing the selection algorithm used by
glXChooseVisual. Therefore, selections may change from
release to release of the client-side library.

There is no direct filter for picking only visuals that
support GLXPixmaps. GLXPixmaps are supported for visuals
whose GLX_BUFFER_SIZE is one of the pixmap depths sup-
ported by the X server.

ERRORS
NULL is returned if an undefined GLX attribute is encoun-
tered in attribList.