<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "DTD/docbook/docbookx.dtd">
<!--
License Applicability. Except to the extent portions of this file are
made subject to an alternative license as permitted in the SGI Free
Software License B, Version 1.1 (the "License"), the contents of this
file are subject only to the provisions of the License. You may not use
this file except in compliance with the License. You may obtain a copy
of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
http://oss.sgi.com/projects/FreeB
Note that, as provided in the License, the Software is distributed on an
"AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
Original Code. The Original Code is: OpenGL ES Reference Manual,
Version 1.0, released September 2003, developed by Silicon Graphics,
Inc. The Original Code is Copyright (c) 2003 Silicon Graphics, Inc.
Copyright in any portions created by third parties is as indicated
elsewhere herein. All Rights Reserved.
-->
<refentry id="eglChooseConfig">
<refmeta>
<refentrytitle>eglChooseConfig</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>eglChooseConfig</refname>
<refpurpose>
return a list of EGL frame buffer configurations that match specified attributes
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>EGLBoolean <function>eglChooseConfig</function></funcdef>
<paramdef>EGLDisplay <parameter>display</parameter></paramdef>
<paramdef>EGLint const * <parameter>attrib_list</parameter></paramdef>
<paramdef>EGLConfig * <parameter>configs</parameter></paramdef>
<paramdef>EGLint <parameter>config_size</parameter></paramdef>
<paramdef>EGLint * <parameter>num_config</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>display</parameter></term>
<listitem><para>Specifies the EGL display connection.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>attrib_list</parameter></term>
<listitem><para>Specifies attributes required to match by configs.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>configs</parameter></term>
<listitem><para>Returns an array of frame buffer configurations.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>config_size</parameter></term>
<listitem><para>Specifies the size of the array of frame buffer configurations.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>num_config</parameter></term>
<listitem><para>Returns the number of frame buffer configurations returned.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<function>eglChooseConfig</function> returns a list of all
<acronym>EGL</acronym> frame buffer configurations that match the
attributes specified in <parameter>attrib_list</parameter>.
The items in the list can be used in any
<acronym>EGL</acronym>
function that requires an
<acronym>EGL</acronym>
frame buffer configuration.
</para>
<para>
<parameter>configs</parameter>
does not return values, if it is specified as
<constant>NULL</constant>.
This is useful for querying just the number of matching frame buffer
configurations.
</para>
<para>
All attributes in <parameter>attrib_list</parameter>,
including boolean attributes, are
immediately followed by the corresponding desired value. The list is
terminated with <constant>EGL_NONE</constant>.
If an attribute is not specified in <parameter>attrib_list</parameter>
then the default value (see below) is used (and the attribute is said to be
specified implicitly). For example, if <constant>EGL_DEPTH_SIZE</constant>
is not specified then
it is assumed to be 0. For some attributes, the default is
<constant>EGL_DONT_CARE</constant> meaning that any value is OK for this
attribute, so the attribute will not be checked.
</para>
<para>
Attributes are matched in an attribute-specific manner. Some of the
attributes, such as <constant>EGL_LEVEL</constant>, must match the
specified value exactly.
Others, such as, <constant>EGL_RED_SIZE</constant> 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.
</para>
<para>
The interpretations of the various EGL frame buffer configuration
attributes are as follows:
</para>
<variablelist>
<varlistentry>
<term><constant>EGL_BUFFER_SIZE</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_RED_SIZE</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_GREEN_SIZE</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_BLUE_SIZE</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_ALPHA_SIZE</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_CONFIG_CAVEAT</constant></term>
<listitem><para>
Must be followed by one of
<constant>EGL_DONT_CARE</constant>,
<constant>EGL_NONE</constant>,
<constant>EGL_SLOW_CONFIG</constant>,
<constant>EGL_NON_CONFORMANT_CONFIG</constant>. If
<constant>EGL_NONE</constant> is specified, then only frame buffer
configurations with no caveats will be
considered. If <constant>EGL_SLOW_CONFIG</constant> is specified,
then only slow frame buffer configurations will
be considered. If <constant>EGL_NON_CONFORMANT_CONFIG</constant> is
specified, then only non-conformant frame buffer
configurations will be considered. The default
value is <constant>EGL_DONT_CARE</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_CONFIG_ID</constant></term>
<listitem><para>
Must be followed by a valid ID that indicates
the desired EGL frame buffer configuration. When
a <constant>EGL_CONFIG_ID</constant> is specified,
all attributes
are ignored. The default value is <constant>EGL_DONT_CARE</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_DEPTH_SIZE</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_LEVEL</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_NATIVE_RENDERABLE</constant></term>
<listitem><para>
Must be followed by
<constant>EGL_DONT_CARE</constant>,
<constant>EGL_TRUE</constant>, or
<constant>EGL_FALSE</constant>.
If <constant>EGL_TRUE</constant> is
specified, then only frame buffer configurations
that allow native rendering into the surface will be
considered. The default value is <constant>EGL_DONT_CARE</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_NATIVE_VISUAL_TYPE</constant></term>
<listitem><para>
Must be followed by a platform dependent value or
<constant>EGL_DONT_CARE</constant>.
The default value is <constant>EGL_DONT_CARE</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SAMPLE_BUFFERS</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SAMPLES</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_STENCIL_SIZE</constant></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SURFACE_TYPE</constant></term>
<listitem><para>
Must be followed by a mask indicating which EGL
surface types the frame buffer configuration
must support. Valid bits are
<constant>EGL_WINDOW_BIT</constant>,
<constant>EGL_PBUFFER_BIT</constant>, and
<constant>EGL_PIXMAP_BIT</constant>.
For example, if mask is set to
<inlineequation><math><mi>EGL_WINDOW_BIT</mi><mo>|</mo><mi>EGL_PIXMAP_BIT</mi></math></inlineequation>,
only frame buffer
configurations that support both windows and
pixmaps will be considered. The default value
is <constant>EGL_WINDOW_BIT</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_TRANSPARENT_TYPE</constant></term>
<listitem><para>
Must be followed by one of
<constant>EGL_NONE</constant> or
<constant>EGL_TRANSPARENT_RGB</constant>.
If <constant>EGL_NONE</constant> is
specified, then only opaque frame buffer
configurations will be considered. If
<constant>EGL_TRANSPARENT_RGB</constant> is specified, then only
transparent frame buffer configurations
will be considered.
The default value is <constant>EGL_NONE</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_TRANSPARENT_RED_VALUE</constant></term>
<listitem><para>
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 <constant>EGL_DONT_CARE</constant>.
</para>
<para>
This attribute is ignored unless
<constant>EGL_TRANSPARENT_TYPE</constant> is included in
<parameter>attrib_list</parameter> and specified as
<constant>EGL_TRANSPARENT_RGB</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_TRANSPARENT_GREEN_VALUE</constant></term>
<listitem><para>
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 <constant>EGL_DONT_CARE</constant>.
</para>
<para>
This attribute is ignored unless
<constant>EGL_TRANSPARENT_TYPE</constant> is included in
<parameter>attrib_list</parameter> and specified as
<constant>EGL_TRANSPARENT_RGB</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_TRANSPARENT_BLUE_VALUE</constant></term>
<listitem><para>
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 <constant>EGL_DONT_CARE</constant>.
</para>
<para>
This attribute is ignored unless
<constant>EGL_TRANSPARENT_TYPE</constant> is included in
<parameter>attrib_list</parameter> and specified as
<constant>EGL_TRANSPARENT_RGB</constant>.
</para></listitem>
</varlistentry>
</variablelist>
<!--
<informaltable>
<tgroup cols="4">
<colspec align="left"/>
<colspec align="center"/>
<colspec align="center"/>
<colspec align="center"/>
<thead>
<row>
<entry>Attribute</entry>
<entry>Default</entry>
<entry>Selection and<br /> Sorting Criteria</entry>
<entry>Sort Priority</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>EGL_BUFFER_SIZE</constant></entry>
<entry>0</entry>
<entry>Smaller</entry>
<entry>3</entry>
</row>
<row>
<entry><constant>EGL_RED_SIZE</constant></entry>
<entry>0</entry>
<entry>Larger</entry>
<entry>2</entry>
</row>
<row>
<entry><constant>EGL_GREEN_SIZE</constant></entry>
<entry>0</entry>
<entry>Larger</entry>
<entry>2</entry>
</row>
<row>
<entry><constant>EGL_BLUE_SIZE</constant></entry>
<entry>0</entry>
<entry>Larger</entry>
<entry>2</entry>
</row>
<row>
<entry><constant>EGL_ALPHA_SIZE</constant></entry>
<entry>0</entry>
<entry>Larger</entry>
<entry>2</entry>
</row>
<row>
<entry><constant>EGL_CONFIG_CAVEAT</constant></entry>
<entry><constant>EGL_DONT_CARE</constant></entry>
<entry>Exact</entry>
<entry>1</entry>
</row>
<row>
<entry><constant>EGL_CONFIG_ID</constant></entry>
<entry><constant>EGL_DONT_CARE</constant></entry>
<entry>Exact</entry>
<entry>9 (last)</entry>
</row>
<row>
<entry><constant>EGL_DEPTH_SIZE</constant></entry>
<entry>0</entry>
<entry>Smaller</entry>
<entry>6</entry>
</row>
<row>
<entry><constant>EGL_LEVEL</constant></entry>
<entry>0</entry>
<entry>Exact</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>EGL_NATIVE_RENDERABLE</constant></entry>
<entry><constant>EGL_DONT_CARE</constant></entry>
<entry>Exact</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>EGL_NATIVE_VISUAL_TYPE</constant></entry>
<entry><constant>EGL_DONT_CARE</constant></entry>
<entry>Exact</entry>
<entry>8</entry>
</row>
<row>
<entry><constant>EGL_SAMPLE_BUFFERS</constant></entry>
<entry>0</entry>
<entry>Smaller</entry>
<entry>4</entry>
</row>
<row>
<entry><constant>EGL_SAMPLES</constant></entry>
<entry>0</entry>
<entry>Smaller</entry>
<entry>5</entry>
</row>
<row>
<entry><constant>EGL_STENCIL_SIZE</constant></entry>
<entry>0</entry>
<entry>Smaller</entry>
<entry>7</entry>
</row>
<row>
<entry><constant>EGL_SURFACE_TYPE</constant></entry>
<entry><constant>EGL_WINDOW_BIT</constant></entry>
<entry>Mask</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>EGL_TRANSPARENT_TYPE</constant></entry>
<entry><constant>EGL_NONE</constant></entry>
<entry>Exact</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>EGL_TRANSPARENT_RED_VALUE</constant></entry>
<entry><constant>EGL_DONT_CARE</constant></entry>
<entry>Exact</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>EGL_TRANSPARENT_GREEN_VALUE</constant></entry>
<entry><constant>EGL_DONT_CARE</constant></entry>
<entry>Exact</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>EGL_TRANSPARENT_BLUE_VALUE</constant></entry>
<entry><constant>EGL_DONT_CARE</constant></entry>
<entry>Exact</entry>
<entry>-</entry>
</row>
</tbody>
</tgroup>
</informaltable>
-->
<para>
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):
</para>
<orderedlist>
<listitem><para>
By <constant>EGL_CONFIG_CAVEAT</constant>, where the precedence is
<constant>EGL_NONE</constant>,
<constant>EGL_SLOW_CONFIG</constant>, and
<constant>EGL_NON_CONFORMANT_CONFIG</constant>.
</para></listitem>
<listitem><para>
Larger total number of color components
(<constant>EGL_RED_SIZE</constant>,
<constant>EGL_GREEN_SIZE</constant>,
<constant>EGL_BLUE_SIZE</constant>, and
<constant>EGL_ALPHA_SIZE</constant>) that have higher number
of bits. If the requested number of bits in
<parameter>attrib_list</parameter> is
zero or <constant>EGL_DONT_CARE</constant> for a particular
color component, then the number of bits for that component is not
considered.
</para></listitem>
<listitem><para>
Smaller <constant>EGL_BUFFER_SIZE</constant>.
</para></listitem>
<listitem><para>
Smaller <constant>EGL_SAMPLE_BUFFERS</constant>.
</para></listitem>
<listitem><para>
Smaller <constant>EGL_SAMPLES</constant>.
</para></listitem>
<listitem><para>
Smaller <constant>EGL_DEPTH_SIZE</constant>.
</para></listitem>
<listitem><para>
Smaller <constant>EGL_STENCIL_SIZE</constant>.
</para></listitem>
<listitem><para>
By <constant>EGL_NATIVE_VISUAL_TYPE</constant>, where the precedence
order is platform dependent.
</para></listitem>
<listitem><para>
Smaller <constant>EGL_CONFIG_ID</constant>.
</para></listitem>
</orderedlist>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
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.
</para>
<programlisting>EGLint const attrib_list[] = {
EGL_RED_SIZE, 4,
EGL_GREEN_SIZE, 4,
EGL_BLUE_SIZE, 4,
EGL_NONE
};</programlisting>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>
and
<citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry>
can be used to implement
selection algorithms other than the generic one implemented by
<function>eglChooseConfig</function>. Call
<citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry> to retrieve all the frame
buffer configurations, or alternatively, all the
frame buffer configurations with a particular set of attributes. Next
call <citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry>
to retrieve additional attributes for the frame
buffer configurations and then select between them.
</para>
<para>
EGL implementors are strongly discouraged, but not proscribed, from
changing the selection algorithm used by
<function>eglChooseConfig</function>. Therefore,
selections may change from release to release of the client-side library.
</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>
<constant>EGL_FALSE</constant>
is returned on failure,
<constant>EGL_TRUE</constant>
otherwise.
<parameter>configs</parameter>
and <parameter>num_config</parameter>
are not modified when
<constant>EGL_FALSE</constant>
is returned.
</para>
<para>
<constant>EGL_BAD_DISPLAY</constant> is generated if
<parameter>display</parameter> is not an EGL display connection.
</para>
<para>
<constant>EGL_BAD_ATTRIBUTE</constant> is generated if
<parameter>attribute_list</parameter> contains an invalid frame buffer
configuration attribute or an
attribute value that is unrecognized or out of range.
</para>
<para>
<constant>EGL_NOT_INITIALIZED</constant> is generated if
<parameter>display</parameter> has not been initialized.
</para>
<para>
<constant>EGL_BAD_PARAMETER</constant> is generated if
<parameter>num_config</parameter> is <constant>NULL</constant>.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>eglCreateContext</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry>
</para>
</refsect1>
</refentry>
![[BACK]](/icons/back.gif){kind=icon}
Return to eglChooseConfig.xml CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [Development] / projects / ogl-sample / main / doc / gles / xml