GLXCHOOSEFBCONFIG(3gl)GLXCHOOSEFBCONFIG(3gl)NAMEglXChooseFBConfig - return a visual that matches specified attributes
C SPECIFICATION
GLXFBConfig* glXChooseFBConfig( Display *dpy,
int screen,
int *attribList,
int *nelements )
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.
nelements Specifies the number of configs returned.
DESCRIPTION
A GLXFBConfig describes the format, type and size of the color buffers
and ancillary buffers for a GLXDrawable. When the GLXDrawable is a win‐
dow then the GLXFBConfig that describes it has an associated X Visual;
for GLXPixmaps and GLXPbuffers there may or may not be an X Visual
associated with the GLXFBConfig.
Use glXChooseFBConfig to get GLXFBConfigs that match a list of
attributes or to get the list of GLXFBConfigs that are available on the
specified screen.
If attribList is NULL then glXChooseFBConfig returns an array of GLXF‐
BConfigs that are available on the specified screen; otherwise this
call returns an array of GLXFBConfigs that match the specified
attributes. See glXGetFBConfigAttrib for a list of attributes. The num‐
ber of elements in the array is returned in nelements. The attributes
are matched in an attribute-specific manner, as shown in Table 1 below.
Some of the attributes, such as GLX_LEVEL, must match the specified
value exactly; others, such as, GLX_RED_SIZE must meet or exceed the
specified minimum values. To retrieve the GLXFBConfig, given an i.d.,
use the GLX_FBCONFIG_ID attribute. When GLX_FBCONFIG_ID is specified,
all other attributes are ignored, and only the GLXFBConfig with the
given XID is returned (NULL is returned if it does not exist).
If no conforming GLXFBConfig exists, or if an error occurs then NULL is
returned. If attribList is not NULL and more than one GLXFBConfig is
found, then a list of GLXFBConfigs, sorted according to the "best"
match criteria, is returned. The exact sorting precedence order is
described later. Use XFree to free the memory returned by glXChooseFB‐
Config.
If GLX_RENDER_TYPE is in attribList then the value that follows is a
mask indicating which type of GLXContexts drawables created with the
corresponding GLXFBConfigs be bound to. For example, if GLX_RGBA_BIT |
GLX_COLOR_INDEX_BIT is specified as the mask then glXChooseFBConfig
will search for GLXFBConfig that can be used to create drawables that
can be bound to both RGBA and color index rendering contexts. The
default value for GLX_RENDER_TYPE is GLX_RGBA_BIT.
The attribute GLX_DRAWABLE_TYPE has as its value a mask indicating the
drawable types that can be created with the corresponding GLXFBConfig
(the config is said to ``support'' these drawable types). For example,
a GLXFBConfig for which the value of GLX_DRAWABLE_TYPE attribute is
GLX_WINDOW_BIT | GLX_PIXMAP_BIT | GLX_PBUFFER_BIT can be used to create
any type of GLX drawable, while a config for which this attribute value
is GLX_WINDOW_BIT can not be used for creating GLX pixmaps. The default
value for GLX_DRAWABLE_TYPE is GLX_WINDOW_BIT.
If a GLXFBConfig supports Windows then it has an associated X Visual.
The value of the GLX_X_VISUAL_TYPE attribute specifies the type of X
Visual. The possible values are:
┌─────────────────────────────────┐
│ GLX Token Name X Visual Type │
├─────────────────────────────────┤
│GLX_TRUE_COLOR TrueColor │
│GLX_DIRECT_COLOR DirectColor │
│GLX_PSEUDO_COLOR PseudoColor │
│GLX_STATIC_COLOR StaticColor │
│GLX_GRAY_SCALE GrayScale │
│GLX_STATIC_GRAY StaticGray │
└─────────────────────────────────┘
Note that RGBA rendering may be supported for any of the six Visual
types but color index rendering is only supported for PseudoColor,
StaticColor, GrayScale, and StaticGray visuals (i.e., single-channel
visuals). The GLX_X_VISUAL_TYPE attribute is ignored if GLX_DRAW‐
ABLE_TYPE is specified in attribList and the mask that follows does not
have GLX_WINDOW_BIT set.
GLX_X_RENDERABLE is a boolean indicating whether X can be used to ren‐
der into a drawable created with the GLXFBConfig. This attribute is
True if the GLXFBConfig supports Windows and/or GLX pixmaps.
All attributes in attribList, including boolean attributes, are immedi‐
ately followed by the corresponding desired value. The list is termi‐
nated with None. If an attribute is not specified in attribList then
the default value (listed in Table 1) is used (it is said to be speci‐
fied implicitly). For example, if GLX_STEREO is not specified then it
is assumed to be False. For some attributes, the default is "don't
care" meaning that any value is OK for this attribute, so the attribute
will not be checked.
┌────────────────────────────────────────────────────────────┐
│ Attribute default sorting criteria │
├────────────────────────────────────────────────────────────┤
│GLX_FBCONFIG_ID don't care exact │
│GLX_BUFFER_SIZE 0 smaller │
│GLX_LEVEL 0 exact │
│GLX_DOUBLEBUFFER don't care smaller │
│GLX_STEREO False exact │
│GLX_AUX_BUFFERS 0 smaller │
│GLX_RED_SIZE 0 larger │
│GLX_GREEN_SIZE 0 larger │
│GLX_BLUE_SIZE 0 larger │
│GLX_ALPHA_SIZE 0 larger │
│GLX_DEPTH_SIZE 0 larger │
│GLX_STENCIL_SIZE 0 larger │
│GLX_ACCUM_RED_SIZE 0 larger │
│GLX_ACCUM_GREEN_SIZE 0 larger │
│GLX_ACCUM_BLUE_SIZE 0 larger │
│GLX_ACCUM_ALPHA_SIZE 0 larger │
│GLX_RENDER_TYPE don't care mask │
│GLX_DRAWABLE_TYPE don't care exact │
│GLX_X_RENDERABLE don't care exact │
│GLX_X_VISUAL_TYPE don't care exact │
│GLX_CONFIG_CAVEAT don't care exact │
│GLX_TRANSPARENT_TYPE don't care exact │
│GLX_TRANSPARENT_INDEX_VALUE don't care exact │
│GLX_TRANSPARENT_RED_VALUE don't care exact │
│GLX_TRANSPARENT_GREEN_VALUE don't care exact │
│GLX_TRANSPARENT_BLUE_VALUE don't care exact │
│GLX_TRANSPARENT_ALPHA_VALUE don't care exact │
│GLX_SAMPLE_BUFFERS 0 smaller │
│GLX_SAMPLES 0 smaller │
│GLX_VIDEO_RESIZE_SUN 0 larger │
│GLX_VIDEO_REFRESH_TIME_SUN 0 smaller │
│GLX_GAMMA_VALUE_SUN 0 larger │
└────────────────────────────────────────────────────────────┘
When more than one GLXFBConfig matches the specification, a list of
matching configurations is returned. The list is sorted according to
the following precedence rules that are applied in ascending order
(i.e., configurations that are considered equal by lower numbered rule
are sorted by the higher numbered rule):
1. by GLX_CONFIG_CAVEAT where the precedence is GLX_NONE,
GLX_SLOW_CONFIG, GLX_NON_CONFORMANT_CONFIG.
2. larger total number of RGBA color bits
(GLX_RED_SIZE,GLX_GREEN_SIZE, GLX_BLUE_SIZE, plus
GLX_ALPHA_SIZE). If the requested number of bits in attribList
for a particular color component is 0 or GLX_DONT_CARE, then the
number of bits for that components is not considered.
3. smaller GLX_BUFFER_SIZE,
4. single buffered configuration (GLX_DOUBLEBUFFER being False)
precedes a double buffered one,
5. smaller GLX_AUX_BUFFERS,
6. smaller GLX_SAMPLE_BUFFERS,
7. smaller GLX_SAMPLES,
8. larger GLX_DEPTH_BITS,
9. smaller GLX_STENCIL_BITS,
10. larger total number of accumulation buffer color components
(GLX_ACCUM_RED_SIZE, GLX_ACCUM_GREEN_SIZE, GLX_ACCUM_BLUE_SIZE,
plus GLX_ACCUM_ALPHA_SIZE). If the requested number of bits in
arribList for a particular color components is zero or
GLX_DONT_CARE, then the number of bits for that components is
not considered.
11. sort by GLX_VISUAL_TYPE where the precedence order is
GLX_TRUE_COLOR, GLX_DIRECT_COLOR, GLX_PSEUDO_COLOR,
GLX_STATIC_COLOR, GLX_GRAY_SCALE, GLX_STATIC_GRAY
12. larger GLX_VIDEO_RESIZE_SUN
13. smaller GLX_VIDEO_REFRESH_TIME_SUN
14. larger GLX_GAMMA_VALUE_SUN
The definition of the sorting criteria is as follow:
smaller configs with attribute value that meets or exceeds the speci‐
fied value are returned, with precedence given to smaller val‐
ues (when a value is not explicitly requested, the default is
implied);
larger when the value is requested explicitly, only configs with a
corresponding attribute value that meet or exceed the speci‐
fied value are returned, with precedence given to larger val‐
ues. When the value is not requested explicitly behaves
exactly like the ``smaller'' criterion.
exact only configs whose corresponding attribute value exactly
matches the requested value are considered. mask - only con‐
figs for which the set bits of corresponding attribute include
all the bits that are set in the requested value are consid‐
ered (Additional bits might be set in the attribute).
NOTESglXChooseFBConfig is part of the GLX Version 1.3 command set. The func‐
tion is only valid if the connection supports GLX Version 1.3 or later.
ERRORS
NULL is returned if an undefined GLX attribute is encountered in attri‐
bList. or dpy does not support GLX version 1.3 or screen is invalid.
SEE ALSO
glXCreateNewContext, glXCreatePixmap, glXGetVisualFromFBConfig,
glXGetFBConfigFromVisual, glXGetFBConfigAttrib
18 May 01 GLXCHOOSEFBCONFIG(3gl)