glXChooseVisual(3G) OpenGL Reference - GLX glXChooseVisual(3G)
NAME
glXChooseVisual - return a visual that matches specified attributes
C SPECIFICATION
XVisualInfo * glXChooseVisual( Display *dpy,
int screen,
int *attribList )
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 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, NULL is returned.
To free the data returned by this function, use XFree.
All boolean GLX attributes default to False except GLXUSEGL, which
defaults to True. All integer GLX attributes default to 0. The defaults
for enumerated attributes are specified below.
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:
GLXUSEGL Ignored. Only visuals that can be rendered with
GLX are considered.
GLXBUFFERSIZE 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 GLXRGBA is
asserted.
Page 1
glXChooseVisual(3G) OpenGL Reference - GLX glXChooseVisual(3G)
GLXLEVEL 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.
GLXRGBA If present, only TrueColor and DirectColor visuals
are considered. Otherwise, only PseudoColor and
StaticColor visuals are considered.
GLXDOUBLEBUFFER If present, only double-buffered visuals are
considered. Otherwise, only single-buffered
visuals are considered.
GLXSTEREO If present, only stereo visuals are considered.
Otherwise, only monoscopic visuals are considered.
GLXAUXBUFFERS 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.
GLXREDSIZE 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.
GLXGREENSIZE 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.
GLXBLUESIZE 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.
GLXALPHASIZE 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.
GLXDEPTHSIZE Must be followed by a nonnegative minimum size
specification. If this value is zero, visuals with
no depth buffer are preferred. Otherwise, the
Page 2
glXChooseVisual(3G) OpenGL Reference - GLX glXChooseVisual(3G)
largest available depth buffer of at least the
minimum size is preferred.
GLXSTENCILSIZE 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.
GLXACCUMREDSIZE 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.
GLXACCUMGREENSIZE 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.
GLXACCUMBLUESIZE 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.
GLXACCUMALPHASIZE 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.
GLXSAMPLEBUFFERSSGIS
Must be followed by the minimum acceptable number
of multisample buffers. Visuals with the smallest
number of multisample buffers that meet or exceed
this minimum number are preferred. Currently
operation with more than one multisample buffer is
undefined, so the returned value will be either
zero or one. Note that multisampling is supported
only on RealityEngine.
GLXSAMPLESSGIS Must be followed by the minimum number of samples
required in multisample buffers. Visuals with the
smallest number of samples that meet or exceed the
specified minimum number are preferred. Note that
it is possible for color samples in the multisample
buffer to have fewer bits than colors in the main
color buffers. However, multisampled colors
maintain at least as much color resolution in
Page 3
glXChooseVisual(3G) OpenGL Reference - GLX glXChooseVisual(3G)
aggregate as the main color buffers.
GLXTRANSPARENTTYPEEXT
Must be followed by one of GLXNONEEXT,
GLXTRANSPARENTRGBEXT, GLXTRANSPARENTINDEXEXT.
If GLXNONEEXT is specified, then only opaque
visuals will be considered; if
GLXTRANSPARENTRGBEXT is specified, then only
transparent, RGBA visuals will be considered; if
GLXTRANSPARENTINDEXEXT is specified, then only
transparent, indexed visuals will be considered.
If not specified, the value GLXNONEEXT is used.
GLXTRANSPARENTINDEXVALUEEXT
Must be followed by an integer value indicating the
transparent index value; the value must be between
0 and the maximum framebuffer value for indices.
Only visuals that use the specified transparent
index value will be considered.
This attribute is ignored during visual selection
unless it is explicitly specified and
GLXTRANSPARENTTYPEEXT is specified as
GLXTRANSPARENTINDEXEXT.
GLXTRANSPARENTREDVALUEEXT
Must be followed by an integer value indicating the
transparent red value; the value must be between 0
and the maximum framebuffer value for red. Only
visuals that use the specified transparent red
value will be considered.
This attribute is ignored during visual selection
unless it is explicitly specified and
GLXTRANSPARENTTYPEEXT is specified as
GLXTRANSPARENTRGBEXT.
GLXTRANSPARENTGREENVALUEEXT
Must be followed by an integer value indicating the
transparent red value; the value must be between 0
and the maximum framebuffer value for red. Only
visuals that use the specified transparent red
value will be considered.
This attribute is ignored during visual selection
unless it is explicitly specified and
GLXTRANSPARENTTYPEEXT is specified as
GLXTRANSPARENTRGBEXT.
GLXTRANSPARENTBLUEVALUEEXT
Must be followed by an integer value indicating the
transparent red value; the value must be between 0
Page 4
glXChooseVisual(3G) OpenGL Reference - GLX glXChooseVisual(3G)
and the maximum framebuffer value for red. Only
visuals that use the specified transparent red
value will be considered.
This attribute is ignored during visual selection
unless it is explicitly specified and
GLXTRANSPARENTTYPEEXT is specified as
GLXTRANSPARENTRGBEXT.
GLXTRANSPARENTALPHAVALUEEXT
Must be followed by an integer value. This
attribute is always ignored; it is for future use
only.
GLXVISUALCAVEATEXT Must be followed by one of GLXNONEEXT,
GLXSLOWVISUALEXT, GLXNONCONFORMANTEXT. If
GLXNONEEXT is specified, then only visuals with
no caveats will be considered; if
GLXSLOWVISUALEXT, is specified then only slow
visuals will be considered; if
GLXNONCONFORMANTEXT is specified then only non-
conformant visuals will be considered.
This attribute is ignored during visual selection
unless it is explicitly specified.
GLXXVISUALTYPEEXT Must be followed by one of GLXTRUECOLOREXT,
GLXDIRECTCOLOREXT, GLXPSEUDOCOLOREXT,
GLXSTATICCOLOREXT, GLXGRAYSCALEEXT,
GLXSTATICGRAYEXT, indicating the desired X
visual type.
If GLXRGBA is in attribList, then only
GLXTRUECOLOREXT and GLXDIRECTCOLOREXT can
produce a match. If GLXXVISUALTYPEEXT is not in
attribList, and if all other attributes are
equivalent, then a TrueColor visual will be chosen
in preference to a DirectColor visual.
If GLXRGBA is not in attribList, then only
GLXPSEUDOCOLOREXT and GLXSTATICCOLOREXT can
produce a match. If GLXXVISUALTYPEEXT is not in
attribList, and if all other attributes are
equivalent, then a PseudoColor visual will be
chosen in preference to a StaticColor visual.
The tokens GLXGRAYSCALEEXT and
GLXSTATICGRAYEXT will not match current OpenGL
enabled visuals, but are included for future use.
Page 5
glXChooseVisual(3G) OpenGL Reference - GLX glXChooseVisual(3G)
EXAMPLES
attribList =
{GLXRGBA, GLXREDSIZE, 4, GLXGREENSIZE, 4, GLXBLUESIZE,
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 glXChooseVisual.
GLX implementers are strongly discouraged, but not proscribed, 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 GLXBUFFERSIZE.
is one of the pixmap depths supported by the X server.
GLXSAMPLEBUFFERSSGIS and GLXSAMPLESSGIS are not valid attributes
unless the SGISmultisample extension is supported.
GLXXVISUALTYPEEXT, GLXTRANSPARENTTYPEEXT,
GLXTRANSPARENTINDEXVALUEEXT, GLXTRANSPARENTREDVALUEEXT,
GLXTRANSPARENTGREENVALUEEXT, GLXTRANSPARENTBLUEVALUEEXT, and
GLXTRANSPARENTALPHAVALUEEXT are not valid attributes unless the
EXTvisualinfo extension is supported.
GLXVISUALCAVEATEXT is not a valid attribute unless the
EXTvisualrating extension is supported.
ERRORS
NULL is returned if an undefined GLX attribute is encountered in
attribList.
Page 6
glXChooseVisual(3G) OpenGL Reference - GLX glXChooseVisual(3G)
MACHINE DEPENDENCIES
The SGISmultisample extension is supported only on RealityEngine,
RealityEngine2, and VTX systems and InfiniteReality systems.
SEE ALSO
glXCreateContext, glXGetConfig
Page 7