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