man/waffle_config.3.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   Copyright Intel 2012
   7
   8   This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0
   9   US). To view a copy of this license, visit http://creativecommons.org.license/by-sa/3.0/us.
  10 -->
  11
  12 <refentry
  13     id="waffle_config"
  14     xmlns:xi="http://www.w3.org/2001/XInclude">
  15
  16   <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->
  17
  18   <refmeta>
  19     <refentrytitle>waffle_config</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>waffle_config</refname>
  25     <refname>waffle_config_choose</refname>
  26     <refname>waffle_config_destroy</refname>
  27     <refname>waffle_config_get_native</refname>
  28     <refpurpose>class <classname>waffle_config</classname></refpurpose>
  29   </refnamediv>
  30
  31   <refentryinfo>
  32     <title>Waffle Manual</title>
  33     <productname>waffle</productname>
  34     <xi:include href="common/author-chad.versace.xml"/>
  35     <xi:include href="common/copyright.xml"/>
  36     <xi:include href="common/legalnotice.xml"/>
  37   </refentryinfo>
  38
  39   <refsynopsisdiv>
  40
  41     <funcsynopsis language="C">
  42
  43       <funcsynopsisinfo>
  44 #include &lt;waffle.h&gt;
  45
  46 struct waffle_config;
  47       </funcsynopsisinfo>
  48
  49       <funcprototype>
  50         <funcdef>struct waffle_config* <function>waffle_config_choose</function></funcdef>
  51         <paramdef>struct waffle_display *<parameter>display</parameter></paramdef>
  52         <paramdef>const int32_t <parameter>attrib_list</parameter>[]</paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>bool <function>waffle_config_destroy</function></funcdef>
  57         <paramdef>struct waffle_config *<parameter>self</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>union waffle_native_config* <function>waffle_config_get_native</function></funcdef>
  62         <paramdef>struct waffle_config *<parameter>self</parameter></paramdef>
  63       </funcprototype>
  64
  65     </funcsynopsis>
  66   </refsynopsisdiv>
  67
  68   <refsect1>
  69     <title>Description</title>
  70
  71     <variablelist>
  72
  73       <varlistentry>
  74         <term><type>struct waffle_config</type></term>
  75         <listitem>
  76           <para>
  77             An opaque type.
  78           </para>
  79         </listitem>
  80       </varlistentry>
  81
  82       <varlistentry>
  83         <term><function>waffle_config_choose()</function></term>
  84         <listitem>
  85           <para>
  86             Choose a config on <parameter>display</parameter> that satifisfies the set of attributes specified by
  87             <parameter>attrib_list</parameter>.
  88
  89             The config can later be used to create surfaces and contexts with
  90
  91             <citerefentry><refentrytitle><function>waffle_window_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry> and
  92             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  93           </para>
  94
  95           <para>
  96             <parameter>attrib_list</parameter> consists of a zero-terminated sequence of name/value pairs.  If an
  97             attribute is absent from <parameter>attrib_list</parameter>, then it assumes its default value.  If
  98             <parameter>attrib_list</parameter> is null, then it is intrepreted the same as the empty list, which is the
  99             list that contains only the terminal zero.
 100
 101             See <xref linkend="sect.attributes"/> below for details on the set of attributes that may appear in
 102             <parameter>attrib_list</parameter>.
 103           </para>
 104
 105           <para>
 106           </para>
 107         </listitem>
 108       </varlistentry>
 109
 110       <varlistentry>
 111         <term><function>waffle_config_destroy()</function></term>
 112         <listitem>
 113           <para>
 114             Destroy the config and release its memory.
 115           </para>
 116         </listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term><function>waffle_config_get_native()</function></term>
 121         <listitem>
 122           <para>
 123             Get the config's underlying native objects. Use
 124             <citerefentry><refentrytitle><function>free</function></refentrytitle><manvolnum>3</manvolnum></citerefentry> to deallocate the
 125             returned pointer.
 126             See <citerefentry><refentrytitle>waffle_native</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 127             for the definition of <type>union waffle_native_config</type>.
 128           </para>
 129         </listitem>
 130       </varlistentry>
 131
 132     </variablelist>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>Discussion</title>
 137
 138     <para>
 139       The context attributes (<constant>WAFFLE_CONTEXT_*</constant>) have quirks that are specific to the native
 140       platform. Waffle attempts to accomdate those quirks in a platform-neutral way as much as possible, but not all
 141       quirks can be eliminated through a platform abstraction layer. The quirks are documented below in detail.
 142     </para>
 143
 144     <para>
 145       For example, one quirk that Waffle is able to accommodate is that some platforms require specification of context
 146       attributes at different times.  GLX requires that the context attributes be specified at time of context creation
 147       [<citerefentry><refentrytitle><function>glXCreateContextAttribsARB</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>]
 148       but MacOS requires the attributes to be specified when choosing
 149       a config [<function>CGLChoosePixelFormat</function>].  Therefore, Waffle is constrained by MacOS to require the
 150       attributes at time of <function>waffle_config_choose()</function>.
 151     </para>
 152
 153     <para>
 154       For additional documentation on the behavior of context attributes on each platform, refer to the following:
 155
 156       <simplelist>
 157
 158         <member><para>
 159             For GLX, refer to the
 160             <ulink url="http://www.opengl.org/registry/doc/glx1.4.pdf">GLX 1.4 Specification</ulink>
 161             and the specifications for extensions
 162             <ulink url="http://www.opengl.org/registry/specs/ARB/glx_create_context.txt">GLX_ARB_create_context_profile</ulink> and
 163             <ulink url="http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt">GLX_EXT_create_context_es2_profile</ulink>.
 164         </para></member>
 165
 166         <member><para>
 167             For EGL, refer to the
 168             <ulink url="http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf">EGL 1.4 Specification</ulink>
 169             and the specifications for extension
 170             <ulink url="http://www.khronos.org/registry/egl/extensions/KHR/EGL_KHR_create_context.txt">EGL_KHR_create_context</ulink>.
 171         </para></member>
 172
 173         <member><para>
 174             For CGL, refer to the documentation of <function>kCGLPFAOpenGLProfile</function> in the
 175             <ulink url="https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html">CGL Reference</ulink>.
 176         </para></member>
 177
 178       </simplelist>
 179     </para>
 180   </refsect1>
 181
 182   <refsect1
 183       id="sect.attributes">
 184
 185     <title>Attributes</title>
 186
 187     <variablelist>
 188
 189       <varlistentry>
 190         <term><constant>WAFFLE_CONTEXT_API</constant></term>
 191         <listitem>
 192           <para>
 193             This is a required attribute; it has no default value. It must be one of:
 194             <simplelist>
 195               <member><constant>WAFFLE_CONTEXT_OPENGL</constant></member>
 196               <member><constant>WAFFLE_CONTEXT_OPENGL_ES1</constant></member>
 197               <member><constant>WAFFLE_CONTEXT_OPENGL_ES2</constant></member>
 198               <member><constant>WAFFLE_CONTEXT_OPENGL_ES3</constant></member>
 199             </simplelist>
 200           </para>
 201           <para>
 202             The actual set of supported values depends on the native platform.  To check if the system supports a given
 203             API, use
 204             <citerefentry><refentrytitle><function>waffle_display_supports_context_api</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 205             Invariants and expectations for each platform are discussed below.
 206           </para>
 207           <para>
 208             On Android, <constant>WAFFLE_CONTEXT_OPENGL_ES1</constant> is always supported.  Beginning with Ice Cream
 209             Sandwich (that is, Android 4.0), <constant>WAFFLE_CONTEXT_OPENGL_ES2</constant> is also supported.  Use
 210             <citerefentry><refentrytitle><function>waffle_display_supports_context_api</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 211             to check if additional APIs are supported.
 212           </para>
 213           <para>
 214             On GLX, <constant>WAFFLE_CONTEXT_OPENGL</constant> is always supported. The system may optionally support
 215             additional APIs.
 216           </para>
 217           <para>
 218             On EGL platforms other than Android, no API is guaranteed to be supported. One must use
 219             <citerefentry><refentrytitle><function>waffle_display_supports_context_api</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 220             to check for supported APIs.
 221           </para>
 222           <para>
 223             On MacOS, only <constant>WAFFLE_CONTEXT_OPENGL</constant> is supported. This may change in the future if
 224             Apple adds support for additional APIs.
 225           </para>
 226         </listitem>
 227       </varlistentry>
 228
 229       <varlistentry>
 230         <term><constant>WAFFLE_CONTEXT_MAJOR_VERSION</constant></term>
 231         <term><constant>WAFFLE_CONTEXT_MINOR_VERSION</constant></term>
 232         <listitem>
 233           <para>
 234             This pair of attributes is optional.
 235
 236             They specify the context version that
 237             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 238             will request.
 239           </para>
 240
 241           <para>
 242             The pair's default value and set of accepted values depend on the value of
 243             <constant>WAFFLE_CONTEXT_API</constant> and the native platform.
 244
 245             Below is described in detail the rules by which waffle filters the set of accepted values according to the
 246             value of <constant>WAFFLE_CONTEXT_API</constant>.
 247
 248             Even if <function>waffle_config_choose()</function> accepts the requested version
 249             and successfully returns a config,
 250
 251             the native platform may later reject the requested version when
 252             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 253             is called.
 254           </para>
 255
 256           <para>
 257             If the requested API is <constant>WAFFLE_CONTEXT_OPENGL_ES1</constant>,
 258             then the default value is 1.0.
 259
 260             The only accepted values are 1.0 and 1.1.
 261           </para>
 262
 263           <para>
 264             If the requested API is <constant>WAFFLE_CONTEXT_OPENGL_ES2</constant>,
 265             then the default value is 2.0.
 266
 267             Waffle accepts any value that is at least 2.0 and strictly less than 3.0.
 268           </para>
 269
 270           <para>
 271             If the requested API is <constant>WAFFLE_CONTEXT_OPENGL_ES3</constant>,
 272             then the default value is 3.0.
 273
 274             Waffle accepts any value that is at least 3.0 and strictly less than 4.0.
 275           </para>
 276
 277           <para>
 278             If the requested API is <constant>WAFFLE_CONTEXT_OPENGL</constant>,
 279             then the default and minimum accepted value is 1.0.
 280           </para>
 281         </listitem>
 282       </varlistentry>
 283
 284       <varlistentry>
 285         <term><constant>WAFFLE_CONTEXT_PROFILE</constant></term>
 286         <listitem>
 287           <para>
 288             This attributes is optional.
 289
 290             It specifies the context profile that
 291             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 292             will request.
 293           </para>
 294
 295           <para>
 296             The attribute's default value and set of accepted values depend on the values of
 297             <constant>WAFFLE_CONTEXT_API</constant>,
 298             <constant>WAFFLE_CONTEXT_MAJOR_VERSION</constant>,
 299             <constant>WAFFLE_CONTEXT_MINOR_VERSION</constant>,
 300             and the native platform.
 301
 302             Below is described in detail the rules by which waffle decides
 303
 304             the default value and the set of accepted values.
 305
 306             Even if <function>waffle_config_choose()</function> accepts the requested profile
 307             and successfully returns a config,
 308
 309             the native platform may later reject the requested profile when
 310             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 311             is called.
 312           </para>
 313
 314           <para>
 315             If the requested API is
 316             <constant>WAFFLE_CONTEXT_OPENGL_ES1</constant>,
 317             <constant>WAFFLE_CONTEXT_OPENGL_ES2</constant>, or
 318             <constant>WAFFLE_CONTEXT_OPENGL_ES3</constant>,
 319
 320             then the default and only accepted value is <constant>WAFFLE_NONE</constant>.
 321           </para>
 322
 323           <para>
 324             If the requested API is <constant>WAFFLE_CONTEXT_OPENGL</constant>
 325
 326             and the requested version is less than 3.2,
 327
 328             then the default and only accepted value is <constant>WAFFLE_NONE</constant>.
 329           </para>
 330
 331           <para>
 332             If the requested API is <constant>WAFFLE_CONTEXT_OPENGL</constant>
 333
 334             and the requested version is at least 3.2,
 335
 336             then default value is <constant>WAFFLE_CONTEXT_CORE_PROFILE</constant>.
 337
 338             The set of accepted values is
 339
 340             <constant>WAFFLE_CONTEXT_CORE_PROFILE</constant> and
 341             <constant>WAFFLE_CONTEXT_COMPATIBILITY_PROFILE</constant>.
 342           </para>
 343         </listitem>
 344       </varlistentry>
 345
 346       <varlistentry>
 347         <term><constant>WAFFLE_CONTEXT_FORWARD_COMPATIBLE</constant></term>
 348         <listitem>
 349           <para>
 350             This attribute, if true, instructs
 351             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 352             to create a forward-compatible context.
 353
 354             However, even if <function>waffle_config_choose()</function>
 355             successfully returns a config for a forward-compatible context, the
 356             native platform may later reject it when
 357             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 358             is called.
 359           </para>
 360           <para>
 361             Forward-compatible contexts do not support functionality marked as
 362             deprecated by that version of the API.  A non-forward-compatible
 363             context supports all functionality in that version, deprecated or
 364             not.
 365           </para>
 366           <para>
 367             This attribute is optional and its default value is false(0).
 368
 369             Valid values are true(1), false(0), and <constant>WAFFLE_DONT_CARE</constant>.
 370
 371             However, true(1) is valid only if
 372             the requested context API is <constant>WAFFLE_CONTEXT_OPENGL</constant>
 373             and its version is at least 3.0.
 374           </para>
 375         </listitem>
 376       </varlistentry>
 377
 378       <varlistentry>
 379         <term><constant>WAFFLE_CONTEXT_DEBUG</constant></term>
 380         <listitem>
 381           <para>
 382             This attribute, if true, instructs
 383             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 384             to create a debug context.
 385
 386             However, even if <function>waffle_config_choose()</function>
 387             successfully returns a config for a debug context, the
 388             native platform may later reject it when
 389             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 390             is called.
 391           </para>
 392           <para>
 393             Debug contexts are intended for use during application development, to provide additional runtime checking,
 394             validation, and logging functionality while possibly incurring performance penalties. The additional
 395             functionality provided by debug contexts may vary according to the implementation. In some cases a debug
 396             context may be identical to a non-debug context.
 397           </para>
 398           <para>
 399             This attribute is optional and its default value is false(0).
 400
 401             Valid values are true(1), false(0), and <constant>WAFFLE_DONT_CARE</constant>.
 402           </para>
 403         </listitem>
 404       </varlistentry>
 405
 406       <varlistentry>
 407         <term><constant>WAFFLE_CONTEXT_ROBUST_ACCESS</constant></term>
 408         <listitem>
 409           <para>
 410             This attribute, if true, instructs
 411             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 412             to create a robust access context.
 413           </para>
 414           <para>
 415             Robust access contexts can implement additional runtime checks, such as bounds checks for various
 416             operations.
 417           </para>
 418           <para>
 419             This attribute is optional and its default value is false(0).
 420
 421             Valid values are true(1), false(0), and <constant>WAFFLE_DONT_CARE</constant>.
 422           </para>
 423         </listitem>
 424       </varlistentry>
 425
 426       <varlistentry>
 427         <term><constant>WAFFLE_RED_SIZE</constant></term>
 428         <term><constant>WAFFLE_GREEN_SIZE</constant></term>
 429         <term><constant>WAFFLE_BLUE_SIZE</constant></term>
 430         <term><constant>WAFFLE_ALPHA_SIZE</constant></term>
 431         <term><constant>WAFFLE_DEPTH_SIZE</constant></term>
 432         <term><constant>WAFFLE_STENCIL_SIZE</constant></term>
 433         <listitem>
 434           <para>
 435             The default value for each size attribute is <constant>0</constant>.
 436
 437             Valid values are the non-negative integers and <constant>WAFFLE_DONT_CARE</constant>.
 438
 439             If the requested size
 440             for a channel is 0, then any surface created with the config will lack that channel. If the requested size
 441             for a channel is positive, then the number of bits in that channel for any surface created with the config
 442             will be at least the requested size.
 443           </para>
 444         </listitem>
 445       </varlistentry>
 446
 447       <varlistentry>
 448         <term><constant>WAFFLE_SAMPLE_BUFFERS</constant></term>
 449         <term><constant>WAFFLE_SAMPLES</constant></term>
 450         <listitem>
 451           <para>
 452             The default value of <constant>WAFFLE_SAMPLE_BUFFERS</constant> is false(0).
 453
 454             Valid values are true(1), false(0), and <constant>WAFFLE_DONT_CARE</constant>.
 455
 456             The attribute specifies if a surface created with this config is double-buffered.
 457
 458             If false, then any surface created with the config will not be multisampled. If true, the any surface
 459             created with the config will be multisampled, where the number of samples will be at least
 460             <constant>WAFFLE_SAMPLES</constant>.
 461           </para>
 462           <para>
 463             The default value of <constant>WAFFLE_SAMPLES</constant> is <constant>0</constant>.
 464
 465             Valid values are the non-negative integers and <constant>WAFFLE_DONT_CARE</constant>.
 466           </para>
 467         </listitem>
 468       </varlistentry>
 469
 470       <varlistentry>
 471         <term><constant>WAFFLE_DOUBLE_BUFFERED</constant></term>
 472         <listitem>
 473           <para>
 474             The default value is true(1).
 475
 476             Valid values are true(1), false(0), and <constant>WAFFLE_DONT_CARE</constant>.
 477
 478             This attribute specifies if a surface created with this config is double-buffered.
 479           </para>
 480         </listitem>
 481       </varlistentry>
 482
 483       <varlistentry>
 484         <term><constant>WAFFLE_ACCUM_BUFFER</constant></term>
 485         <listitem>
 486           <para>
 487             The default value is false(0).
 488
 489             Valid values are true(1), false(0), and <constant>WAFFLE_DONT_CARE</constant>.
 490
 491             This attribute specifies if a surface created with this config possesses an accumulation buffer.
 492           </para>
 493         </listitem>
 494       </varlistentry>
 495
 496     </variablelist>
 497   </refsect1>
 498
 499   <refsect1>
 500     <title>Return Value</title>
 501     <xi:include href="common/return-value.xml"/>
 502   </refsect1>
 503
 504   <refsect1>
 505     <title>Errors</title>
 506
 507     <xi:include href="common/error-codes.xml"/>
 508
 509     <para>
 510       Listed below are the errors specific to the <type>waffle_config</type> functions.
 511     </para>
 512
 513     <variablelist>
 514
 515       <varlistentry>
 516         <term><function>waffle_config_choose()</function></term>
 517         <listitem>
 518           <variablelist>
 519
 520             <varlistentry>
 521               <term><errorcode>WAFFLE_ERROR_BAD_ATTRIBUTE</errorcode></term>
 522               <listitem>
 523                 <para>
 524                   An item in <parameter>attrib_list</parameter> is unrecognized or has an invalid value, or a required
 525                   attribute is missing.
 526                 </para>
 527               </listitem>
 528             </varlistentry>
 529
 530             <varlistentry>
 531               <term><errorcode>WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM</errorcode></term>
 532               <listitem>
 533                 <para>
 534                   If the native platform does not expose the necessary functionality to create a context with the
 535                   properties specified by config
 536
 537                   or if waffle can predetermine that the native platform will reject the config at context creation,
 538
 539                   but otherwise the requested attributes are valid,
 540
 541                   then <constant>WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM</constant> is emitted.
 542                 </para>
 543
 544                 <para>
 545                   For example,
 546
 547                   <itemizedlist>
 548                     <listitem>
 549                       <para>
 550                         GLX supports creation of an OpenGL ES2 context only if libGLESv2.so.2 is installed and if
 551                         GLX_EXT_create_context_es2_profile is exposed as both a server and client extension.
 552                       </para>
 553                     </listitem>
 554                     <listitem>
 555                       <para>
 556                       MacOS does not support the OpenGL 3.2 Compatibility Profile, and it supports the OpenGL 3.2 Core Profile
 557                       only for MacOS >= 10.7 on select GPU's.
 558                     </para>
 559                     </listitem>
 560                   </itemizedlist>
 561                 </para>
 562               </listitem>
 563             </varlistentry>
 564
 565           </variablelist>
 566
 567         </listitem>
 568       </varlistentry>
 569
 570     </variablelist>
 571
 572   </refsect1>
 573
 574   <refsect1>
 575     <title>Examples</title>
 576
 577     <refsect2>
 578       <title>Example 1</title>
 579
 580       <para>
 581         Choose a config for an OpenGL legacy context that has at least 8 bits in each of the RGBA channels.
 582
 583         <programlisting>
 584 <![CDATA[
 585 #include <stdlib.h>
 586 #include <waffle.h>
 587
 588 static const int32_t init_attrib_list[] = {
 589     WAFFLE_PLATFORM, WAFFLE_PLATFORM_GLX,
 590     0,
 591 };
 592
 593 static const int32_t config_attrib_list[] = {
 594     WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_OPENGL,
 595
 596     WAFFLE_RED_SIZE,    8,
 597     WAFFLE_GREEN_SIZE,  8,
 598     WAFFLE_BLUE_SIZE,   8,
 599     WAFFLE_ALPHA_SIZE,  8,
 600
 601     0,
 602 };
 603
 604 int
 605 main()
 606 {
 607     struct waffle_display *display;
 608     struct waffle_config *config;
 609     bool ok;
 610
 611
 612     ok = waffle_init(init_attrib_list);
 613     if (!ok)
 614       exit(EXIT_FAILURE);
 615
 616     display = waffle_display_connect(NULL);
 617     if (!display)
 618       exit(EXIT_FAILURE);
 619
 620     config = waffle_config_choose(config_attrib_list);
 621     if (!config)
 622       exit(EXIT_FAILURE);
 623
 624     // Now clean up.
 625     waffle_config_destroy(config);
 626     waffle_display_disconnect(display);
 627     return EXIT_SUCCESS;
 628 }
 629 ]]>
 630         </programlisting>
 631       </para>
 632     </refsect2>
 633
 634     <refsect2>
 635       <title>Example 2</title>
 636
 637       <para>
 638         An attribute list for creating an OpenGL 3.2 Core Profile context that has depth and stencil buffers and some
 639         non-zero number of bits in each of the RGB channels.  Since the default value of
 640         <constant>WAFFLE_ALPHA_SIZE</constant> is <constant>WAFFLE_DONT_CARE</constant>, the config may not have an
 641         alpha channel.
 642
 643         <programlisting>
 644 <![CDATA[
 645 const int32_t attrib_list[] = {
 646     WAFFLE_CONTEXT_API,             WAFFLE_CONTEXT_OPENGL,
 647     WAFFLE_CONTEXT_MAJOR_VERSION,   3,
 648     WAFFLE_CONTEXT_MINOR_VERSION,   2,
 649     WAFFLE_CONTEXT_PROFILE,         WAFFLE_CONTEXT_CORE_PROFILE,
 650
 651     WAFFLE_RED_SIZE,                1,
 652     WAFFLE_GREEN_SIZE,              1,
 653     WAFFLE_BLUE_SIZE,               1,
 654
 655     WAFFLE_DEPTH_SIZE,             24,
 656     WAFFLE_STENCIL_SIZE,            8,
 657
 658     0,
 659 };
 660 ]]>
 661         </programlisting>
 662       </para>
 663     </refsect2>
 664   </refsect1>
 665
 666   <xi:include href="common/issues.xml"/>
 667
 668   <refsect1>
 669     <title>See Also</title>
 670     <para>
 671       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 672       <citerefentry><refentrytitle>waffle_context_create</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 673       <citerefentry><refentrytitle>waffle_window_create</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 674     </para>
 675   </refsect1>
 676
 677 </refentry>
 678
 679 <!--
 680 vim:tw=120 et ts=2 sw=2:
 681 -->