Graphics & UI

Draw into a shadow, publish by damage.

The display path is intentionally simple: drawing lands in a RAM shadow buffer, damage rectangles describe what changed, and a budgeted flush copies those rectangles to VRAM. Windows add a compositor and a mapped-canvas ABI on top; a small immediate-mode toolkit supplies the widgets.

VBE LFB 1 MiB flush budget 8 windows RGB565 canvases

Framebuffer

The boot path writes a struct vga_boot_fb_info to 0x600: LFB base, pitch, width, height, bits per pixel and an RGBX flag for GOP's byte order. The legacy VESA stage chooses a mode with at least 16 bpp, a linear framebuffer, it must fit the card's VRAM, at most 1920 pixels wide, and its shadow (pitch × height) must fit the 8 MB reserve. 1920×1080 is the practical maximum: its 8.29 MB shadow fits, and its 4.15 MB RGB565 canvas fits the 4 MB window slot; 1920×1200 is rejected because its canvas would need 4.6 MB. The UEFI loader applies the same GOP limits.

vga.c owns the visible surface. On a normal boot the render target is a RAM shadow buffer at 0x100000, not the LFB; the 8 MB reserve holds a 1920×1080×32 frame (8.29 MB) with about 94 KB to spare. A surface carries width, height, pitch, format and a pixel-pointer, so the same drawing code can target a window layer or a canvas.

Shadow buffer & damage

Drawing never writes VRAM directly. Each operation records a damage rectangle; overlapping or touching rectangles merge, so a keystroke's cells collapse into one small rect while unrelated damage stays apart. The main loop calls vga_present_shadow() on every iteration with a byte budget of VGA_FLUSH_BUDGET_BYTES (1 MiB by default).

When the target is not the screen — a window layer or an app canvas — vga_target_damage() is a no-op. The render target override is stored in the PCB, so a preempted draw cannot leak into another process's window.

Blit backends

blit.c is the pixel-operation vtable: fill, copy, blend, canvas, present and flip. Software is the only backend today, but the WM calls the vtable rather than a fixed function, so an accelerator can replace individual operations without touching window logic.

The software fill uses an SSE2 row store when the CPU supports it. Rows that do not fit the cache use streaming stores (movntdq, one sfence per fill), which avoids read-for-ownership traffic that makes large fills DRAM-bound on the Atom. SSE/SSE2 are never assumed: the kernel is built with -mno-sse, and cpu_has_sse2() probes CPUID, sets CR4.OSFXSR/OSXMMEXCPT and is re-run on every AP.

gfxbench times fill, copy, cell, canvas and flush paths and reports the bytes actually copied by the presenter.

Window manager

The WM is a process that owns the desktop and a fixed array of eight windows. It draws a system bar with the banner, launcher buttons, clock, the temperature, and, on ThinkPads and Chromebooks, an AC/battery status icon at the far right (the Adwaita ac-adapter symbol on AC, and the battery outline with our own level fill inside on battery, with a percentage tooltip below the bar on hover, painted above the windows), plus draggable terminal and canvas windows with a title bar and close button. A normal window has no visible frame; an invisible resize band (1 px inside, 3 px outside its outer edge) is the resize grab area, and the active title bar uses the toolkit's highlight colour. Click-to-focus, drag-by-title-bar and close are routed through the same pointer path. To the left of the rightmost AC/battery status icon, a network status icon shows the Adwaita network-wired symbol for wired Ethernet, a network-wireless-signal-* symbol for a connected WiFi link, the phone symbol for RNDIS tethering, and network-wired-disconnected in red when no NIC is active (network-wireless-offline when a WiFi card is present but not associated). The whole right status area — temperature, date/time, network and AC/battery items plus the gaps between them — is one button: it opens the anchored bin/netmenu control panel (a second click closes it). It opens collapsed: the battery/clock summary and Quick settings pills are visible, while the network, power-mode and date/time settings stay hidden until their pill is clicked. Present NICs can then be selected (DHCP runs), and scanned WiFi networks can be joined, asking for the WPA2 passphrase first when the AP requires one.

