Provided by: libwaffle-doc_1.8.0-2build1_all bug

NAME

       waffle_config, waffle_config_choose, waffle_config_destroy, waffle_config_get_native -
       class waffle_config

SYNOPSIS

       #include <waffle.h>

       struct waffle_config;

       struct waffle_config* waffle_config_choose(struct waffle_display *display,
                                                  const int32_t attrib_list[]);

       bool waffle_config_destroy(struct waffle_config *self);

       union waffle_native_config* waffle_config_get_native(struct waffle_config *self);

DESCRIPTION

       struct waffle_config
           An opaque type.

       waffle_config_choose()
           Choose a config on display that satifisfies the set of attributes specified by
           attrib_list. The config can later be used to create surfaces and contexts with
           waffle_window_create(3) and waffle_context_create(3).

           attrib_list consists of a zero-terminated sequence of name/value pairs. If an
           attribute is absent from attrib_list, then it assumes its default value. If
           attrib_list is null, then it is intrepreted the same as the empty list, which is the
           list that contains only the terminal zero. See the section called “ATTRIBUTES” below
           for details on the set of attributes that may appear in attrib_list.

       waffle_config_destroy()
           Destroy the config and release its memory.

       waffle_config_get_native()
           Get the config's underlying native objects. Use free(3) to deallocate the returned
           pointer. See waffle_native(3) for the definition of union waffle_native_config.

DISCUSSION

       The context attributes (WAFFLE_CONTEXT_*) have quirks that are specific to the native
       platform. Waffle attempts to accomdate those quirks in a platform-neutral way as much as
       possible, but not all quirks can be eliminated through a platform abstraction layer. The
       quirks are documented below in detail.

       For example, one quirk that Waffle is able to accommodate is that some platforms require
       specification of context attributes at different times. GLX requires that the context
       attributes be specified at time of context creation [glXCreateContextAttribsARB(3)] but
       MacOS requires the attributes to be specified when choosing a config
       [CGLChoosePixelFormat]. Therefore, Waffle is constrained by MacOS to require the
       attributes at time of waffle_config_choose().

       For additional documentation on the behavior of context attributes on each platform, refer
       to the following:

           For GLX, refer to the GLX 1.4 Specification[1] and the specifications for extensions
           GLX_ARB_create_context_profile[2] and GLX_EXT_create_context_es2_profile[3].

           For EGL, refer to the EGL 1.4 Specification[4] and the specifications for extension
           EGL_KHR_create_context[5].

           For CGL, refer to the documentation of kCGLPFAOpenGLProfile in the CGL Reference[6].

