2003-2014 The Khronos Group Inc.
eglChooseConfig 3G
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 in configs a list of all EGL frame buffer configurations that match the attributes specified in attrib_list. The returned EGLConfigs can be used in any EGL function that requires an EGL frame buffer configuration.

If configs is not `NULL`, up to config_size configs will be returned in the array pointed to by configs. The number of configs actually returned will be returned in *num_config.

If configs is `NULL`, no configs will be returned in configs. Instead, the total number of configs matching attrib_list will be returned in *num_config. In this case config_size is ignored. This form of `eglChooseConfig` is used to determine the number of matching frame buffer configurations, followed by allocating an array of EGLConfig to pass into another call to `eglChooseConfig` with all other parameters unchanged.

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 zero. 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 matching all attributes 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.

For the bitmask attributes `EGL_CONFORMANT`, `EGL_RENDERABLE_TYPE`, and `EGL_SURFACE_TYPE`, only the nonzero bits of the mask are considered when matching. Any bits that are zero in the specified bitmask attribute value may be either zero or one in the resulting config's attribute value.

Attributes which may appear in attrib_list, and their descriptions and allowed values, are:

`EGL_ALPHA_MASK_SIZE`

  Must be followed by a nonnegative integer that indicates the desired alpha mask buffer size, in bits. The smallest alpha mask buffers of at least the specified size are preferred. The default value is zero.

  The alpha mask buffer is used only by OpenGL and OpenGL ES client APIs.

`EGL_ALPHA_SIZE`

  Must be followed by a nonnegative integer that indicates the desired size of the alpha component of the color buffer, in bits. If this value is zero, color buffers with the smallest alpha component size are preferred. Otherwise, color buffers with the largest alpha component of at least the specified size are preferred. The default value is zero.

`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 OpenGL ES 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 one of `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 OpenGL ES RGBA texture will be considered. Currently only frame buffer configurations that support pbuffers allow this. The default value is `EGL_DONT_CARE`.

`EGL_BLUE_SIZE`

  Must be followed by a nonnegative integer that indicates the desired size of the blue component of the color buffer, in bits. If this value is zero, color buffers with the smallest blue component size are preferred. Otherwise, color buffers with the largest blue component of at least the specified size are preferred. The default value is zero.

`EGL_BUFFER_SIZE`

  Must be followed by a nonnegative integer that indicates the desired color buffer size, in bits. The smallest color buffers of at least the specified size are preferred. The default value is zero.

  The color buffer size is the sum of `EGL_RED_SIZE`, `EGL_GREEN_SIZE`, `EGL_BLUE_SIZE`, and `EGL_ALPHA_SIZE`, and does not include any padding bits which may be present in the pixel format. It is usually preferable to specify desired sizes for these color components individually.

`EGL_COLOR_BUFFER_TYPE`

  Must be followed by one of `EGL_RGB_BUFFER` or `EGL_LUMINANCE_BUFFER`.

  `EGL_RGB_BUFFER` indicates an RGB color buffer; in this case, attributes `EGL_RED_SIZE`, `EGL_GREEN_SIZE` and `EGL_BLUE_SIZE` must be non-zero, and `EGL_LUMINANCE_SIZE` must be zero.

  `EGL_LUMINANCE_BUFFER` indicates a luminance color buffer. In this case `EGL_RED_SIZE`, `EGL_GREEN_SIZE`, `EGL_BLUE_SIZE` must be zero, and `EGL_LUMINANCE_SIZE` must be non-zero.

  For both RGB and luminance color buffers, `EGL_ALPHA_SIZE` may be zero or non-zero.

`EGL_CONFIG_CAVEAT`

  Must be followed by `EGL_DONT_CARE`, `EGL_NONE`, `EGL_SLOW_CONFIG`, or `EGL_NON_CONFORMANT_CONFIG`.

  If `EGL_DONT_CARE` is specified, then configs are not matched for this attribute. The default value is `EGL_DONT_CARE`.

  If `EGL_NONE` is specified, then configs are matched for this attribute, but only configs with no caveats (neither `EGL_SLOW_CONFIG` or `EGL_NON_CONFORMANT_CONFIG`) will be considered.

  If `EGL_SLOW_CONFIG` is specified, then only slow configs configurations will be considered. The meaning of``slow'' is implementation-dependent, but typically indicates a non-hardware-accelerated (software) implementation.

  If `EGL_NON_CONFORMANT_CONFIG` is specified, then only configs supporting non-conformant OpenGL ES contexts will be considered.

  If the EGL version is 1.3 or later, caveat `EGL_NON_CONFORMANT_CONFIG` is obsolete, since the same information can be specified via the `EGL_CONFORMANT` attribute on a per-client-API basis, not just for OpenGL ES.