A popover is a chromeless canvas window created with u_win_create_popover() (WIN_F_POPOVER). The WM anchors it flush under the top bar at the right screen edge, treats it as always topmost in painting and hit-testing, and draws no chrome at all: the canvas fills the whole window rectangle, with no title bar, shadow, rim or rounded outer corners, so it reads as a flat menu panel. The kernel uses the window origin for content-relative pointer and scroll coordinates. An outside press dismisses the popover and the click then continues normally; a second click on any status target toggles it. The panel itself is drawn with the ngui components: a battery/AC and clock summary, a brightness slider when the panel PWM is present, and Quick settings tiles for Network, the CPU power mode (SYS_CPUFREQ) and Date & Time. Clicking a tile expands that section in place — the network devices/Wi-Fi/connection lists, the three power modes, or an inline date/time editor with Set, Now and Sync NTP (no separate window). SYS_WIN_RESIZE_SELF grows or shrinks the popover to the section, clamped to SYS_SCREEN_INFO's framebuffer; the section scrolls with the wheel, touchpad or page keys when it is taller than the screen, and its overlay scrollbar slides in while the pointer is over the panel.

The WM is the ring-3 process loaded from /ramfs/bin/wm; there is no kernel WM fallback. The kernel window server in wm.c owns the shadow mapping, the per-window canvases, input routing, the cursor, kexec detection and the boot-console handoff. It starts the first terminal after the storage mount (wm_server_boot_ready) and leaves the boot console visible until the WM attaches. The console uses the same 8×16 face and top-left origin as the terminal, so the first frame replaces it without a size or position jump.

Window anatomy A window consists of a title bar, a content area backed by an RGB565 canvas, and a close control. The WM composites the canvas into the screen shadow buffer. Terminal · /ramfs/bin/ls × content canvas · RGB565 · mapped at 0x50000000 text cells, images, widgets, or arbitrary drawing
One window, one canvas. The title bar belongs to the WM; the content is whatever the owning process draws into its mapped back buffer. The WM never reads the process's memory — it composites the front canvas on PRESENT.

Compositing cost

The WM keeps a front-to-back order: the focused window first, then the remaining windows in descending slot order. For each damage rectangle it fills the desktop once and walks that order, subtracting every window in front from the region still uncovered. A window is drawn only in its exposed pieces, so a fully occluded window costs nothing and the stack is never repainted back-to-front. The kernel pointer hit-test uses the same order. A focused-window drag copies its shadow block to the new position and repaints only the old strips the new rectangle does not cover, instead of compositing the window at both positions. If either rectangle is partly off-screen the shadow has no valid pixels for the hidden part, so that step repaints the window rect instead of copying desktop background into it.

SYS_WIN_PRESENT carries a content-relative damage rectangle. The terminal tracks its dirty rows, so a keystroke copies and composites one 8×16 row block instead of the whole 512×512 canvas. The kernel unions the rectangles between WM polls and SYS_WM_INFO returns that union; a present with w == 0 or h == 0 still means the whole canvas. The WM overwrites /share/wmstats every two seconds with the interval's frame count, compositing time, worst frame and pixels drawn (usurf_pixels), which is the on-target compositor measurement.

Canvas ABI

SYS_WIN_CREATE maps the calling command's window canvas read/write at 0x50000000. The process draws RGB565 pixels and publishes a finished frame with SYS_WIN_PRESENT, optionally passing a content-relative rectangle (struct wm_win_present) for the changed region. Present copies that region from the back buffer into the composited front canvas with interrupts off, so a half-drawn frame can never reach the screen. Frames carry monotonic sequence counters, so the WM cannot lose one. content_gen comes from a global counter and is unique per window creation, so a new window that reuses a just-closed slot forces the WM to remap its front canvas instead of reusing a stale mapping.

