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.
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, and width at most 1280 pixels. The UEFI loader imposes
its own GOP constraints.
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 leaves room for
future modes. 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).
- Small rects copy whole. A window repaint within the budget never tears.
- Large rects are chunked. A full-screen redraw continues across loop iterations; newer damage is queued behind it.
- No fixed frame rate. The loop flushes whenever there is pending damage, so a cursor move reaches the screen within one loop.
- Re-entry guard.
vga_present_shadow()refuses to run while another process is mid-flush; a full-screen copy is long enough to be preempted. - Window drags flush immediately.
wm_drag_shadowcopies each drag step as one consistent frame.
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 and the CPU temperature/battery percentage, plus draggable
terminal and canvas windows with a title bar and close button.
Click-to-focus, drag-by-title-bar and close are routed through the
same pointer path. The right-aligned date/time text is also a
target: it highlights on hover and opens the Date & Time editor
(bin/settime) on a click.
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.
PRESENT.
- Terminal windows are canvas clients: ucmd_term.c renders its rows into the RGB565 window canvas; keys arrive through the generic
SYS_KEY_POLLorSYS_WIN_KEY_WAIT. The WM no longer has a text-cell path. - Canvas windows are generic: the app gets a back buffer, pointer position/buttons/focus and queued press/release edges with capture.
- Focus and z-order are explicit; closing a window kills its session and frees its canvas.
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.
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.
SYS_WIN_CREATE creates a generic canvas window. Input is
exposed through SYS_WIN_POINTER (content-relative
position, button mask, focus) and SYS_WIN_EVENT, which
queues press/release edges and a capture window. A click that starts
in a window still receives its release after the pointer leaves.
The WM process itself is special: it maps the screen shadow at
0x58000000 and each front canvas at
0x59000000 + index × 2 MB, which is how it composites
without reading another process's memory.
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.
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, nine
procedural icons, a theme palette, layout cut helpers and scrolling
panes. It is linked into files, mines,
solitaire and the real gallery.elf.
- Text fields support drag-selection, double-click select-all, Ctrl+Left/Right word jumps, Ctrl+Delete/Backspace word deletion and Ctrl+A. They use the proportional face with measured caret, selection and horizontal scrolling; a field marked
disabledignores pointer and keyboard input, drops the focus and paints its value dimmed in the same proportional face. The terminal and editor keep the 8×16 cell grid. - Clip stack keeps nested panes and popups inside their parents.
- Layout cuts split a rectangle into rows, columns and fixed margins without a constraint solver.
- No retained widget tree. Apps redraw from state every frame, which keeps the toolkit small and predictable.
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 and
Liberation Mono subsets 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.
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.
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 Date & Time editor. Clicking the top-bar date/time opens settime, which reads and writes the CMOS RTC.
browser
HTML/CSS renderer with flex rows, auto-fit card grids, inline-block runs, basic tables and inline SVG diagrams. It decodes inline images and fetches through a headless helper; there is no JavaScript or form submission. 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 links the same objects and decodes HTTP bodies in memory.
- Formats. PNG, baseline and progressive JPEG, animated GIF, BMP, TGA, PNM, ICO/CUR and PAM.
- Drawing.
img_draw()is a clipped, scaled RGB565 blit: box-filter downscale, bilinear upscale, alpha over a checkerboard or over the destination. - Orientation. EXIF orientation is applied; arithmetic JPEG and CMYK are rejected.
- Cost. Downscaling runs on the CPU. The viewer caches one image; the browser keeps a display bitmap but still rescales on repaint.
GPU quirks
- ATI Mach64. A CRTC fixup is applied after mode set. The legacy CRTC is skipped under UEFI.
- NVIDIA. VBE-only. The legacy VGA CRTC is never touched. On the ION, the framebuffer is stolen DRAM behind a BAR3 aperture; nvidia.c finds the stolen range and writes through a cached alias once a WC MTRR covers it.
- Intel. The Ironlake-era path supports a hardware cursor where available; the software cursor is the common fallback.
- UEFI.
vga.chonours the RGBX flag and skips the VBE-only ATI CRTC reset and NVIDIA stolen-VRAM alias. mouse.c forces the software cursor.
Source map
vga.c,vga.h— framebuffer and damagevga_copy.S— copy primitivesblit.c,blit.h— pixel vtablecpu.c— SSE2 probingwm.c,wm.h— kernel window serverucmd_wm.c,uwm_lib.c— ring-3 WMucmd_settime.c,rtc.c— Date & Time editor and RTC accessgfx.c,gfx.h— RGB565 window canvasessys_wm.c,sys_wm.h— WM/window ABIbrowser.c,browser_html.c— HTML/CSS renderer and inline SVGngui.c,ngui.h— toolkitufont.c,ufont_ttf.c,ufont_draw.c— fixed-point TrueType textfonts/*.ttf— Arimo / Liberation Mono subsets in the packucmd_files.c,gallery.c,ucmd_solitaire.cimg*.c— image codecsati.c,nvidia.c,intel.c,nv50.c