NAME

glXChooseVisual - return a visual that matches specified attributes

C SPECIFICATION

XVisualInfo* ggllXXCChhoooosseeVViissuuaall( Display _*_d_p_y,
                              int _s_c_r_e_e_n,
                              int _*_a_t_t_r_i_b_L_i_s_t )

delim $$

PARAMETERS

_d_p_y
Specifies the connection to the X server.
_s_c_r_e_e_n
Specifies the screen number.
_a_t_t_r_i_b_L_i_s_t
Specifies a list of boolean attributes and integer attribute/value pairs. The last attribute must be NNoonnee.

DESCRIPTION

ggllXXCChhoooosseeVViissuuaall 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, NNUULLLL is returned. To free the data returned by this function, use XXFFrreeee.

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

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

GGLLXX__UUSSEE__GGLL
Ignored. Only visuals that can be rendered with GLX are considered.
GGLLXX__BBUUFFFFEERR__SSIIZZEE
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 GGLLXX__RRGGBBAA is asserted.
GGLLXX__LLEEVVEELL
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.
GGLLXX__RRGGBBAA
If present, only TrueColor and DirectColor visuals are considered. Otherwise, only PseudoColor and StaticColor visuals are considered.
GGLLXX__DDOOUUBBLLEEBBUUFFFFEERR
If present, only double-buffered visuals are considered. Otherwise, only single-buffered visuals are considered.
GGLLXX__SSTTEERREEOO
If present, only stereo visuals are considered. Otherwise, only monoscopic visuals are considered.
GGLLXX__AAUUXX__BBUUFFFFEERRSS
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.
GGLLXX__RREEDD__SSIIZZEE
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.
GGLLXX__GGRREEEENN__SSIIZZEE
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.
GGLLXX__BBLLUUEE__SSIIZZEE
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.
GGLLXX__AALLPPHHAA__SSIIZZEE
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.
GGLLXX__DDEEPPTTHH__SSIIZZEE
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.
GGLLXX__SSTTEENNCCIILL__SSIIZZEE
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.
GGLLXX__AACCCCUUMM__RREEDD__SSIIZZEE
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.
GGLLXX__AACCCCUUMM__GGRREEEENN__SSIIZZEE
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.
GGLLXX__AACCCCUUMM__BBLLUUEE__SSIIZZEE
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.
GGLLXX__AACCCCUUMM__AALLPPHHAA__SSIIZZEE
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

_a_t_t_r_i_b_L_i_s_t =
{GGLLXX__RRGGBBAA, GGLLXX__RREEDD__SSIIZZEE, 4, GGLLXX__GGRREEEENN__SSIIZZEE, 4, GGLLXX__BBLLUUEE__SSIIZZEE, 4, NNoonnee};

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

XXVViissuuaallIInnffoo is defined in _X_u_t_i_l_._h_. It is a structure that includes _v_i_s_u_a_l, _v_i_s_u_a_l_I_D, _s_c_r_e_e_n, and _d_e_p_t_h elements.

ggllXXCChhoooosseeVViissuuaall is implemented as a client-side utility using only XXGGeettVViissuuaallIInnffoo and ggllXXGGeettCCoonnffiigg. Calls to these two routines can be used to implement selection algorithms other than the generic one implemented by ggllXXCChhoooosseeVViissuuaall.

GLX implementers are strongly discouraged, but not proscribed, from changing the selection algorithm used by ggllXXCChhoooosseeVViissuuaall. 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 GGLLXX__BBUUFFFFEERR__SSIIZZEE is one of the pixmap depths supported by the X server.

ERRORS

NNUULLLL is returned if an undefined GLX attribute is encountered in _a_t_t_r_i_b_L_i_s_t.

SEE ALSO

ggllXXCCrreeaatteeCCoonntteexxtt, ggllXXGGeettCCoonnffiigg