SYS_WIN_CREATE creates a generic canvas window. struct win_create.flags can request WIN_F_POPOVER, a chromeless overlay: the canvas fills the window and the WM supplies only the topmost placement. SYS_WIN_RESIZE_SELF (115) resizes the caller's canvas and SYS_SCREEN_INFO (116) reports the framebuffer size, so a popover can collapse or grow. Input is exposed through SYS_WIN_POINTER (content-relative position, button mask, focus), SYS_WIN_EVENT, which queues press/release edges and a capture window, and SYS_WIN_SCROLL, which returns wheel/touchpad scroll accumulated for the window under the pointer in pixels (+dy is later content). A click that starts in a window still receives its release after the pointer leaves. The ngui helper ngui_scroll_wheel() applies the delta to a pane when the pointer is over it. A pane's scrollbar is an overlay: an 8 px rounded pill at its right edge that stays hidden while the pointer is outside, slides in over about 100 ms on hover, and never reduces the content rectangle or reflows a row. hide_bar suppresses it entirely. The WM process itself is special: it maps the screen shadow at 0x58000000 and each front canvas at 0x59000000 + index × 4 MB, which is how it composites without reading another process's memory. The 4 MB slot covers a full-screen 1920×1080 RGB565 canvas (4.15 MB) minus the chrome; the old 2 MB slot capped a full-height window at roughly 1050 px wide. SYS_WM_RESIZE (WM side) and SYS_WIN_ACK_RESIZE (client side) swap in a resized canvas; the content size is bounded by the framebuffer, so a window can grow to the edge of the screen.

Double-clicking a title bar maximizes the window to the work area below the system bar (0, WM_BAR_H, fbw, fbh - WM_BAR_H); the next double-click restores the saved geometry. Dropping a title-bar drag with the pointer on the left or right screen edge (WM_SNAP_EDGE, 2 px) snaps the window to that half of the work area at full height, and the top edge maximizes it. The restore geometry is saved only when a window leaves the normal state, so snapping and then maximizing still restores the original size. Dragging a maximized or snapped window restores it first, with the grab point kept at the same fraction of the title bar, and a manual resize clears the state. While a window is dragged, the screen edges and the facing edges of other windows resist it: the window stays flush until the pointer overshoots by WM_RESIST (24 px), which makes side-by-side placement exact. Windows can be dragged past the left, right and bottom edges; WM_DRAG_VISIBLE (48 px) of the title bar always stays on-screen for recovery, and the top bar is never overlapped. An invisible resize band (1 px inside, 3 px outside) runs along every edge and corner: the grabbed edges follow the pointer while the opposite edges stay put, clamped to the work area. While a drag or resize is active the WM owns the pointer, so the window content does not see the held button.

Buttons fire on the release edge. The toolkit keeps a button active until ui->released; inferring release from the sampled button mask races the WM event queue and drops clicks.

When a process exits or crashes, the reaper releases its window mappings and the window server frees the canvas. Closing a window kills its owner. Keys go through the window key queue (SYS_WIN_KEY_WAIT) or the generic SYS_KEY_POLL; Ctrl+C still reaches the terminal.

ngui toolkit

ngui.c/ngui.h is an immediate-mode GUI toolkit shared by the ring-3 apps. It provides clipped RGB565 primitives, buttons, menu items, text fields, the Adwaita symbolic icons (see UI icons), a theme palette, layout cut helpers and scrolling panes. It is linked into files, mines, solitaire, chat, the control panel and the real gallery.elf.

Proportional text comes from ufont.c: a fixed-point, integer-only TrueType parser and antialiased rasterizer. The pack carries Latin-1 Arimo regular/bold/italic/bold-italic, Liberation Mono and a curated monochrome Noto Emoji subset under /ramfs/fonts. The browser, ngui apps and the WM chrome use real pixel sizes from 8 to 48 px; the browser maps CSS font-size, font-weight, font-style and font-family: monospace to the faces. Missing fonts fall back to the 8×16 bitmap. The browser detaches the font arena before heap_reset() and reattaches after heap_start(); terminal content and the editor keep the bitmap cells.

UTF-8 text is available through ngui_text_utf8* and ngui_menu_item_utf8(). Per codepoint, the selected primary face is tried first, then the lazily loaded emoji face; cmap format 12 covers codepoints above the BMP. The emoji set is deliberately limited to common single-codepoint glyphs that fit the rasterizer's 256-point/16-contour limits. ZWJ sequences, flags, skin tones and color glyphs fall back to a tofu or ?; the browser keeps its Latin-1 byte path.