ATTRIBUTES

       WAFFLE_CONTEXT_API
           This is a required attribute; it has no default value. It must be one of:
               WAFFLE_CONTEXT_OPENGL
               WAFFLE_CONTEXT_OPENGL_ES1
               WAFFLE_CONTEXT_OPENGL_ES2
               WAFFLE_CONTEXT_OPENGL_ES3

           The actual set of supported values depends on the native platform. To check if the
           system supports a given API, use waffle_display_supports_context_api(3). Invariants
           and expectations for each platform are discussed below.

           On Android, WAFFLE_CONTEXT_OPENGL_ES1 is always supported. Beginning with Ice Cream
           Sandwich (that is, Android 4.0), WAFFLE_CONTEXT_OPENGL_ES2 is also supported. Use
           waffle_display_supports_context_api(3) to check if additional APIs are supported.

           On GLX, WAFFLE_CONTEXT_OPENGL is always supported. The system may optionally support
           additional APIs.

           On EGL platforms other than Android, no API is guaranteed to be supported. One must
           use waffle_display_supports_context_api(3) to check for supported APIs.

           On MacOS, only WAFFLE_CONTEXT_OPENGL is supported. This may change in the future if
           Apple adds support for additional APIs.

       WAFFLE_CONTEXT_MAJOR_VERSION
       WAFFLE_CONTEXT_MINOR_VERSION
           This pair of attributes is optional. They specify the context version that
           waffle_context_create(3) will request.

           The pair's default value and set of accepted values depend on the value of
           WAFFLE_CONTEXT_API and the native platform. Below is described in detail the rules by
           which waffle filters the set of accepted values according to the value of
           WAFFLE_CONTEXT_API. Even if waffle_config_choose() accepts the requested version and
           successfully returns a config, the native platform may later reject the requested
           version when waffle_context_create(3) is called.

           If the requested API is WAFFLE_CONTEXT_OPENGL_ES1, then the default value is 1.0. The
           only accepted values are 1.0 and 1.1.

           If the requested API is WAFFLE_CONTEXT_OPENGL_ES2, then the default value is 2.0.
           Waffle accepts any value that is at least 2.0 and strictly less than 3.0.

           If the requested API is WAFFLE_CONTEXT_OPENGL_ES3, then the default value is 3.0.
           Waffle accepts any value that is at least 3.0 and strictly less than 4.0.

           If the requested API is WAFFLE_CONTEXT_OPENGL, then the default and minimum accepted
           value is 1.0.

       WAFFLE_CONTEXT_PROFILE
           This attributes is optional. It specifies the context profile that
           waffle_context_create(3) will request.

           The attribute's default value and set of accepted values depend on the values of
           WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_MAJOR_VERSION, WAFFLE_CONTEXT_MINOR_VERSION, and
           the native platform. Below is described in detail the rules by which waffle decides
           the default value and the set of accepted values. Even if waffle_config_choose()
           accepts the requested profile and successfully returns a config, the native platform
           may later reject the requested profile when waffle_context_create(3) is called.

           If the requested API is WAFFLE_CONTEXT_OPENGL_ES1, WAFFLE_CONTEXT_OPENGL_ES2, or
           WAFFLE_CONTEXT_OPENGL_ES3, then the default and only accepted value is WAFFLE_NONE.

           If the requested API is WAFFLE_CONTEXT_OPENGL and the requested version is less than
           3.2, then the default and only accepted value is WAFFLE_NONE.

           If the requested API is WAFFLE_CONTEXT_OPENGL and the requested version is at least
           3.2, then default value is WAFFLE_CONTEXT_CORE_PROFILE. The set of accepted values is
           WAFFLE_CONTEXT_CORE_PROFILE and WAFFLE_CONTEXT_COMPATIBILITY_PROFILE.

       WAFFLE_CONTEXT_FORWARD_COMPATIBLE
           This attribute, if true, instructs waffle_context_create(3) to create a
           forward-compatible context. However, even if waffle_config_choose() successfully
           returns a config for a forward-compatible context, the native platform may later
           reject it when waffle_context_create(3) is called.

           Forward-compatible contexts do not support functionality marked as deprecated by that
           version of the API. A non-forward-compatible context supports all functionality in
           that version, deprecated or not.

           This attribute is optional and its default value is false(0). Valid values are
           true(1), false(0), and WAFFLE_DONT_CARE. However, true(1) is valid only if the
           requested context API is WAFFLE_CONTEXT_OPENGL and its version is at least 3.0.

       WAFFLE_CONTEXT_DEBUG
           This attribute, if true, instructs waffle_context_create(3) to create a debug context.
           However, even if waffle_config_choose() successfully returns a config for a debug
           context, the native platform may later reject it when waffle_context_create(3) is
           called.

           Debug contexts are intended for use during application development, to provide
           additional runtime checking, validation, and logging functionality while possibly
           incurring performance penalties. The additional functionality provided by debug
           contexts may vary according to the implementation. In some cases a debug context may
           be identical to a non-debug context.

           This attribute is optional and its default value is false(0). Valid values are
           true(1), false(0), and WAFFLE_DONT_CARE.

       WAFFLE_CONTEXT_ROBUST_ACCESS
           This attribute, if true, instructs waffle_context_create(3) to create a robust access
           context.

           Robust access contexts can implement additional runtime checks, such as bounds checks
           for various operations.

           This attribute is optional and its default value is false(0). Valid values are
           true(1), false(0), and WAFFLE_DONT_CARE.

       WAFFLE_RED_SIZE
       WAFFLE_GREEN_SIZE
       WAFFLE_BLUE_SIZE
       WAFFLE_ALPHA_SIZE
       WAFFLE_DEPTH_SIZE
       WAFFLE_STENCIL_SIZE
           The default value for each size attribute is 0. Valid values are the non-negative
           integers and WAFFLE_DONT_CARE. If the requested size for a channel is 0, then any
           surface created with the config will lack that channel. If the requested size for a
           channel is positive, then the number of bits in that channel for any surface created
           with the config will be at least the requested size.

       WAFFLE_SAMPLE_BUFFERS
       WAFFLE_SAMPLES
           The default value of WAFFLE_SAMPLE_BUFFERS is false(0). Valid values are true(1),
           false(0), and WAFFLE_DONT_CARE. The attribute specifies if a surface created with this
           config is double-buffered. If false, then any surface created with the config will not
           be multisampled. If true, the any surface created with the config will be
           multisampled, where the number of samples will be at least WAFFLE_SAMPLES.

           The default value of WAFFLE_SAMPLES is 0. Valid values are the non-negative integers
           and WAFFLE_DONT_CARE.

       WAFFLE_DOUBLE_BUFFERED
           The default value is true(1). Valid values are true(1), false(0), and
           WAFFLE_DONT_CARE. This attribute specifies if a surface created with this config is
           double-buffered.

       WAFFLE_ACCUM_BUFFER
           The default value is false(0). Valid values are true(1), false(0), and
           WAFFLE_DONT_CARE. This attribute specifies if a surface created with this config
           possesses an accumulation buffer.

