Name

eglChooseConfig — return a list of EGL frame buffer configurations that match specified attributes

C Specification

EGLBoolean eglChooseConfig(EGLDisplay display,
 EGLint const * attrib_list,
 EGLConfig * configs,
 EGLint config_size,
 EGLint * num_config);
 

Parameters

display

Specifies the EGL display connection.

attrib_list

Specifies attributes required to match by configs.

configs

Returns an array of frame buffer configurations.

config_size

Specifies the size of the array of frame buffer configurations.

num_config

Returns the number of frame buffer configurations returned.

Description

eglChooseConfig returns a list of all EGL frame buffer configurations that match the attributes specified in attrib_list. The items in the list can be used in any EGL function that requires an EGL frame buffer configuration.

configs does not return values, if it is specified as NULL. This is useful for querying just the number of matching frame buffer configurations.

All attributes in attrib_list, including boolean attributes, are immediately followed by the corresponding desired value. The list is terminated with EGL_NONE. If an attribute is not specified in attrib_list then the default value (see below) is used (and the attribute is said to be specified implicitly). For example, if EGL_DEPTH_SIZE is not specified then it is assumed to be 0. For some attributes, the default is EGL_DONT_CARE meaning that any value is OK for this attribute, so the attribute will not be checked.

Attributes are matched in an attribute-specific manner. Some of the attributes, such as EGL_LEVEL, must match the specified value exactly. Others, such as, EGL_RED_SIZE must meet or exceed the specified minimum values. If more than one EGL frame buffer configuration is found, then a list of configurations, sorted according to the ``best'' match criteria, is returned. The match criteria for each attribute and the exact sorting order is defined below.

The interpretations of the various EGL frame buffer configuration attributes are as follows:

EGL_BUFFER_SIZE

Must be followed by a nonnegative integer that indicates the desired color buffer size. The smallest color buffer of at least the specified size is preferred. The default value is 0.

EGL_RED_SIZE

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. The default value is 0.

EGL_GREEN_SIZE

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. The default value is 0.

EGL_BLUE_SIZE

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. The default value is 0.

EGL_ALPHA_SIZE

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. The default value is 0.

EGL_BIND_TO_TEXTURE_RGB

Must be followed by EGL_DONT_CARE, EGL_TRUE, or EGL_FALSE. If EGL_TRUE is specified, then only frame buffer configurations that support binding of color buffers to an RGB texture will be considered. Currently only frame buffer configurations that support pbuffers allow this. The default value is EGL_DONT_CARE.

EGL_BIND_TO_TEXTURE_RGBA

Must be followed by EGL_DONT_CARE, EGL_TRUE, or EGL_FALSE. If EGL_TRUE is specified, then only frame buffer configurations that support binding of color buffers to an RGBA texture will be considered. Currently only frame buffer configurations that support pbuffers allow this. The default value is EGL_DONT_CARE.

EGL_CONFIG_CAVEAT

Must be followed by one of EGL_DONT_CARE, EGL_NONE, EGL_SLOW_CONFIG, EGL_NON_CONFORMANT_CONFIG. If EGL_NONE is specified, then only frame buffer configurations with no caveats will be considered. If EGL_SLOW_CONFIG is specified, then only slow frame buffer configurations will be considered. If EGL_NON_CONFORMANT_CONFIG is specified, then only non-conformant frame buffer configurations will be considered. The default value is EGL_DONT_CARE.

EGL_CONFIG_ID

Must be followed by a valid ID that indicates the desired EGL frame buffer configuration. When a EGL_CONFIG_ID is specified, all attributes are ignored. The default value is EGL_DONT_CARE.

EGL_DEPTH_SIZE

Must be followed by a nonnegative integer that indicates the desired depth buffer size. The smallest available depth buffer of at least the minimum size is preferred. If the desired value is zero, frame buffer configurations with no depth buffer are preferred. The default value is 0.

EGL_LEVEL

Must be followed by an integer buffer-level specification. This specification is honored exactly. Buffer level 0 corresponds to the default frame buffer of the display. Buffer level 1 is the first overlay frame buffer, level two the second overlay frame buffer, and so on. Negative buffer levels correspond to underlay frame buffers. The default value is 0.

EGL_NATIVE_RENDERABLE

Must be followed by EGL_DONT_CARE, EGL_TRUE, or EGL_FALSE. If EGL_TRUE is specified, then only frame buffer configurations that allow native rendering into the surface will be considered. The default value is EGL_DONT_CARE.

EGL_MAX_SWAP_INTERVAL

Must be followed by a integer that indicates the maximum value that can be passed to eglSwapInterval. The default value is EGL_DONT_CARE.

EGL_MIN_SWAP_INTERVAL

Must be followed by a integer that indicates the minimum value that can be passed to eglSwapInterval. The default value is EGL_DONT_CARE.

EGL_SAMPLE_BUFFERS

Must be followed by the minimum acceptable number of multisample buffers. Configurations 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 only values of zero or one will produce a match. The default value is 0.

EGL_SAMPLES

Must be followed by the minimum number of samples required in multisample buffers. Configurations 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 aggregate as the main color buffers.

EGL_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, frame buffer configurations with no stencil buffer are preferred. The default value is 0.

EGL_SURFACE_TYPE

Must be followed by a mask indicating which EGL surface types the frame buffer configuration must support. Valid bits are EGL_WINDOW_BIT, EGL_PBUFFER_BIT, and EGL_PIXMAP_BIT. For example, if mask is set to EGL_WINDOW_BIT|EGL_PIXMAP_BIT, only frame buffer configurations that support both windows and pixmaps will be considered. The default value is EGL_WINDOW_BIT.

EGL_TRANSPARENT_TYPE

Must be followed by one of EGL_NONE or EGL_TRANSPARENT_RGB. If EGL_NONE is specified, then only opaque frame buffer configurations will be considered. If EGL_TRANSPARENT_RGB is specified, then only transparent frame buffer configurations will be considered. The default value is EGL_NONE.

EGL_TRANSPARENT_RED_VALUE

Must be followed by an integer value indicating the transparent red value. The value must be between 0 and the maximum color buffer value for red. Only frame buffer configurations that use the specified transparent red value will be considered. The default value is EGL_DONT_CARE.

This attribute is ignored unless EGL_TRANSPARENT_TYPE is included in attrib_list and specified as EGL_TRANSPARENT_RGB.

EGL_TRANSPARENT_GREEN_VALUE

Must be followed by an integer value indicating the transparent green value. The value must be between 0 and the maximum color buffer value for red. Only frame buffer configurations that use the specified transparent green value will be considered. The default value is EGL_DONT_CARE.

This attribute is ignored unless EGL_TRANSPARENT_TYPE is included in attrib_list and specified as EGL_TRANSPARENT_RGB.

EGL_TRANSPARENT_BLUE_VALUE

Must be followed by an integer value indicating the transparent blue value. The value must be between 0 and the maximum color buffer value for red. Only frame buffer configurations that use the specified transparent blue value will be considered. The default value is EGL_DONT_CARE.

This attribute is ignored unless EGL_TRANSPARENT_TYPE is included in attrib_list and specified as EGL_TRANSPARENT_RGB.

When more than one EGL frame buffer configuration matches the specified attributes, a list of matching configurations is returned. The list is sorted according to the following precedence rules, which are applied in ascending order (i.e., configurations that are considered equal by a lower numbered rule are sorted by the higher numbered rule):

  1. Special EGL_CONFIG_CAVEAT, where the precedence is EGL_NONE, EGL_SLOW_CONFIG, and EGL_NON_CONFORMANT_CONFIG.

  2. Special larger total number of color components (sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, and EGL_ALPHA_SIZE) that have higher number of bits. If the requested number of bits in attrib_list is 0 or EGL_DONT_CARE for a particular color component, then the number of bits for that component is not considered.

  3. Smaller EGL_BUFFER_SIZE.

  4. Smaller EGL_SAMPLE_BUFFERS.

  5. Smaller EGL_SAMPLES.

  6. Smaller EGL_DEPTH_SIZE.

  7. Smaller EGL_STENCIL_SIZE.

  8. Special EGL_NATIVE_VISUAL_TYPE (the actual sort order is implementation-defined, depending on the meaning of native visual types).

  9. Smaller EGL_CONFIG_ID (this is always the last sorting rule, and guarantees a unique ordering).

EGLConfigs are not sorted with respect to the parameters EGL_BIND_TO_TEXTURE_RGB, EGL_BIND_TO_TEXTURE_RGBA, EGL_LEVEL, EGL_NATIVE_RENDERABLE, EGL_MAX_SWAP_INTERVAL, EGL_MIN_SWAP_INTERVAL, EGL_SURFACE_TYPE, EGL_TRANSPARENT_TYPE, EGL_TRANSPARENT_RED_VALUE, EGL_TRANSPARENT_GREEN_VALUE, and EGL_TRANSPARENT_BLUE_VALUE.

Examples

The following example specifies a frame buffer configuration in the normal frame buffer (not an overlay or underlay). The returned frame buffer configuration supports at least 4 bits each of red, green and blue and possible no alpha bits. The code shown in the example may or may not have a depth buffer, or a stencil buffer. 

EGLint const attrib_list[] = {
        EGL_RED_SIZE, 4,
        EGL_GREEN_SIZE, 4,
        EGL_BLUE_SIZE, 4,
        EGL_NONE
};

Notes

eglGetConfigs and eglGetConfigAttrib can be used to implement selection algorithms other than the generic one implemented by eglChooseConfig. Call eglGetConfigs to retrieve all the frame buffer configurations, or alternatively, all the frame buffer configurations with a particular set of attributes. Next call eglGetConfigAttrib to retrieve additional attributes for the frame buffer configurations and then select between them.

EGL implementors are strongly discouraged, but not proscribed, from changing the selection algorithm used by eglChooseConfig. Therefore, selections may change from release to release of the client-side library.

Errors

EGL_FALSE is returned on failure, EGL_TRUE otherwise. configs and num_config are not modified when EGL_FALSE is returned.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_BAD_ATTRIBUTE is generated if attribute_list contains an invalid frame buffer configuration attribute or an attribute value that is unrecognized or out of range.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_PARAMETER is generated if num_config is NULL.

See Also

eglCreateContext, eglCreatePbufferSurface, eglCreatePixmapSurface, eglCreateWindowSurface, eglGetConfigs, eglGetConfigAttrib

Copyright

Copyright © 2003-2004 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.