Applications

files

File browser on the VFS: opens text in edit, images in view and HTML in browser. The first ngui user.

gallery

Live showcase of every ngui control and primitive. Ships in the pack as bin/gallery.app; a launcher prefers /share/GALLERY for development.

chat

Cloudron Chat client: native OIDC login, channel/DM sidebar with unread badges and presence dots, a wrapped timeline with avatars, day headers and reply snippets, a composer and browse/new-DM pickers. Media downloads use a warm curl __serve helper; message images are also decoded there (480×320 bounds), while avatars decode at 32×32 on the chat thread, so the window keeps drawing. Saved sessions resume from /data. The top-bar Chat button launches it.

disks

Storage manager: devices, MBR partitions and mounts, per-volume mount name, read-only and automount, and Format / Install NebOS dialogs that show the kernel command's output. The top-bar Disks button and the Disks button in files launch it.

solitaire

Klondike with drag-and-drop, draw-one/three, scoring, animation and pixel-art cards on the canvas service.

view

Image viewer with fit, 1:1, zoom, pan, EXIF orientation and animated GIF playback.

clock / colors / settime

Small canvas demos: an analog clock, a colour test window, and the standalone Date & Time editor (settime). The control panel's Date & Time tile reveals its own inline editor, which reads and writes the CMOS RTC and can fetch UTC from an SNTP server.

browser

HTML/CSS renderer with flex rows, auto-fit and repeat(N, 1fr) card grids, aspect-ratio frames, inline-block runs, inline SVG icons, basic tables and inline SVG diagrams. It decodes inline images at their laid-out bounds (a JPEG gets a reduced IDCT) in the fetch helper, caches a display-size bitmap per image so repaints are 1:1, and fetches through the same helper; image repaints are coalesced and /share/IMGSTAT reports where a load spent its time. Inline and external scripts run on the vendored QuickJS engine (ES2025), and forms render and submit natively. The largest ring-3 application in the tree.

Image library

The codecs are independent of the OS and the toolkit: each takes an input buffer plus a caller-provided struct img_mem arena and returns an RGB565 image with an optional 8-bit alpha plane. The browser and the chat client link the same objects and decode HTTP bodies in memory.

UI icons

ngui's icons (ngui_icon(), ngui_icon_button(): back/forward, reload and home in the browser toolbar, folder/file/drive in files) and the WM's top-bar network/battery indicators are GNOME Adwaita symbolic icons (adwaita-icon-theme 51, LGPL-3 or CC-BY-SA-3.0). The unchanged *-symbolic.svg files live in assets/icons/adwaita/; the host tool tools/mkicons.c rasterizes each one with the browser's svg_raster.c into a 16×16 8-bit coverage mask and writes one NBICO1 bundle, /ramfs/icons/adwaita16.icn (layout in include/icon_abi.h): a 16-byte header and 24 masks, ~6.2 KB raw and ~1.3 KB gzip, so both the USB and the floppy pack carry it.

Mouse cursors

The cursor set is the GNOME Adwaita theme (adwaita-cursors 51, LGPL-3 or CC-BY-SA-3.0). Its 24 px Xcursor images are copied into assets/cursors/adwaita/ (trimmed by tools/xcursor_trim.py), and the host tool tools/mkcursors.c turns them into one NBCUR1 bundle, /ramfs/cursors/adwaita24.cur (layout in include/cursor_abi.h): 35 shapes named after the CSS cursor keywords, each with its size, hotspot, frame count and premultiplied ARGB8888 frames. The animated wait/progress spinners keep every fourth of Adwaita's 60 frames (15 frames at 64 ms, the same speed). The bundle is ~146 KB raw, ~18 KB gzip, and only in the full pack: the floppy lite pack has no room, so a floppy boot keeps the built-in 16×16 arrow.

GPU quirks

Panel backlight

The HP Chromebook 11 G5 (google/setzer, Braswell) drives its internal panel PWM from the display engine, not from the Chrome EC. The board VBT (data.vbt, block 43) declares PWM controller 0 at 200 Hz, active high. Linux uses the same Valleyview/Cherryview registers through intel_backlight.

Source map