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 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 OpenVG.
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 platforms do not support buffer levels other than zero. The behavior of windows placed in overlay and underlay planes depends on the underlying platform.
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):
Special: by EGL_CONFIG_CAVEAT
,
where the precedence is EGL_NONE
,
EGL_SLOW_CONFIG
, and
EGL_NON_CONFORMANT_CONFIG
.
Special: by EGL_COLOR_BUFFER_TYPE
,
where the precedence is
EGL_RGB_BUFFER
,
EGL_LUMINANCE_BUFFER
.
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.
Smaller EGL_BUFFER_SIZE
.
Smaller EGL_SAMPLE_BUFFERS
.
Smaller EGL_SAMPLES
.
Smaller EGL_DEPTH_SIZE
.
Smaller EGL_STENCIL_SIZE
.
Smaller EGL_ALPHA_MASK_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
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
.
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 };
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.
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
.
eglCreateContext, eglCreatePbufferSurface, eglCreatePixmapSurface, eglCreateWindowSurface, eglGetConfigs, eglGetConfigAttrib, eglSurfaceAttrib, eglSwapInterval
Copyright © 2003-2014 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.