WAFFLE_INIT(3)

📦
version 1.8.3 · 7 versions
, in ubuntu stonking

💖 WAFFLE_INIT(3) — the Waffle Manual, bestie edition 💖

okay so. hi. you're here for waffle_init, and honestly? iconic choice. this is the function that wakes waffle up from its little nap and hands it the vibe. let me walk you through it. 🌸

✨ NAME ✨

waffle_init — the one that initializes waffle's per-process global state 👑

✨ SYNOPSIS ✨

#include <waffle.h>

bool waffle_init(const int32_t attrib_list[]);

✨ DESCRIPTION ✨

so waffle_init() initializes the per-process global state of the waffle library, using the attributes you pass in attrib_list. the whole set of attributes is documented right below this, don't worry. attrib_list is a zero-terminated sequence of name/value pairs — think of it like a little list of "here's the setting, here's the value, here's the setting, here's the value… and 0 to say we're done". 🎀

most waffle functions will straight-up emit an error if you call them while waffle is unitialized. rude of them? maybe. but there's a small set of functions that can be successfully called before initialization, and those ones are explicitly documented as such. iykyk. 🫶

here's the important part, bestie, so listen: if a call to waffle_init() fails, no global state gets initialized, and the caller may safely attempt to call waffle_init() again. no harm, no foul, no cleanup needed. ✨ but if waffle has already been initialized by a successful call to waffle_init(), then you have to call waffle_teardown() to clear the global state first. otherwise calling waffle_init() again emits the error WAFFLE_ERROR_ALREADY_INITIALIZED. like girl, we already did this. 💀

✨ ATTRIBUTES ✨

WAFFLE_PLATFORM

this attribute is required. no cap. the possible values are:

  • WAFFLE_PLATFORM_ANDROID — [Android] use EGL on Android. 🍓
  • WAFFLE_PLATFORM_GBM — [Linux] use EGL with GBM, the "Generic Buffer Manager" provided by libgbm. this platform is capable of OpenGL rendering without a display manager. main character energy fr fr.
  • WAFFLE_PLATFORM_CGL — [MacOS] use CGL to create the waffle_config(3) and waffle_context(3). use Cocoa to create the waffle_window(3). 💅
  • WAFFLE_PLATFORM_GLX — [Linux only, MacOS not yet supported]
  • WAFFLE_PLATFORM_SURFACELESS_EGL — [Linux] use EGL's "surfaceless" platform, EGL_MESA_platform_surfaceless[1]. ✨
  • WAFFLE_PLATFORM_WAYLAND — [Linux] use EGL with the Wayland display server. 🌈
  • WAFFLE_PLATFORM_WGL — [Windows] use WGL on Windows. 🦋
  • WAFFLE_PLATFORM_X11_EGL — [Linux] use EGL with the X11 display server.

✨ RETURN VALUE ✨

so: 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. either way, use waffle_error_get_info(3) to get information about any errors. don't just sit there guessing, go get the info. 🔥

✨ ERRORS ✨

see waffle_error(3) for the complete list of waffle's error codes. the ones listed here are the errors specific to waffle_init():

  • WAFFLE_ERROR_ALREADY_INITIALIZED — waffle has already been initialized with a successful call to waffle_init(). bestie. we been knew. 💀
  • WAFFLE_ERROR_BAD_ATTRIBUTE — an item in attrib_list is unrecognized or has an invalid value, or a required attribute is missing. 🙈
  • WAFFLE_ERROR_BUILT_WITHOUT_SUPPORT — waffle was built without support for the requested attribute. 😭

✨ EXAMPLE ✨

here's how you initialize waffle for X11/EGL. slay.

#include <waffle.h>

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

int
main()
{
    bool ok = waffle_init(init_attrib_list);
    if (ok)
        return EXIT_SUCCESS;
    else
        return EXIT_FAILURE;
}

notice the 0 at the end? that's the zero-terminator doing its little job. 🎀

✨ ISSUES ✨

please report bugs or and feature requests to https://gitlab.freedesktop.org/mesa/waffle/issues. the maintainers want to hear from you, fr fr. 🫶

✨ SEE ALSO ✨

✨ AUTHOR ✨

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

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. EGL_MESA_platform_surfaceless https://www.khronos.org/registry/egl/extensions/MESA/EGL_MESA_platform_surfaceless.txt

aaand that's the whole page, gorgeous. 💖 this one came from the waffle source, dated 07/06/2026, and it lives at section WAFFLE_INIT(3) — go init something iconic. periodt. 💅✨🎀

📦 where this page comes from