`EGL_CONFIG_ID`

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

  The meaning of config IDs is implementation-dependent. They are used only to uniquely identify different frame buffer configurations.

`EGL_CONFORMANT`

  Must be followed by a bitmask indicating which types of client API contexts created with respect to the frame buffer configuration config must pass the required conformance tests for that API. Mask bits include:

  `EGL_OPENGL_BIT`

    Config supports creating OpenGL contexts.

  `EGL_OPENGL_ES_BIT`

    Config supports creating OpenGL ES 1.0 and/or 1.1 contexts.

  `EGL_OPENGL_ES2_BIT`

    Config supports creating OpenGL ES 2.0 contexts.

  `EGL_OPENVG_BIT`

    Config supports creating OpenVG contexts.

  For example, if the bitmask is set to `EGL_OPENGL_ES_BIT`, only frame buffer configurations that support creating conformant OpenGL ES contexts will match. The default value is zero.

  Most EGLConfigs should be conformant for all supported client APIs, and it is rarely desirable to select a nonconformant config. Conformance requirements limit the number of non-conformant configs that an implementation can define.

`EGL_DEPTH_SIZE`

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

  The depth buffer is used only by OpenGL and OpenGL ES client APIs.

`EGL_GREEN_SIZE`

  Must be followed by a nonnegative integer that indicates the desired size of the green component of the color buffer, in bits. If this value is zero, color buffers with the smallest green component size are preferred. Otherwise, color buffers with the largest green component of at least the specified size are preferred. The default value is zero.

`EGL_LEVEL`

  Must be followed by an integer buffer level specification. This specification is honored exactly. Buffer level zero corresponds to the default 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. The default value is zero.

  Most imlementations do not support overlay or underlay planes (buffer levels other than zero).

`EGL_LUMINANCE_SIZE`

  Must be followed by a nonnegative integer that indicates the desired size of the luminance component of the color buffer, in bits. If this value is zero, color buffers with the smallest luminance component size are preferred. Otherwise, color buffers with the largest luminance component of at least the specified size are preferred. The default value is zero.

`EGL_MATCH_NATIVE_PIXMAP`

  Must be followed by the handle of a valid native pixmap, cast to EGLint, or `EGL_NONE`. If the value is not `EGL_NONE`, only configs which support creating pixmap surfaces with this pixmap using eglCreatePixmapSurface will match this attribute. If the value is `EGL_NONE`, then configs are not matched for this attribute. The default value is `EGL_NONE`.

  `EGL_MATCH_NATIVE_PIXMAP` was introduced due to the difficulty of determining an EGLConfig compatibile with a native pixmap using only color component sizes.

`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_RED_SIZE`

  Must be followed by a nonnegative integer that indicates the desired size of the red component of the color buffer, in bits. If this value is zero, color buffers with the smallest red component size are preferred. Otherwise, color buffers with the largest red component of at least the specified size are preferred. The default value is zero.

`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 zero.

`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 stencil buffer size, in bits. The smallest stencil buffers of at least the specified size are preferred. If the desired size is zero, frame buffer configurations with no stencil buffer are preferred. The default value is zero.

  The stencil buffer is used only by OpenGL and OpenGL ES client APIs.

`EGL_RENDERABLE_TYPE`

  Must be followed by a bitmask indicating which types of client API contexts the frame buffer configuration must support creating with eglCreateContext). Mask bits are the same as for attribute `EGL_CONFORMANT`. The default value is `EGL_OPENGL_ES_BIT`.