RETURN VALUE

       Functions whose return type is bool return true on success and false on failure. Functions
       whose return type is a pointer return NULL on failure. Use waffle_error_get_info(3) to get
       information about any errors.

ERRORS

       See waffle_error(3) for the complete list of waffle's error codes.

       Listed below are the errors specific to the waffle_config functions.

       waffle_config_choose()

           WAFFLE_ERROR_BAD_ATTRIBUTE
               An item in attrib_list is unrecognized or has an invalid value, or a required
               attribute is missing.

           WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM
               If the native platform does not expose the necessary functionality to create a
               context with the properties specified by config or if waffle can predetermine that
               the native platform will reject the config at context creation, but otherwise the
               requested attributes are valid, then WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM is
               emitted.

               For example,

               •   GLX supports creation of an OpenGL ES2 context only if libGLESv2.so.2 is
                   installed and if GLX_EXT_create_context_es2_profile is exposed as both a
                   server and client extension.

               •   MacOS does not support the OpenGL 3.2 Compatibility Profile, and it supports
                   the OpenGL 3.2 Core Profile only for MacOS >= 10.7 on select GPU's.

EXAMPLES

   Example 1
       Choose a config for an OpenGL legacy context that has at least 8 bits in each of the RGBA
       channels.

           #include <stdlib.h>
           #include <waffle.h>

           static const int32_t init_attrib_list[] = {
               WAFFLE_PLATFORM, WAFFLE_PLATFORM_GLX,
               0,
           };

           static const int32_t config_attrib_list[] = {
               WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_OPENGL,

               WAFFLE_RED_SIZE,    8,
               WAFFLE_GREEN_SIZE,  8,
               WAFFLE_BLUE_SIZE,   8,
               WAFFLE_ALPHA_SIZE,  8,

               0,
           };

           int
           main()
           {
               struct waffle_display *display;
               struct waffle_config *config;
               bool ok;

               ok = waffle_init(init_attrib_list);
               if (!ok)
                 exit(EXIT_FAILURE);

               display = waffle_display_connect(NULL);
               if (!display)
                 exit(EXIT_FAILURE);

               config = waffle_config_choose(config_attrib_list);
               if (!config)
                 exit(EXIT_FAILURE);

               // Now clean up.
               waffle_config_destroy(config);
               waffle_display_disconnect(display);
               return EXIT_SUCCESS;
           }

   Example 2
       An attribute list for creating an OpenGL 3.2 Core Profile context that has depth and
       stencil buffers and some non-zero number of bits in each of the RGB channels. Since the
       default value of WAFFLE_ALPHA_SIZE is WAFFLE_DONT_CARE, the config may not have an alpha
       channel.

           const int32_t attrib_list[] = {
               WAFFLE_CONTEXT_API,             WAFFLE_CONTEXT_OPENGL,
               WAFFLE_CONTEXT_MAJOR_VERSION,   3,
               WAFFLE_CONTEXT_MINOR_VERSION,   2,
               WAFFLE_CONTEXT_PROFILE,         WAFFLE_CONTEXT_CORE_PROFILE,

               WAFFLE_RED_SIZE,                1,
               WAFFLE_GREEN_SIZE,              1,
               WAFFLE_BLUE_SIZE,               1,

               WAFFLE_DEPTH_SIZE,             24,
               WAFFLE_STENCIL_SIZE,            8,

               0,
           };

ISSUES

       Please report bugs or and feature requests to
       https://gitlab.freedesktop.org/mesa/waffle/issues.

SEE ALSO

       waffle(7) waffle_context_create(3) waffle_window_create(3)

AUTHOR

       Chad Versace <chad.versace@linux.intel.com>
           Former maintainer

COPYRIGHT

       Copyright © 2013 Intel

       This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United
       States License (CC BY-SA 3.0). To view a copy of this license, visit
       http://creativecommons.org.license/by-sa/3.0/us.

NOTES

        1. GLX 1.4 Specification
           http://www.opengl.org/registry/doc/glx1.4.pdf

        2. GLX_ARB_create_context_profile
           http://www.opengl.org/registry/specs/ARB/glx_create_context.txt

        3. GLX_EXT_create_context_es2_profile
           http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt

        4. EGL 1.4 Specification
           http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf

        5. EGL_KHR_create_context
           http://www.khronos.org/registry/egl/extensions/KHR/EGL_KHR_create_context.txt

        6. CGL Reference
           https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html