GUI Platforms & GPU (std/gui/) #

How std/gui reaches the screen on each platform: the Wayland backend next to X11 on Linux, the WebAssembly backend that turns windows into <canvas> elements of a web page, and GPU presentation through OpenGL ES (EGL), Metal, Direct3D 11 or WebGL. None of this changes how a program draws: rendering stays on the CPU, so a frame is the same bytes everywhere — the browser frame of examples/gui_gallery matches its native headless snapshot pixel for pixel, except for the bars that animate with the clock.

Choosing X11 or Wayland #

A Linux build contains both backends; the first window decides:

#include <std/gui/gui_wayland.h>

if (!gui_use_wayland()) { /* no compositor: X11 it is */ }   // or force it in code, before the first window

gui_wayland_available() connects (once) and reports whether Wayland can be used; gui_wayland_backend() is the backend table (null on non-Linux targets).

Nothing is linked: libwayland-client, libxkbcommon and libwayland-cursor are dlopen()ed, so one binary runs on an X11-only system too. safeguard bundle lists their packages under the .deb's Recommends, never Depends.

Wayland #

Wayland gives a client no say over window positions, raising or focusing its own windows, or staying on top: set_position() is ignored (and pos_x()/pos_y() stay GUI_POS_DEFAULT unless set), focus() does nothing, and topmost is ignored.

Tested under sway and Weston, both headless (tests/stdlib/wayland/run.sh): frames read back with grim (full and partial presents, several in flight), input from a virtual pointer and keyboard the test creates on its own connection (motion, buttons, wheel, keys with Shift and Ctrl, key repeat), the clipboard against wl-copy/wl-paste, compositor and client resizes, hide/show, close, two windows under one GuiApp, fractional scale 1.5, and the EGL presenter.

The web #

On wasm32/wasm64, std/gui's backend is the browser page. The host side is std/gui/gui_web.js, an ES module shipped with std:

import { loadSafeCGui, fetchFiles } from "./gui_web.js";

const files = await fetchFiles({ "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf": "fonts/DejaVuSans.ttf" });
const app = await loadSafeCGui(fetch("app.wasm"), { files, entry: "start" });

A browser can't block, so a web program doesn't call GuiApp::run(). Its entry point — any export_name function; the glue calls it once — opens the windows and hands the app to gui_web_run(), which returns at once; the page then runs one app.pump(0) per requestAnimationFrame until it returns 0. Everything else — widgets, the canvas, timers, animation frames — is the desktop code unchanged:

#include <std/gui/gui_app.h>
#include <std/gui/gui_web.h>

static struct GuiApp gApp;          // outlives start()

__attribute__((export_name("start")))
int start() {
    gApp = GuiApp::new();
    ?&GuiWindow w = gApp.open_window("Hello", 480, 320);
    match (w) {
        case some(win): { gApp.set_root(win, Widget::button("Hi")); }
        case null: { return 1; }
    }
    gui_web_run(&gApp);
    return 0;
}

gui_web.js options: canvas, fit, title (the first window's title becomes document.title), windows, container, present ("webgl" / "2d"), preserveDrawingBuffer, files, entry, loadSafeC, domGlue, imports, globals. The returned gui object has start(), stop(), frame(), canvas(id), element(id), input(id) and presenter(id). The glue also supplies the libc a freestanding module may still import — a small printf/snprintf, getenv (nothing set), the files reads, Math-backed libm.

A page from safeguard #

safeguard bundle --target wasm32 builds the program and writes build/<name>.web/: the module, the glue of every std module it uses (gui_web.js, safec_dom.js, audio_web.js), the [bundle] resources, and an index.html that loads them. Serve the folder over HTTP (python3 -m http.server -d build/<name>.web): browsers don't instantiate WebAssembly from file://. No [bundle] table is needed; with one, these keys apply:

[bundle]
name        = "GuiWeb"
identifier  = "org.safec.gui-web"
web_entry   = "start"                 # the export the page calls (default)
web_present = "webgl"                 # or "2d"
web_windows = "frames"                # or "canvas" (default)
web_page    = "web/index.html"        # your page instead of the generated one
web_files   = ["fonts/Inter.ttf=/usr/share/fonts/truetype/inter/Inter.ttf"]
                                      # files the module can fopen() ("src" or "src=path")

examples/gui_web is a complete web program (safeguard bundle --target wasm32 in it); examples/gui_gallery runs in a page too (its start export).

Tested under Node against a fake DOM (tests/stdlib/wasm_gui/run.sh: three windows, widgets clicked and typed into, IME and virtual-keyboard text, the clipboard, resizes, scale changes, frames dragged and resized, WebGL2/WebGL1 with partial uploads and context loss, the DOM interop) and in headless Chromium through Playwright (browser.sh: the gallery, built for wasm32 with the native build's fonts, matches its native snapshot through both putImageData and WebGL (SwiftShader); real mouse, keyboard and insertText input; frames dragged; the generated safeguard bundle page).

GPU presentation #

#include <std/gui/gui_gpu.h>

struct GuiWindowOptions o = GuiWindowOptions::new("Video", 1280, 720);
o.present = GUI_PRESENT_GPU;          // GUI_PRESENT_DEFAULT / GPU / CPU
struct GuiWindow win = GuiWindow::create_with(&o);
const char* how = gui_window_presenter_name(&win);   // "gl", "metal", "d3d11", "webgl" or "cpu"

A presenter uploads the frame into a texture — only the damaged rectangle (or, without a row-length setting, the damaged rows) — and draws it as one quad, or blits it into the swap chain:

Any failure — no driver or library, a context or swap chain that can't be made, a device or WebGL context lost later — sends the window back to the software path for good, without the program noticing beyond gui_window_uses_gpu() turning 0. Worth it for large windows redrawn often (animation, video, games); for a mostly static UI the software path is just as good.

Tested: "gl" for real on Xvfb with Mesa llvmpipe (tests/stdlib/x11/run.sh: frames read back, partial updates, resizes, two GL windows, switching to software and back) and on sway (wayland/run.sh, scale 1 and 1.5); "d3d11" under Wine, whose wined3d translates to OpenGL (tests/stdlib/win32/run.sh: frames, a partial update, a resize, back to GDI); "webgl" in headless Chromium with SwiftShader and under Node; "metal" compiled for arm64 and x86_64 macOS only.

Writing a presenter #

A GuiPresenter (gui_backend.h) is three functions: attach(st, handles) gets the window's native handles (GuiNativeHandle: display, window, view, visual) and keeps its state in st.presenterData; present(st, pixels, bufW, bufH, x, y, w, h) gets exactly what the backend's window_present would — premultiplied RGBA, the damaged rectangle — and must cope with the size changing between frames; detach(st) frees it. A presenter that fails for good while presenting frees its data, sets st.presenter = null and hands the frame to the backend's window_present. Attach one with gui_window_set_presenter().