1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" 3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"> 4<refentry xml:base="" id="eglChooseConfig"> 5 <refentryinfo> 6 <copyright> 7 <year>2003-2014</year> 8 <holder>The Khronos Group Inc.</holder> 9 </copyright> 10 </refentryinfo> 11 <refmeta> 12 <refentrytitle>eglChooseConfig</refentrytitle> 13 <manvolnum>3G</manvolnum> 14 </refmeta> 15 <refnamediv> 16 <refname>eglChooseConfig</refname> 17 <refpurpose> 18 return a list of EGL frame buffer configurations that match specified attributes 19 </refpurpose> 20 </refnamediv> 21 <refsynopsisdiv> 22 <title>C Specification</title> 23 <funcsynopsis> 24 <funcprototype> 25 <funcdef>EGLBoolean <function>eglChooseConfig</function></funcdef> 26 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 27 <paramdef>EGLint const * <parameter>attrib_list</parameter></paramdef> 28 <paramdef>EGLConfig * <parameter>configs</parameter></paramdef> 29 <paramdef>EGLint <parameter>config_size</parameter></paramdef> 30 <paramdef>EGLint * <parameter>num_config</parameter></paramdef> 31 </funcprototype> 32 </funcsynopsis> 33 </refsynopsisdiv> 34 <refsect1 id="parameters"><title>Parameters</title> 35 <variablelist> 36 <varlistentry> 37 <term><parameter>display</parameter></term> 38 <listitem><para>Specifies the EGL display connection.</para></listitem> 39 </varlistentry> 40 <varlistentry> 41 <term><parameter>attrib_list</parameter></term> 42 <listitem><para>Specifies attributes required to match by configs.</para></listitem> 43 </varlistentry> 44 <varlistentry> 45 <term><parameter>configs</parameter></term> 46 <listitem><para>Returns an array of frame buffer configurations.</para></listitem> 47 </varlistentry> 48 <varlistentry> 49 <term><parameter>config_size</parameter></term> 50 <listitem><para>Specifies the size of the array of frame buffer configurations.</para></listitem> 51 </varlistentry> 52 <varlistentry> 53 <term><parameter>num_config</parameter></term> 54 <listitem><para>Returns the number of frame buffer configurations returned.</para></listitem> 55 </varlistentry> 56 </variablelist> 57 </refsect1> 58 <refsect1 id="description"><title>Description</title> 59 <para> 60 <function>eglChooseConfig</function> returns in 61 <parameter>configs</parameter> a list of all 62 <acronym>EGL</acronym> frame buffer configurations that 63 match the attributes specified in 64 <parameter>attrib_list</parameter>. The returned 65 <type>EGLConfig</type>s can be used in any 66 <acronym>EGL</acronym> function that requires an 67 <acronym>EGL</acronym> frame buffer configuration. 68 </para> 69 <para> 70 If <parameter>configs</parameter> is not 71 <constant>NULL</constant>, up to 72 <parameter>config_size</parameter> configs will be returned 73 in the array pointed to by <parameter>configs</parameter>. 74 The number of configs actually returned will be returned in 75 *<parameter>num_config</parameter>. 76 </para> 77 <para> 78 If <parameter>configs</parameter> is 79 <constant>NULL</constant>, no configs will be returned in 80 <parameter>configs</parameter>. Instead, the total number of 81 configs matching <parameter>attrib_list</parameter> will be 82 returned in *<parameter>num_config</parameter>. In this case 83 <parameter>config_size</parameter> is ignored. This form of 84 <function>eglChooseConfig</function> is used to determine 85 the number of matching frame buffer configurations, followed 86 by allocating an array of <type>EGLConfig</type> to pass 87 into another call to <function>eglChooseConfig</function> 88 with all other parameters unchanged. 89 </para> 90 <para> 91 All attributes in <parameter>attrib_list</parameter>, 92 including boolean attributes, are immediately followed by 93 the corresponding desired value. The list is terminated with 94 <constant>EGL_NONE</constant>. If an attribute is not 95 specified in <parameter>attrib_list</parameter> then the 96 default value (see below) is used (and the attribute is said 97 to be specified implicitly). For example, if 98 <constant>EGL_DEPTH_SIZE</constant> is not specified then it 99 is assumed to be zero. For some attributes, the default is 100 <constant>EGL_DONT_CARE</constant> meaning that any value is 101 OK for this attribute, so the attribute will not be checked. 102 </para> 103 <para> 104 Attributes are matched in an attribute-specific manner. Some 105 of the attributes, such as <constant>EGL_LEVEL</constant>, 106 must match the specified value exactly. Others, such as, 107 <constant>EGL_RED_SIZE</constant> must meet or exceed the 108 specified minimum values. If more than one EGL frame buffer 109 configuration matching all attributes is found, then a list 110 of configurations, sorted according to the ``best'' match 111 criteria, is returned. The match criteria for each attribute 112 and the exact sorting order is defined below. 113 </para> 114 <para> 115 For the bitmask attributes 116 <constant>EGL_CONFORMANT</constant>, 117 <constant>EGL_RENDERABLE_TYPE</constant>, and 118 <constant>EGL_SURFACE_TYPE</constant>, only the nonzero bits 119 of the mask are considered when matching. Any bits that are 120 zero in the specified bitmask attribute value may be either 121 zero or one in the resulting config's attribute value. 122 </para> 123 <para> 124 Attributes which may appear in 125 <parameter>attrib_list</parameter>, and their descriptions 126 and allowed values, are: 127 </para> 128 <variablelist> 129 <varlistentry> 130 <term><constant>EGL_ALPHA_MASK_SIZE</constant></term> 131 <listitem><para> 132 Must be followed by a nonnegative integer that 133 indicates the desired alpha mask buffer size, in 134 bits. The smallest alpha mask buffers of at least 135 the specified size are preferred. The default value 136 is zero. 137 </para> 138 <para> 139 The alpha mask buffer is used only by OpenGL and 140 OpenGL ES client APIs. 141 </para> 142 </listitem> 143 </varlistentry> 144 <varlistentry> 145 <term><constant>EGL_ALPHA_SIZE</constant></term> 146 <listitem><para> 147 Must be followed by a nonnegative integer that 148 indicates the desired size of the alpha component of 149 the color buffer, in bits. If this value is zero, 150 color buffers with the smallest alpha component size 151 are preferred. Otherwise, color buffers with the 152 largest alpha component of at least the specified 153 size are preferred. The default value is zero. 154 </para></listitem> 155 </varlistentry> 156 <varlistentry> 157 <term><constant>EGL_BIND_TO_TEXTURE_RGB</constant></term> 158 <listitem><para> 159 Must be followed by 160 <constant>EGL_DONT_CARE</constant>, 161 <constant>EGL_TRUE</constant>, or 162 <constant>EGL_FALSE</constant>. 163 If <constant>EGL_TRUE</constant> is specified, then 164 only frame buffer configurations that support 165 binding of color buffers to an OpenGL ES RGB texture 166 will be considered. Currently only frame buffer 167 configurations that support pbuffers allow this. The 168 default value is <constant>EGL_DONT_CARE</constant>. 169 </para></listitem> 170 </varlistentry> 171 <varlistentry> 172 <term><constant>EGL_BIND_TO_TEXTURE_RGBA</constant></term> 173 <listitem><para> 174 Must be followed by one of 175 <constant>EGL_DONT_CARE</constant>, 176 <constant>EGL_TRUE</constant>, or 177 <constant>EGL_FALSE</constant>. 178 If <constant>EGL_TRUE</constant> is specified, then 179 only frame buffer configurations that support 180 binding of color buffers to an OpenGL ES RGBA 181 texture will be considered. Currently only frame 182 buffer configurations that support pbuffers allow 183 this. The default value is 184 <constant>EGL_DONT_CARE</constant>. 185 </para></listitem> 186 </varlistentry> 187 <varlistentry> 188 <term><constant>EGL_BLUE_SIZE</constant></term> 189 <listitem><para> 190 Must be followed by a nonnegative integer that 191 indicates the desired size of the blue component of 192 the color buffer, in bits. If this value is zero, 193 color buffers with the smallest blue component size 194 are preferred. Otherwise, color buffers with the 195 largest blue component of at least the specified 196 size are preferred. The default value is zero. 197 </para></listitem> 198 </varlistentry> 199 <varlistentry> 200 <term><constant>EGL_BUFFER_SIZE</constant></term> 201 <listitem><para> 202 Must be followed by a nonnegative integer that 203 indicates the desired color buffer size, in bits. 204 The smallest color buffers of at least the specified 205 size are preferred. The default value is zero. 206 </para> 207 <para> 208 The color buffer size is the sum of 209 <constant>EGL_RED_SIZE</constant>, 210 <constant>EGL_GREEN_SIZE</constant>, 211 <constant>EGL_BLUE_SIZE</constant>, and 212 <constant>EGL_ALPHA_SIZE</constant>, and does not 213 include any padding bits which may be present in the 214 pixel format. It is usually preferable to specify 215 desired sizes for these color components 216 individually. 217 </para> 218 </listitem> 219 </varlistentry> 220 <varlistentry> 221 <term><constant>EGL_COLOR_BUFFER_TYPE</constant></term> 222 <listitem> 223 <para> 224 Must be followed by one of 225 <constant>EGL_RGB_BUFFER</constant> or 226 <constant>EGL_LUMINANCE_BUFFER</constant>. 227 </para> 228 <para> 229 <constant>EGL_RGB_BUFFER</constant> indicates 230 an RGB color buffer; in this case, 231 attributes <constant>EGL_RED_SIZE</constant>, 232 <constant>EGL_GREEN_SIZE</constant> and 233 <constant>EGL_BLUE_SIZE</constant> must be non-zero, and 234 <constant>EGL_LUMINANCE_SIZE</constant> must be zero. 235 </para> 236 <para> 237 <constant>EGL_LUMINANCE_BUFFER</constant> indicates a luminance color 238 buffer. In this case <constant>EGL_RED_SIZE</constant>, 239 <constant>EGL_GREEN_SIZE</constant>, 240 <constant>EGL_BLUE_SIZE</constant> must be zero, and 241 <constant>EGL_LUMINANCE_SIZE</constant> must be non-zero. 242 </para> 243 <para> 244 For both RGB and luminance color buffers, 245 <constant>EGL_ALPHA_SIZE</constant> may be zero or 246 non-zero. 247 </para> 248 </listitem> 249 </varlistentry> 250 <varlistentry> 251 <term><constant>EGL_CONFIG_CAVEAT</constant></term> 252 <listitem> 253 <para> 254 Must be followed by 255 <constant>EGL_DONT_CARE</constant>, 256 <constant>EGL_NONE</constant>, 257 <constant>EGL_SLOW_CONFIG</constant>, or 258 <constant>EGL_NON_CONFORMANT_CONFIG</constant>. 259 </para> 260 <para> 261 If <constant>EGL_DONT_CARE</constant> is specified, 262 then configs are not matched for this attribute. The 263 default value is <constant>EGL_DONT_CARE</constant>. 264 </para> 265 <para> 266 If <constant>EGL_NONE</constant> is specified, then 267 configs are matched for this attribute, but only 268 configs with no caveats (neither 269 <constant>EGL_SLOW_CONFIG</constant> or 270 <constant>EGL_NON_CONFORMANT_CONFIG</constant>) will 271 be considered. 272 </para> 273 <para> 274 If <constant>EGL_SLOW_CONFIG</constant> is 275 specified, then only slow configs configurations 276 will be considered. The meaning of``slow'' is 277 implementation-dependent, but typically indicates a 278 non-hardware-accelerated (software) implementation. 279 </para> 280 <para> 281 If <constant>EGL_NON_CONFORMANT_CONFIG</constant> is 282 specified, then only configs supporting 283 non-conformant OpenGL ES contexts will be 284 considered. 285 </para> 286 <para> 287 If the EGL version is 1.3 or later, caveat 288 <constant>EGL_NON_CONFORMANT_CONFIG</constant> is 289 obsolete, since the same information can be 290 specified via the 291 <constant>EGL_CONFORMANT</constant> attribute on a 292 per-client-API basis, not just for OpenGL ES. 293 </para> 294 </listitem> 295 </varlistentry> 296 <varlistentry> 297 <term><constant>EGL_CONFIG_ID</constant></term> 298 <listitem> 299 <para> 300 Must be followed by a valid integer ID that 301 indicates the desired EGL frame buffer 302 configuration. When a 303 <constant>EGL_CONFIG_ID</constant> is specified, all 304 other attributes are ignored. The default value is 305 <constant>EGL_DONT_CARE</constant>. 306 </para> 307 <para> 308 The meaning of config IDs is 309 implementation-dependent. They are used only to 310 uniquely identify different frame buffer 311 configurations. 312 </para> 313 </listitem> 314 </varlistentry> 315 <varlistentry> 316 <term><constant>EGL_CONFORMANT</constant></term> 317 <listitem> 318 <para> 319 Must be followed by a bitmask indicating which types 320 of client API contexts created with respect to the 321 frame buffer configuration config must pass the 322 required conformance tests for that API. Mask bits 323 include: 324 </para> 325 <variablelist> 326 <varlistentry> 327 <term><constant>EGL_OPENGL_BIT</constant></term> 328 <listitem><para> 329 Config supports creating OpenGL contexts. 330 </para></listitem> 331 </varlistentry> 332 <varlistentry> 333 <term><constant>EGL_OPENGL_ES_BIT</constant></term> 334 <listitem><para> 335 Config supports creating OpenGL ES 1.0 336 and/or 1.1 contexts. 337 </para></listitem> 338 </varlistentry> 339 <varlistentry> 340 <term><constant>EGL_OPENGL_ES2_BIT</constant></term> 341 <listitem><para> 342 Config supports creating OpenGL ES 2.0 contexts. 343 </para></listitem> 344 </varlistentry> 345 <varlistentry> 346 <term><constant>EGL_OPENVG_BIT</constant></term> 347 <listitem><para> 348 Config supports creating OpenVG contexts. 349 </para></listitem> 350 </varlistentry> 351 </variablelist> 352 <para> 353 For example, if the bitmask is set to 354 <constant>EGL_OPENGL_ES_BIT</constant>, only frame 355 buffer configurations that support creating 356 conformant OpenGL ES contexts will match. The 357 default value is zero. 358 </para> 359 <para> 360 Most EGLConfigs should be conformant for all 361 supported client APIs, and it is rarely desirable to 362 select a nonconformant config. Conformance 363 requirements limit the number of non-conformant 364 configs that an implementation can define. 365 </para> 366 </listitem> 367 </varlistentry> 368 <varlistentry> 369 <term><constant>EGL_DEPTH_SIZE</constant></term> 370 <listitem> 371 <para> 372 Must be followed by a nonnegative integer that 373 indicates the desired depth buffer size, in bits. 374 The smallest depth buffers of at least the specified 375 size is preferred. If the desired size is zero, 376 frame buffer configurations with no depth buffer are 377 preferred. The default value is zero. 378 </para> 379 <para> 380 The depth buffer is used only by OpenGL and OpenGL 381 ES client APIs. 382 </para> 383 </listitem> 384 </varlistentry> 385 <varlistentry> 386 <term><constant>EGL_GREEN_SIZE</constant></term> 387 <listitem><para> 388 Must be followed by a nonnegative integer that 389 indicates the desired size of the green component of 390 the color buffer, in bits. If this value is zero, 391 color buffers with the smallest green component size 392 are preferred. Otherwise, color buffers with the 393 largest green component of at least the specified 394 size are preferred. The default value is zero. 395 </para></listitem> 396 </varlistentry> 397 <varlistentry> 398 <term><constant>EGL_LEVEL</constant></term> 399 <listitem><para> 400 Must be followed by an integer buffer level 401 specification. This specification is honored 402 exactly. Buffer level zero corresponds to the 403 default frame buffer of the display. Buffer level 404 one is the first overlay frame buffer, level two the 405 second overlay frame buffer, and so on. Negative 406 buffer levels correspond to underlay frame buffers. 407 The default value is zero. 408 </para> 409 <para> 410 Most imlementations do not support overlay or 411 underlay planes (buffer levels other than zero). 412 </para> 413 </listitem> 414 </varlistentry> 415 <varlistentry> 416 <term><constant>EGL_LUMINANCE_SIZE</constant></term> 417 <listitem> 418 <para> 419 Must be followed by a nonnegative integer that 420 indicates the desired size of the luminance 421 component of the color buffer, in bits. If this 422 value is zero, color buffers with the smallest 423 luminance component size are preferred. Otherwise, 424 color buffers with the largest luminance component 425 of at least the specified size are preferred. The 426 default value is zero. 427 </para> 428 </listitem> 429 </varlistentry> 430 <varlistentry> 431 <term><constant>EGL_MATCH_NATIVE_PIXMAP</constant></term> 432 <listitem> 433 <para> 434 Must be followed by the handle of a valid native 435 pixmap, cast to <type>EGLint</type>, or 436 <constant>EGL_NONE</constant>. If the value is not 437 <constant>EGL_NONE</constant>, only configs which 438 support creating pixmap surfaces with this pixmap 439 using 440 <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry> 441 will match this attribute. If the value is 442 <constant>EGL_NONE</constant>, then configs are not 443 matched for this attribute. The default value is 444 <constant>EGL_NONE</constant>. 445 </para> 446 <para> 447 <constant>EGL_MATCH_NATIVE_PIXMAP</constant> was 448 introduced due to the difficulty of determining an 449 <type>EGLConfig</type> compatibile with a native 450 pixmap using only color component sizes. 451 </para> 452 </listitem> 453 </varlistentry> 454 <varlistentry> 455 <term><constant>EGL_NATIVE_RENDERABLE</constant></term> 456 <listitem><para> 457 Must be followed by 458 <constant>EGL_DONT_CARE</constant>, 459 <constant>EGL_TRUE</constant>, or 460 <constant>EGL_FALSE</constant>. 461 If <constant>EGL_TRUE</constant> is specified, then 462 only frame buffer configurations that allow native 463 rendering into the surface will be considered. The 464 default value is <constant>EGL_DONT_CARE</constant>. 465 </para></listitem> 466 </varlistentry> 467 <varlistentry> 468 <term><constant>EGL_MAX_SWAP_INTERVAL</constant></term> 469 <listitem><para> 470 Must be followed by a integer that indicates the 471 maximum value that can be passed to 472 <citerefentry><refentrytitle>eglSwapInterval</refentrytitle></citerefentry>. 473 The default value is 474 <constant>EGL_DONT_CARE</constant>. 475 </para></listitem> 476 </varlistentry> 477 <varlistentry> 478 <term><constant>EGL_MIN_SWAP_INTERVAL</constant></term> 479 <listitem><para> 480 Must be followed by a integer that indicates the 481 minimum value that can be passed to eglSwapInterval. 482 The default value is <constant>EGL_DONT_CARE</constant>. 483 </para></listitem> 484 </varlistentry> 485 <varlistentry> 486 <term><constant>EGL_RED_SIZE</constant></term> 487 <listitem><para> 488 Must be followed by a nonnegative integer that 489 indicates the desired size of the red component of 490 the color buffer, in bits. If this value is zero, 491 color buffers with the smallest red component size 492 are preferred. Otherwise, color buffers with the 493 largest red component of at least the specified size 494 are preferred. The default value is zero. 495 </para></listitem> 496 </varlistentry> 497 <varlistentry> 498 <term><constant>EGL_SAMPLE_BUFFERS</constant></term> 499 <listitem><para> 500 Must be followed by the minimum acceptable number of 501 multisample buffers. Configurations with the 502 smallest number of multisample buffers that meet or 503 exceed this minimum number are preferred. Currently 504 operation with more than one multisample buffer is 505 undefined, so only values of zero or one will 506 produce a match. The default value is zero. 507 </para></listitem> 508 </varlistentry> 509 <varlistentry> 510 <term><constant>EGL_SAMPLES</constant></term> 511 <listitem><para> 512 Must be followed by the minimum number of 513 samples required in multisample buffers. 514 Configurations with the smallest number of 515 samples that meet or exceed the specified 516 minimum number are preferred. Note that it is 517 possible for color samples in the multisample 518 buffer to have fewer bits than colors in the 519 main color buffers. However, multisampled 520 colors maintain at least as much color 521 resolution in aggregate as the main color 522 buffers. 523 </para></listitem> 524 </varlistentry> 525 <varlistentry> 526 <term><constant>EGL_STENCIL_SIZE</constant></term> 527 <listitem> 528 <para> 529 Must be followed by a nonnegative integer that 530 indicates the desired stencil buffer size, in bits. 531 The smallest stencil buffers of at least the 532 specified size are preferred. If the desired size is 533 zero, frame buffer configurations with no stencil 534 buffer are preferred. The default value is zero. 535 </para> 536 <para> 537 The stencil buffer is used only by OpenGL and 538 OpenGL ES client APIs. 539 </para> 540 </listitem> 541 </varlistentry> 542 <varlistentry> 543 <term><constant>EGL_RENDERABLE_TYPE</constant></term> 544 <listitem> 545 <para> 546 Must be followed by a bitmask indicating which types 547 of client API contexts the frame buffer 548 configuration must support creating with 549 <citerefentry><refentrytitle>eglCreateContext</refentrytitle></citerefentry>). 550 Mask bits are the same as for attribute 551 <constant>EGL_CONFORMANT</constant>. The default 552 value is <constant>EGL_OPENGL_ES_BIT</constant>. 553 </para> 554 </listitem> 555 </varlistentry> 556 <varlistentry> 557 <term><constant>EGL_SURFACE_TYPE</constant></term> 558 <listitem> 559 <para> 560 Must be followed by a bitmask indicating which EGL 561 surface types and capabilities the frame buffer 562 configuration must support. Mask bits include: 563 </para> 564 <variablelist> 565 <varlistentry> 566 <term><constant>EGL_MULTISAMPLE_RESOLVE_BOX_BIT</constant></term> 567 <listitem><para> 568 Config allows specifying box filtered 569 multisample resolve behavior with 570 <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>. 571 </para></listitem> 572 </varlistentry> 573 <varlistentry> 574 <term><constant>EGL_PBUFFER_BIT</constant></term> 575 <listitem><para> 576 Config supports creating pixel buffer surfaces. 577 </para></listitem> 578 </varlistentry> 579 <varlistentry> 580 <term><constant>EGL_PIXMAP_BIT</constant></term> 581 <listitem><para> 582 Config supports creating pixmap surfaces. 583 </para></listitem> 584 </varlistentry> 585 <varlistentry> 586 <term><constant>EGL_SWAP_BEHAVIOR_PRESERVED_BIT</constant></term> 587 <listitem><para> 588 Config allows setting swap behavior for 589 color buffers with 590 <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>. 591 </para></listitem> 592 </varlistentry> 593 <varlistentry> 594 <term><constant>EGL_VG_ALPHA_FORMAT_PRE_BIT</constant></term> 595 <listitem><para> 596 Config allows specifying OpenVG rendering 597 with premultiplied alpha values at surface 598 creation time (see 599 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>, 600 <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>, 601 and 602 <citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>). 603 </para></listitem> 604 </varlistentry> 605 <varlistentry> 606 <term><constant>EGL_VG_COLORSPACE_LINEAR_BIT</constant></term> 607 <listitem><para> 608 Config allows specifying OpenVG rendering in 609 a linear colorspace at surface creation time 610 (see 611 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>, 612 <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>, 613 and 614 <citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>). 615 </para></listitem> 616 </varlistentry> 617 <varlistentry> 618 <term><constant>EGL_WINDOW_BIT</constant></term> 619 <listitem><para> 620 Config supports creating window surfaces. 621 </para></listitem> 622 </varlistentry> 623 </variablelist> 624 <para> 625 For example, if the bitmask is set to 626 <inlineequation> 627 <mml:math> 628 <mml:mi><constant>EGL_WINDOW_BIT</constant></mml:mi> 629 <mml:mo>|</mml:mo> 630 <mml:mi><constant>EGL_PIXMAP_BIT</constant></mml:mi> 631 </mml:math> 632 </inlineequation>, 633 only frame buffer configurations that support both 634 windows and pixmaps will be considered. The default 635 value is <constant>EGL_WINDOW_BIT</constant>. 636 </para> 637 </listitem> 638 </varlistentry> 639 <varlistentry> 640 <term><constant>EGL_TRANSPARENT_TYPE</constant></term> 641 <listitem><para> 642 Must be followed by one of 643 <constant>EGL_NONE</constant> or 644 <constant>EGL_TRANSPARENT_RGB</constant>. If 645 <constant>EGL_NONE</constant> is specified, then 646 only opaque frame buffer configurations will be 647 considered. If 648 <constant>EGL_TRANSPARENT_RGB</constant> is 649 specified, then only transparent frame buffer 650 configurations will be considered. The default value 651 is <constant>EGL_NONE</constant>. 652 </para> 653 <para> 654 Most implementations support only opaque frame 655 buffer configurations. 656 </para> 657 </listitem> 658 </varlistentry> 659 <varlistentry> 660 <term><constant>EGL_TRANSPARENT_RED_VALUE</constant></term> 661 <listitem><para> 662 Must be followed by an integer value indicating the 663 transparent red value. The value must be between 664 zero and the maximum color buffer value for red. 665 Only frame buffer configurations that use the 666 specified transparent red value will be considered. 667 The default value is 668 <constant>EGL_DONT_CARE</constant>. 669 </para> 670 <para> 671 This attribute is ignored unless 672 <constant>EGL_TRANSPARENT_TYPE</constant> is included in 673 <parameter>attrib_list</parameter> and specified as 674 <constant>EGL_TRANSPARENT_RGB</constant>. 675 </para></listitem> 676 </varlistentry> 677 <varlistentry> 678 <term><constant>EGL_TRANSPARENT_GREEN_VALUE</constant></term> 679 <listitem><para> 680 Must be followed by an integer value indicating the 681 transparent green value. The value must be between 682 zero and the maximum color buffer value for green. 683 Only frame buffer configurations that use the 684 specified transparent green value will be 685 considered. The default value is 686 <constant>EGL_DONT_CARE</constant>. 687 </para> 688 <para> 689 This attribute is ignored unless 690 <constant>EGL_TRANSPARENT_TYPE</constant> is included in 691 <parameter>attrib_list</parameter> and specified as 692 <constant>EGL_TRANSPARENT_RGB</constant>. 693 </para></listitem> 694 </varlistentry> 695 <varlistentry> 696 <term><constant>EGL_TRANSPARENT_BLUE_VALUE</constant></term> 697 <listitem><para> 698 Must be followed by an integer value indicating the 699 transparent blue value. The value must be between 700 zero and the maximum color buffer value for blue. 701 Only frame buffer configurations that use the 702 specified transparent blue value will be considered. 703 The default value is 704 <constant>EGL_DONT_CARE</constant>. 705 </para> 706 <para> 707 This attribute is ignored unless 708 <constant>EGL_TRANSPARENT_TYPE</constant> is included in 709 <parameter>attrib_list</parameter> and specified as 710 <constant>EGL_TRANSPARENT_RGB</constant>. 711 </para></listitem> 712 </varlistentry> 713 </variablelist> 714 <para> 715 When more than one EGL frame buffer configuration matches 716 the specified attributes, a list of matching configurations 717 is returned. The list is sorted according to the following 718 precedence rules, which are applied in ascending order 719 (i.e., configurations that are considered equal by a lower 720 numbered rule are sorted by the higher numbered rule): 721 </para> 722 <orderedlist> 723 <listitem><para> 724 Special: by <constant>EGL_CONFIG_CAVEAT</constant>, 725 where the precedence is <constant>EGL_NONE</constant>, 726 <constant>EGL_SLOW_CONFIG</constant>, and 727 <constant>EGL_NON_CONFORMANT_CONFIG</constant>. 728 </para></listitem> 729 <listitem><para> 730 Special: by <constant>EGL_COLOR_BUFFER_TYPE</constant>, 731 where the precedence is 732 <constant>EGL_RGB_BUFFER</constant>, 733 <constant>EGL_LUMINANCE_BUFFER</constant>. 734 </para></listitem> 735 <listitem> 736 <para> 737 Special: by larger total number of color bits (for an 738 RGB color buffer, this is the sum of 739 <constant>EGL_RED_SIZE</constant>, 740 <constant>EGL_GREEN_SIZE</constant>, 741 <constant>EGL_BLUE_SIZE</constant>, and 742 <constant>EGL_ALPHA_SIZE</constant>; for a luminance 743 color buffer, the sum of 744 <constant>EGL_LUMINANCE_SIZE</constant> and 745 <constant>EGL_ALPHA_SIZE</constant>). If the requested 746 number of bits in <parameter>attrib_list</parameter> is 747 <constant>0</constant> or 748 <constant>EGL_DONT_CARE</constant> for a particular 749 color component, then the number of bits for that 750 component is not considered. 751 </para> 752 <para> 753 This sort rule places configs with deeper color buffers 754 before configs with shallower color buffers, which may 755 be counterintuitive. 756 </para> 757 </listitem> 758 <listitem><para> 759 Smaller <constant>EGL_BUFFER_SIZE</constant>. 760 </para></listitem> 761 <listitem><para> 762 Smaller <constant>EGL_SAMPLE_BUFFERS</constant>. 763 </para></listitem> 764 <listitem><para> 765 Smaller <constant>EGL_SAMPLES</constant>. 766 </para></listitem> 767 <listitem><para> 768 Smaller <constant>EGL_DEPTH_SIZE</constant>. 769 </para></listitem> 770 <listitem><para> 771 Smaller <constant>EGL_STENCIL_SIZE</constant>. 772 </para></listitem> 773 <listitem><para> 774 Smaller <constant>EGL_ALPHA_MASK_SIZE</constant>. 775 </para></listitem> 776 <listitem><para> 777 Special: <constant>EGL_NATIVE_VISUAL_TYPE</constant> 778 (the actual sort order is implementation-defined, 779 depending on the meaning of native visual types). 780 </para></listitem> 781 <listitem><para> 782 Smaller <constant>EGL_CONFIG_ID</constant> (this is 783 always the last sorting rule, and guarantees a unique 784 ordering). 785 </para></listitem> 786 </orderedlist> 787 <para> 788 <type>EGLConfigs</type> are not sorted with respect to the 789 attributes <constant>EGL_BIND_TO_TEXTURE_RGB</constant>, 790 <constant>EGL_BIND_TO_TEXTURE_RGBA</constant>, 791 <constant>EGL_CONFORMANT</constant>, 792 <constant>EGL_LEVEL</constant>, 793 <constant>EGL_NATIVE_RENDERABLE</constant>, 794 <constant>EGL_MAX_SWAP_INTERVAL</constant>, 795 <constant>EGL_MIN_SWAP_INTERVAL</constant>, 796 <constant>EGL_RENDERABLE_TYPE</constant>, 797 <constant>EGL_SURFACE_TYPE</constant>, 798 <constant>EGL_TRANSPARENT_TYPE</constant>, 799 <constant>EGL_TRANSPARENT_RED_VALUE</constant>, 800 <constant>EGL_TRANSPARENT_GREEN_VALUE</constant>, and 801 <constant>EGL_TRANSPARENT_BLUE_VALUE</constant>. 802 </para> 803 </refsect1> 804 <refsect1 id="examples"><title>Examples</title> 805 <para> 806 The following example specifies a frame buffer configuration 807 in the normal frame buffer (not an overlay or underlay). The 808 returned frame buffer configuration supports a color buffer 809 with at least 4 bits each of red, green and blue, and 810 possibly no alpha bits. The code shown in the example may or 811 may not have a depth buffer, or a stencil buffer. 812 </para> 813 <programlisting>EGLint const attrib_list[] = { 814 EGL_RED_SIZE, 4, 815 EGL_GREEN_SIZE, 4, 816 EGL_BLUE_SIZE, 4, 817 EGL_NONE 818};</programlisting> 819 </refsect1> 820 <refsect1 id="notes"><title>Notes</title> 821 <para> 822 <constant>EGL_RENDERABLE_TYPE</constant> bit 823 <constant>EGL_OPENGL_BIT</constant>, and 824 <constant>EGL_SURFACE_TYPE</constant> bits 825 <constant>EGL_MULTISAMPLE_RESOLVE_BOX_BIT</constant> and 826 <constant>EGL_SWAP_BEHAVIOR_PRESERVED_BIT</constant> are 827 supported only if the EGL version is 1.4 or greater. 828 </para> 829 <para> 830 <constant>EGL_CONFORMANT</constant>, 831 <constant>EGL_MATCH_NATIVE_PIXMAP</constant>, 832 <constant>EGL_RENDERABLE_TYPE</constant> bit 833 <constant>EGL_OPENGL_ES2_BIT</constant>, and 834 <constant>EGL_SURFACE_TYPE</constant> bits 835 <constant>EGL_VG_ALPHA_FORMAT_PRE_BIT</constant> and 836 <constant>EGL_VG_COLORSPACE_LINEAR_BIT</constant> are 837 supported only if the EGL version is 1.3 or greater. 838 </para> 839 <para> 840 <constant>EGL_ALPHA_MASK_SIZE</constant>, 841 <constant>EGL_COLOR_BUFFER_TYPE</constant>, 842 <constant>EGL_LUMINANCE_SIZE</constant>, 843 <constant>EGL_RENDERABLE_TYPE</constant>, and 844 <constant>EGL_RENDERABLE_TYPE</constant> bits 845 <constant>EGL_OPENGL_ES_BIT</constant> and 846 <constant>EGL_OPENVG_BIT</constant> are supported only if 847 the EGL version is 1.2 or greater. 848 </para> 849 <para> 850 If OpenGL or OpenGL ES rendering is supported for a 851 luminance color buffer, it is treated as RGB rendering with 852 the value of <constant>GL_RED_BITS</constant> equal to 853 <constant>EGL_LUMINANCE_SIZE</constant> and the values of 854 <constant>GL_GREEN_BITS</constant> and 855 <constant>GL_BLUE_BITS</constant> equal to zero. The red 856 component of fragments is written to the luminance channel 857 of the color buffer while the green and blue components are 858 discarded. 859 </para> 860 <para> 861 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry> 862 and 863 <citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry> 864 can be used to implement selection algorithms other than the 865 generic one implemented by 866 <function>eglChooseConfig</function>. Call 867 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry> 868 to retrieve all the frame buffer configurations, or 869 alternatively, all the frame buffer configurations with a 870 particular set of attributes. Next call 871 <citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry> 872 to retrieve additional attributes for the frame buffer 873 configurations and then select between them. 874 </para> 875 <para> 876 EGL implementors are strongly discouraged, but not 877 proscribed, from changing the selection algorithm used by 878 <function>eglChooseConfig</function>. Therefore, selections 879 may change from release to release of the client-side 880 library. 881 </para> 882 </refsect1> 883 <refsect1 id="errors"><title>Errors</title> 884 <para> 885 <constant>EGL_FALSE</constant> is returned on failure, 886 <constant>EGL_TRUE</constant> otherwise. 887 <parameter>configs</parameter> and 888 <parameter>num_config</parameter> are not modified when 889 <constant>EGL_FALSE</constant> is returned. 890 </para> 891 <para> 892 <constant>EGL_BAD_DISPLAY</constant> is generated if 893 <parameter>display</parameter> is not an EGL display connection. 894 </para> 895 <para> 896 <constant>EGL_BAD_ATTRIBUTE</constant> is generated if 897 <parameter>attribute_list</parameter> contains an invalid frame buffer 898 configuration attribute or an 899 attribute value that is unrecognized or out of range. 900 </para> 901 <para> 902 <constant>EGL_NOT_INITIALIZED</constant> is generated if 903 <parameter>display</parameter> has not been initialized. 904 </para> 905 <para> 906 <constant>EGL_BAD_PARAMETER</constant> is generated if 907 <parameter>num_config</parameter> is <constant>NULL</constant>. 908 </para> 909 </refsect1> 910 <refsect1 id="seealso"><title>See Also</title> 911 <para> 912 <citerefentry><refentrytitle>eglCreateContext</refentrytitle></citerefentry>, 913 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>, 914 <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>, 915 <citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>, 916 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>, 917 <citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry>, 918 <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>, 919 <citerefentry><refentrytitle>eglSwapInterval</refentrytitle></citerefentry> 920 </para> 921 </refsect1> 922 <refsect3 id="Copyright"><title></title> 923 <!-- Content included from copyright.inc.xsl --> 924 <imageobject> 925 <imagedata fileref="KhronosLogo.jpg" format="jpg" /> 926 </imageobject> 927 <para /> 928 </refsect3> 929</refentry> 930
