WAFFLE_CONFIG(3)

📦

version 1.8.3 · 7 versions

🧇 WAFFLE_CONFIG(3) — straight from the Waffle Manual 💖

okay bestie, sit down, hydrate, because today we're learning about waffle_config and she is lowkey the main character of your whole rendering setup. this is part 1 of 2, so pace yourself 🫶

📛 NAME

waffle_config, waffle_config_choose, waffle_config_destroy, waffle_config_get_native — the entire waffle_config class, all four of them, holding hands 🌸

✨ 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. meaning you don't get to peek inside her little purse, you just hold the pointer and trust the process 💜
waffle_config_choose() — picks you a config on display that satisfies the whole set of attributes you listed in attrib_list. then, later, that config can be used to make surfaces and contexts with waffle_window_create(3) and waffle_context_create(3). slay.

so attrib_list is a zero-terminated sequence of name/value pairs. no cap. if some attribute isn't in attrib_list at all, it just chills at its default value. and if attrib_list is null? that gets interpreted the exact same as the empty list — aka the list that has nothing in it except the terminal zero. so null is not special, bestie, it's just the empty one 🙈

head down to the “ATTRIBUTES” section below for the full rundown of what's allowed to show up in attrib_list.

waffle_config_destroy() — destroys the config and frees her memory. say goodbye, be normal about it 😭
waffle_config_get_native() — hands you the config's underlying native objects. use free(3) to deallocate the pointer you get back, okay? don't just leave her floating. see waffle_native(3) for the definition of union waffle_native_config 🌈

🗣️ DISCUSSION

okay so here's the tea: the context attributes (WAFFLE_CONTEXT_*) have quirks that are specific to each native platform. Waffle tries so hard to accommodate those quirks in a platform-neutral way, as much as she possibly can — but not every single quirk can be eliminated through a platform abstraction layer. the ones that survive are documented in detail below, bestie, we're not hiding anything 💀

for example, one quirk Waffle is able to accommodate: some platforms want you to specify the context attributes at a different moment than others. GLX requires the context attributes be specified at the time of context creation — that's glXCreateContextAttribsARB(3) — but MacOS requires the attributes to be specified when you're choosing a config — that's CGLChoosePixelFormat. so therefore, Waffle is constrained by MacOS into requiring the attributes at the time of waffle_config_choose(). the vibes are: MacOS sets the curfew 🕰️

want more documentation on how context attributes behave on each platform? go read these:

for GLX, refer to the GLX 1.4 Specification[1] and the specifications for the 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 specification for the extension EGL_KHR_create_context[5].
for CGL, refer to the documentation of kCGLPFAOpenGLProfile in the CGL Reference[6].

🌟 ATTRIBUTES

WAFFLE_CONTEXT_API — this one is a required attribute. she has no default value. she must be exactly 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 your native platform. to check whether the system supports a given API, use waffle_display_supports_context_api(3). the 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. you 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 is optional. together 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 on the native platform. below is the detailed description of the rules by which Waffle filters the set of accepted values according to the value of WAFFLE_CONTEXT_API. and listen — 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. so it's giving "we'll see" 😭

if the requested API is WAFFLE_CONTEXT_OPENGL_ES1, 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, 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, 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, the default and minimum accepted value is 1.0.

WAFFLE_CONTEXT_PROFILE — optional. she specifies the context profile that waffle_context_create(3) will request.

her 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 the detailed description of the rules by which Waffle decides the default value and the set of accepted values. and again, even if waffle_config_choose() accepts the requested profile and successfully returns a config, the native platform may later reject that requested profile when waffle_context_create(3) is called. iconic of her honestly 💅

if the requested API is WAFFLE_CONTEXT_OPENGL_ES1, WAFFLE_CONTEXT_OPENGL_ES2, or WAFFLE_CONTEXT_OPENGL_ES3, 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, 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, the 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 — if true, this attribute 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. yes, again. no, we are not okay 🙈