`EGL_SURFACE_TYPE`

  Must be followed by a bitmask indicating which EGL surface types and capabilities the frame buffer configuration must support. Mask bits include:

  `EGL_MULTISAMPLE_RESOLVE_BOX_BIT`

    Config allows specifying box filtered multisample resolve behavior with eglSurfaceAttrib.

  `EGL_PBUFFER_BIT`

    Config supports creating pixel buffer surfaces.

  `EGL_PIXMAP_BIT`

    Config supports creating pixmap surfaces.

  `EGL_SWAP_BEHAVIOR_PRESERVED_BIT`

    Config allows setting swap behavior for color buffers with eglSurfaceAttrib.

  `EGL_VG_ALPHA_FORMAT_PRE_BIT`

    Config allows specifying OpenVG rendering with premultiplied alpha values at surface creation time (see eglCreatePbufferSurface, eglCreatePixmapSurface, and eglCreateWindowSurface).

  `EGL_VG_COLORSPACE_LINEAR_BIT`

    Config allows specifying OpenVG rendering in a linear colorspace at surface creation time (see eglCreatePbufferSurface, eglCreatePixmapSurface, and eglCreateWindowSurface).

  `EGL_WINDOW_BIT`

    Config supports creating window surfaces.

  For example, if the bitmask 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`.

  Most implementations support only opaque frame buffer configurations.

`EGL_TRANSPARENT_RED_VALUE`

  Must be followed by an integer value indicating the transparent red value. The value must be between zero 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 zero and the maximum color buffer value for green. 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 zero and the maximum color buffer value for blue. 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: by `EGL_CONFIG_CAVEAT`, where the precedence is `EGL_NONE`, `EGL_SLOW_CONFIG`, and `EGL_NON_CONFORMANT_CONFIG`.

2. Special: by `EGL_COLOR_BUFFER_TYPE`, where the precedence is `EGL_RGB_BUFFER`, `EGL_LUMINANCE_BUFFER`.

3. Special: by larger total number of color bits (for an RGB color buffer, this is the sum of `EGL_RED_SIZE`, `EGL_GREEN_SIZE`, `EGL_BLUE_SIZE`, and `EGL_ALPHA_SIZE`; for a luminance color buffer, the sum of `EGL_LUMINANCE_SIZE` and `EGL_ALPHA_SIZE`). 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.

   This sort rule places configs with deeper color buffers before configs with shallower color buffers, which may be counterintuitive.

4. Smaller `EGL_BUFFER_SIZE`.

5. Smaller `EGL_SAMPLE_BUFFERS`.

6. Smaller `EGL_SAMPLES`.

7. Smaller `EGL_DEPTH_SIZE`.

8. Smaller `EGL_STENCIL_SIZE`.

9. Smaller `EGL_ALPHA_MASK_SIZE`.

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

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

EGLConfigs are not sorted with respect to the attributes `EGL_BIND_TO_TEXTURE_RGB`, `EGL_BIND_TO_TEXTURE_RGBA`, `EGL_CONFORMANT`, `EGL_LEVEL`, `EGL_NATIVE_RENDERABLE`, `EGL_MAX_SWAP_INTERVAL`, `EGL_MIN_SWAP_INTERVAL`, `EGL_RENDERABLE_TYPE`, `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 a color buffer with at least 4 bits each of red, green and blue, and possibly 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

`EGL_RENDERABLE_TYPE` bit `EGL_OPENGL_BIT`, and `EGL_SURFACE_TYPE` bits `EGL_MULTISAMPLE_RESOLVE_BOX_BIT` and `EGL_SWAP_BEHAVIOR_PRESERVED_BIT` are supported only if the EGL version is 1.4 or greater.

`EGL_CONFORMANT`, `EGL_MATCH_NATIVE_PIXMAP`, `EGL_RENDERABLE_TYPE` bit `EGL_OPENGL_ES2_BIT`, and `EGL_SURFACE_TYPE` bits `EGL_VG_ALPHA_FORMAT_PRE_BIT` and `EGL_VG_COLORSPACE_LINEAR_BIT` are supported only if the EGL version is 1.3 or greater.

`EGL_ALPHA_MASK_SIZE`, `EGL_COLOR_BUFFER_TYPE`, `EGL_LUMINANCE_SIZE`, `EGL_RENDERABLE_TYPE`, and `EGL_RENDERABLE_TYPE` bits `EGL_OPENGL_ES_BIT` and `EGL_OPENVG_BIT` are supported only if the EGL version is 1.2 or greater.

If OpenGL or OpenGL ES rendering is supported for a luminance color buffer, it is treated as RGB rendering with the value of `GL_RED_BITS` equal to `EGL_LUMINANCE_SIZE` and the values of `GL_GREEN_BITS` and `GL_BLUE_BITS` equal to zero. The red component of fragments is written to the luminance channel of the color buffer while the green and blue components are discarded.

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, eglSurfaceAttrib, eglSwapInterval

##