eglChooseConfig
- return a list of EGL frame buffer configurations that match specified attributes
EGLBoolean eglChooseConfig(EGLDisplay display, EGLint const * attrib_list, EGLConfig * configs, EGLint config_size, EGLint * num_config)
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.
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):
Special EGL_CONFIG_CAVEAT
, where the precedence is EGL_NONE
, EGL_SLOW_CONFIG
, and EGL_NON_CONFORMANT_CONFIG
.
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.
Smaller EGL_BUFFER_SIZE
.
Smaller EGL_SAMPLE_BUFFERS
.
Smaller EGL_SAMPLES
.
Smaller EGL_DEPTH_SIZE
.
Smaller EGL_STENCIL_SIZE
.
Special EGL_NATIVE_VISUAL_TYPE
(the actual sort order is implementation-defined, depending on the meaning of native visual types).
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
.
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 };
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.
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
.
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/.
eglCreateContext
, eglCreatePbufferSurface
, eglCreatePixmapSurface
, eglCreateWindowSurface
, eglGetConfigs
, eglGetConfigAttrib