forward-compatible contexts do not support functionality that's marked as deprecated by that version of the API. a non-forward-compatible context supports all the functionality in that version — deprecated or not. so choose wisely bestie.

this attribute is optional and her 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. read that again 🫶

WAFFLE_CONTEXT_DEBUG — if true, this attribute instructs waffle_context_create(3) to create a debug context. but you already know what's coming: 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 extra runtime checking, validation, and logging functionality — while possibly incurring performance penalties. the additional functionality a debug context gives you may vary according to the implementation. in some cases a debug context may be identical to a non-debug context. so like. sometimes she shows up, sometimes she just vibes identically to the regular one.

this attribute is optional and her default value is false(0). valid values are true(1), false(0), and WAFFLE_DONT_CARE.

WAFFLE_CONTEXT_ROBUST_ACCESS — if true, this attribute 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. she's careful, she double-checks, we love her for it 🧚

this attribute is optional and her 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. that's the promise. periodt 🌈
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. yes she said it twice, she's consistent 💖
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. an accumulation buffer. fancy ✨

🎁 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. and use waffle_error_get_info(3) to get the info on any errors — she'll tell you what went wrong bestie, just ask 💜

💥 ERRORS 💥

First thing bestie: the whole master list of waffle error codes lives in waffle_error(3), go look there for the full buffet. 🍓

But down below is the stuff that's specific to the waffle_config functions. Slay.

`waffle_config_choose()`

WAFFLE_ERROR_BAD_ATTRIBUTE — an item in attrib_list is unrecognized, or its value is invalid, or a required attribute just... isn't there. Missing attribute? Rude. Blocked. 💀
WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM — okay so this one is for when the native platform simply doesn't have the functionality to make a context with the properties that config is asking for, or when waffle can predetermine that the native platform is gonna reject the config at context creation time — but the requested attributes themselves are valid. That's when this bad boy gets emitted.

For example, no cap:

GLX only supports creating an OpenGL ES2 context if libGLESv2.so.2 is installed and if GLX_EXT_create_context_es2_profile is exposed as both a server and client extension. Two conditions, both non-negotiable.
MacOS does not support the OpenGL 3.2 Compatibility Profile at all, and it supports the OpenGL 3.2 Core Profile only for MacOS >= 10.7 on select GPU's. So... yeah. Check your GPU bestie. 🫶

🌈 EXAMPLES 🌈

Example 1

Choosing a config for an OpenGL legacy context that has at least 8 bits in each of the RGBA channels. Iconic, honestly.

#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

Now this one is 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. And here's the lil plot twist: since the default value of WAFFLE_ALPHA_SIZE is WAFFLE_DONT_CARE, the config may not have an alpha channel. Like, it might, it might not. No promises. 🙈

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 🐛

Found a bug? Got a feature request? Do not suffer in silence, bestie — please report it right here: https://gitlab.freedesktop.org/mesa/waffle/issues. The maintainers wanna hear it fr fr. 💖

Go read those next, they're the sequel. ✨

👑 AUTHOR 👑

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

Former maintainer 🌸

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

📚 NOTES 📚

GLX 1.4 Specification http://www.opengl.org/registry/doc/glx1.4.pdf
GLX_ARB_create_context_profile http://www.opengl.org/registry/specs/ARB/glx_create_context.txt
GLX_EXT_create_context_es2_profile http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt
EGL 1.4 Specification http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf
EGL_KHR_create_context http://www.khronos.org/registry/egl/extensions/KHR/EGL_KHR_create_context.txt
CGL Reference https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html

And that's a wrap on WAFFLE_CONFIG(3) bestie!! 💅✨ This page came from the waffle manual and it's dated 07/06/2026. Go forth and choose your configs, you absolute icon. Periodt. 🎀🦋

📦 where this page comes from

ubuntu stonking: libwaffle-doc 1.8.3-1 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms