Module gui::gui

GUI: cross-platform windows + software framebuffer.

The std/gui stack, bottom to top (include only what you use):

gui.h          windows, events, clipboard, cursors, the pixel buffer
gui_draw.h     the original integer primitives + 8x8 bitmap font
gui_canvas.h   anti-aliased 2D vector canvas (paths, gradients, images,
               transforms, clipping, blend modes, TrueType text)
gui_text.h     TrueType/OpenType fonts and text layout
gui_widget.h   retained widget toolkit (layout, theming, ~35 widgets)
gui_app.h      application object: many windows, one event loop,
               timers, animation frames
gui_backend.h  the interface a windowing backend implements
gui_headless.h an in-memory backend (tests, CI, offscreen rendering)
gui_gpu.h      GPU presentation (OpenGL ES/EGL, Metal, Direct3D 11, WebGL)
gui_wayland.h  the Wayland backend (Linux)
gui_web.h      the WebAssembly <canvas> backend

Exactly one platform backend is linked — safeguard picks it by the file's suffix for the target (see gui_backend.h for the contract):

std/gui/gui_cocoa.sc   macOS, via the Objective-C runtime + Core Graphics
std/gui/gui_win32.sc   Windows, via the Win32 API
std/gui/gui_x11.sc     Linux/BSD/Unix, via Xlib — and on Linux the
                       Wayland backend next to it, chosen at run time
                       when there is a compositor (gui_wayland.h)
std/gui/gui_web_wasm.sc  WebAssembly: <canvas> elements of a web page
                       (gui_web.h, with std/gui/gui_web.js)
std/gui/gui_fb.sc      bare metal, via a linear framebuffer (see gui_fb.h)

A program can also install another backend at run time before its first window (gui_set_backend(), gui_backend.h) — gui_headless.h's in-memory one (or any program: SAFEC_GUI_BACKEND=headless). Presenting can go through the GPU instead of a software blit: gui_gpu.h.

Every backend presents the same model: a window owns a CPU-side pixel buffer, 'pixels' — RGBA8888, premultiplied alpha, top-left origin, row-major, 4 bytes per pixel, R first in memory on every platform — that the application draws into (directly, through gui_draw.h, through gui_canvas.h, or through the widget toolkit), and win.present() puts it on the screen (the backend converts to its native pixel order on the way, or hands it to a GPU presenter: see gui_backend.h's GuiPresenter). Rasterization is always on the CPU, deterministic and identical on every backend: the same frame is the same bytes on Cocoa, Win32, X11, bare metal and the headless backend.

Sizes: a window's size is given in logical units (points on macOS, device-independent pixels on Windows, pixels on X11). With GuiWindowOptions.hiDpi set, the pixel buffer is the window's size times the display's scale factor (win.scale, e.g. 2.0 on a Retina display), so drawing is sharp; otherwise scale is 1 and the OS scales the window up. Event coordinates and win.width/height are always in buffer pixels.