graphics.html 52 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751
  1. <!doctype html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="utf-8">
  5. <meta name="viewport" content="width=device-width, initial-scale=1">
  6. <title>Graphics &amp; UI | NebOS Architecture</title>
  7. <meta name="description" content="NebOS graphics architecture: VBE framebuffer, shadow buffer, damage rectangles, blit vtable, window manager, canvas ABI, ngui toolkit and image library.">
  8. <link rel="icon" href="favicon.svg" type="image/svg+xml">
  9. <link rel="stylesheet" href="style.css">
  10. </head>
  11. <body>
  12. <a class="skip" href="#main">Skip to content</a>
  13. <header class="site-header">
  14. <a class="brand" href="index.html">
  15. <span class="brand-mark" aria-hidden="true"></span>
  16. <span>NebOS <span class="brand-sub">Architecture</span></span>
  17. </a>
  18. <nav class="site-nav" aria-label="Architecture sections">
  19. <a href="index.html">Overview</a>
  20. <a href="boot.html">Boot</a>
  21. <a href="memory.html">Memory</a>
  22. <a href="cpu.html">CPU</a>
  23. <a href="drivers.html">Drivers</a>
  24. <a href="filesystems.html">Filesystems</a>
  25. <a href="graphics.html" aria-current="page">Graphics</a>
  26. <a href="network.html">Network</a>
  27. <a href="userland.html">Userland</a>
  28. <a href="development.html">Development</a>
  29. </nav>
  30. </header>
  31. <main id="main" class="page">
  32. <div class="page-head">
  33. <p class="kicker">Graphics &amp; UI</p>
  34. <h1>Draw into a shadow, publish by damage.</h1>
  35. <p class="lede">
  36. The display path is intentionally simple: drawing lands in a RAM
  37. shadow buffer, damage rectangles describe what changed, and a
  38. budgeted flush copies those rectangles to VRAM. Windows add a
  39. compositor and a mapped-canvas ABI on top; a small immediate-mode
  40. toolkit supplies the widgets.
  41. </p>
  42. <div class="meta">
  43. <span class="pill">VBE LFB</span>
  44. <span class="pill">1 MiB flush budget</span>
  45. <span class="pill">8 windows</span>
  46. <span class="pill">RGB565 canvases</span>
  47. </div>
  48. </div>
  49. <nav class="toc" aria-label="On this page">
  50. <h2>On this page</h2>
  51. <ul>
  52. <li><a href="#framebuffer">Framebuffer</a></li>
  53. <li><a href="#shadow">Shadow &amp; damage</a></li>
  54. <li><a href="#blit">Blit backends</a></li>
  55. <li><a href="#wm">Window manager</a></li>
  56. <li><a href="#canvas">Canvas ABI</a></li>
  57. <li><a href="#ngui">ngui toolkit</a></li>
  58. <li><a href="#apps">Applications</a></li>
  59. <li><a href="#images">Image library</a></li>
  60. <li><a href="#icons">UI icons</a></li>
  61. <li><a href="#appicons">App icons &amp; dock</a></li>
  62. <li><a href="#cursors">Mouse cursors</a></li>
  63. <li><a href="#gpu">GPU quirks</a></li>
  64. <li><a href="#backlight">Panel backlight</a></li>
  65. <li><a href="#sources">Source map</a></li>
  66. </ul>
  67. </nav>
  68. <section id="framebuffer">
  69. <h2>Framebuffer</h2>
  70. <p>
  71. The boot path writes a <code>struct vga_boot_fb_info</code> to
  72. <code>0x600</code>: LFB base, pitch, width, height, bits per pixel
  73. and an RGBX flag for GOP's byte order. The legacy VESA stage chooses
  74. a mode with at least 16 bpp, a linear framebuffer, it must fit the
  75. card's VRAM, at most 1920 pixels wide, and its shadow (pitch ×
  76. height) must fit the 8 MB reserve. 1920×1080 is the practical
  77. maximum: its 8.29 MB shadow fits, and its 4.15 MB RGB565 canvas
  78. fits the 4 MB window slot; 1920×1200 is rejected because its
  79. canvas would need 4.6 MB. The UEFI loader applies the same GOP
  80. limits.
  81. </p>
  82. <p>
  83. <span class="file">vga.c</span> owns the visible surface. On a
  84. normal boot the render target is a RAM shadow buffer at
  85. <code>0x100000</code>, not the LFB; the 8 MB reserve holds a
  86. 1920×1080×32 frame (8.29 MB) with about 94 KB to spare. A surface
  87. carries width, height, pitch, format and a
  88. pixel-pointer, so the same drawing code can target a window layer or
  89. a canvas.
  90. </p>
  91. </section>
  92. <section id="shadow">
  93. <h2>Shadow buffer &amp; damage</h2>
  94. <p>
  95. Drawing never writes VRAM directly. Each operation records a damage
  96. rectangle; overlapping or touching rectangles merge, so a keystroke's
  97. cells collapse into one small rect while unrelated damage stays
  98. apart. The main loop calls <code>vga_present_shadow()</code> on every
  99. iteration with a byte budget of <code>VGA_FLUSH_BUDGET_BYTES</code>
  100. (1 MiB by default).
  101. </p>
  102. <ul>
  103. <li><strong>Small rects copy whole.</strong> A window repaint within the budget never tears.</li>
  104. <li><strong>Large rects are chunked.</strong> A full-screen redraw continues across loop iterations; newer damage is queued behind it.</li>
  105. <li><strong>No fixed frame rate.</strong> The loop flushes whenever there is pending damage, so a cursor move reaches the screen within one loop.</li>
  106. <li><strong>Re-entry guard.</strong> <code>vga_present_shadow()</code> refuses to run while another process is mid-flush; a full-screen copy is long enough to be preempted.</li>
  107. <li><strong>Window drags flush immediately.</strong> <code>wm_drag_shadow</code> copies each drag step as one consistent frame.</li>
  108. </ul>
  109. <p>
  110. When the target is not the screen — a window layer or an app canvas —
  111. <code>vga_target_damage()</code> is a no-op. The render target
  112. override is stored in the PCB, so a preempted draw cannot leak into
  113. another process's window.
  114. </p>
  115. </section>
  116. <section id="blit">
  117. <h2>Blit backends</h2>
  118. <p>
  119. <span class="file">blit.c</span> is the pixel-operation vtable:
  120. fill, copy, blend, canvas, present and flip. Software is the only
  121. backend today, but the WM calls the vtable rather than a fixed
  122. function, so an accelerator can replace individual operations
  123. without touching window logic.
  124. </p>
  125. <p>
  126. The software fill uses an SSE2 row store when the CPU supports it.
  127. Rows that do not fit the cache use streaming stores
  128. (<code>movntdq</code>, one <code>sfence</code> per fill), which
  129. avoids read-for-ownership traffic that makes large fills DRAM-bound
  130. on the Atom. SSE/SSE2 are never assumed: the kernel is built with
  131. <code>-mno-sse</code>, and <code>cpu_has_sse2()</code> probes CPUID,
  132. sets <code>CR4.OSFXSR/OSXMMEXCPT</code> and is re-run on every AP.
  133. </p>
  134. <p>
  135. <code>gfxbench</code> times fill, copy, cell, canvas and flush paths
  136. and reports the bytes actually copied by the presenter.
  137. </p>
  138. </section>
  139. <section id="wm">
  140. <h2>Window manager</h2>
  141. <p>
  142. The WM is a process that owns the desktop and a fixed array of eight
  143. windows. It draws a system bar with the NebOS start button, the
  144. clock, the temperature, and, on ThinkPads and Chromebooks, an
  145. AC/battery status icon at the far right (the Adwaita
  146. <code>ac-adapter</code> symbol on AC, and the <code>battery</code>
  147. outline with our own level fill inside on battery), plus
  148. draggable
  149. terminal and canvas windows with a title bar and a close
  150. icon. A normal window has no visible frame; an invisible
  151. resize band (1 px inside, 4 px outside its outer edge, with
  152. 12 px corner squares) is the resize grab area, and the active
  153. title bar uses the toolkit's highlight colour. The title is
  154. inset 8 px from the left; the close control is the Adwaita
  155. <code>window-close</code> symbol at the right edge with no red
  156. button fill, dimmed while idle and brightened on hover, and it
  157. shows the hand cursor. Every normal window also casts a 10 px
  158. soft drop shadow: <code>usurf_window_shadow()</code> darkens
  159. the ring outside the window edge with a rounded distance
  160. falloff, so the corners fade in a curve. The shadow, the edge
  161. snapping and the drag resistance can be changed in
  162. <code>bin/settings</code> (<em>Windows</em>): the WM keeps a
  163. <code>struct wm_prefs</code> in <code>wm_status</code>, applied
  164. through <code>SYS_WM_PREFS</code> and persisted in
  165. <code>/data/SETTINGS.CFG</code> (or the RAM copy
  166. <code>/share/settings.cfg</code>).
  167. Shadows are painted after the windows, back to front, so a
  168. front window's shadow falls on the windows behind it and is
  169. clipped by every window in front; popovers stay flat. Geometry
  170. damage grows by the shadow spread, while a title-bar drag
  171. repaints only the old and new ring strips around the copied
  172. window block. The desktop is a configurable flat colour
  173. (<code>wm_prefs.bg_rgb</code>, default <code>#202030</code>);
  174. <code>view</code>'s <em>Background</em> button or the
  175. Settings app's <em>Appearance</em> page stores a pre-scaled
  176. RGB565 file (<code>/data/WALLPAPR.BIN</code> on an installed
  177. board, else <code>/share/wallpaper</code>) and signals the WM
  178. through <code>SYS_WM_WALLPAPER</code>, which reloads and
  179. stretches it under the windows. The image wins over the colour
  180. while it is installed; removing it in Settings exposes the
  181. colour again. The WM has no image decoder of its own.
  182. Click-to-focus, drag-by-title-bar and close are routed through the
  183. same pointer path. To the left of the rightmost AC/battery status
  184. icon, a network status icon shows the Adwaita
  185. <code>network-wired</code> symbol for wired Ethernet, a
  186. <code>network-wireless-signal-*</code> symbol for a connected WiFi
  187. link, the <code>phone</code> symbol for RNDIS tethering, and
  188. <code>network-wired-disconnected</code> in red when no NIC is
  189. active (<code>network-wireless-offline</code> when a WiFi card is
  190. present but not associated).
  191. The whole right status cluster — temperature, date/time,
  192. network and AC/battery items plus the gaps between them — is
  193. one button with a single rounded hover pill; the empty bar
  194. between the start button and the cluster is not clickable. Both
  195. bar buttons use the same height and rounded style, stopping just
  196. above the rainbow separator, and turn selection-blue while their
  197. panel is open. It opens the anchored <code>bin/netmenu</code>
  198. quick-settings popover (a second click closes it).
  199. The popover holds the battery/clock summary, a brightness slider
  200. and six pills: Network, Power, Date &amp; Time, Appearance,
  201. Windows and About. Clicking a pill never expands the popover;
  202. it calls <code>SYS_WM_OPEN_SETTINGS(section)</code>, the WM
  203. opens or focuses the real <code>bin/settings</code> window and
  204. writes the requested section to <code>/share/settings.req</code>,
  205. and the popover closes. A running Settings window consumes that
  206. request and switches panes without restarting.
  207. </p>
  208. <p>
  209. The NebOS banner in the top-left is the start button. Clicking it
  210. opens a Windows-like start menu drawn by the WM as a flat overlay,
  211. not a window, so it floats above every canvas without consuming a
  212. window slot. The panel uses the quick-settings popover's theme: a flat
  213. <code>theme.bg</code> surface with no rim, a dim
  214. <code>Applications</code> caption as its first row, rounded hover
  215. rows and a rounded Power tile. Every self-contained GUI
  216. application in the pack gets a row with its full-colour GNOME app
  217. icon (the coloured letter tile remains only as a fallback) —
  218. Terminal, Files, Web, Gallery, Chat, Clock, Text editor, Colors,
  219. Mines, Cards, Disks, Tasks, Services, Settings and Date &amp; Time — the
  220. pointer highlights the hovered row, and an outside press dismisses
  221. the panel. Row height shrinks to keep the whole list inside the
  222. work area on short panels. The last row, Power, opens a submenu
  223. with Reboot and Power off; both run the privileged kernel command
  224. through <code>SYS_SPAWN_KCMD</code>. The bar notice and the
  225. right-aligned status never draw left of
  226. <code>WM_BAR_LEFT_END</code>.
  227. </p>
  228. <p>
  229. A macOS-like dock floats at the bottom centre. It is a WM-drawn
  230. overlay, not a work-area reservation, so maximized windows keep
  231. their full height and simply pass underneath it. The pinned row
  232. is Terminal, Files, Web, Chat, Text editor, Gallery, Clock,
  233. Colors, Mines, Cards, Disks, Tasks and Settings (after a thin
  234. separator); Services and Date &amp; Time stay in the start menu.
  235. Icons use a 48&nbsp;px base, shrinking to 24&nbsp;px on narrow
  236. screens, and the panel is a translucent rounded surface with a
  237. 1&nbsp;px rim. The pointer's horizontal distance to each base
  238. slot (fixed slots, so the target does not chase the moving
  239. layout) drives a squared falloff over about 2.5 slots and a
  240. 1.0&ndash;1.75&times; scale in 8.8 fixed point. The scaled icons
  241. are laid out again with their real widths and the row is
  242. recentred, so magnified icons push their neighbours aside as the
  243. pointer moves; per-frame easing makes the wave follow smoothly.
  244. A name pill appears above the hovered icon.
  245. </p>
  246. <p>
  247. Running apps get a small dot under their icon: the WM matches the
  248. canvas title (<code>term</code>, <code>Files</code>,
  249. <code>Browser</code>, ...), since the canvas ABI carries no
  250. executable id. Clicking a running app focuses its window;
  251. otherwise the click goes through the same launcher path as the
  252. start menu. Settings opens or focuses the Settings window. While the pointer is over an icon, the panel or its
  253. label, the WM takes <code>SYS_WM_MOUSE_CAPTURE</code>, so a click
  254. or wheel event cannot leak to the window underneath; it releases
  255. the capture on leave (or after the button is released). The dock
  256. joins <code>wm_overlays()</code>, and any window damage that
  257. intersects its rectangle repaints it, so a window drag or a
  258. canvas update cannot leave a hole in it. When a window is
  259. dragged out from under the dock (or the brightness OSD), the WM
  260. repaints it from its canvas instead of block-copying the old
  261. shadow rectangle, because those pixels belong to the overlay and
  262. would otherwise travel with the window.
  263. </p>
  264. <p>
  265. The dock is not auto-hidden and does not support reordering or
  266. badges; because it overlays the bottom of the screen, the bottom
  267. resize band of a window that reaches the screen edge is not
  268. reachable until the window is moved up.
  269. </p>
  270. <p>
  271. A popover is a chromeless canvas window created with
  272. <code>u_win_create_popover()</code> (<code>WIN_F_POPOVER</code>).
  273. The WM anchors it flush under the top bar at the right screen
  274. edge, treats it as always topmost in painting and hit-testing,
  275. and draws no chrome at all:
  276. the canvas fills the whole window rectangle, with no title bar,
  277. shadow, rim or rounded outer corners, so it reads as a flat menu
  278. panel. The kernel uses the window origin for content-relative
  279. pointer and scroll coordinates. An outside press dismisses the
  280. popover and the click then continues normally; a second click on
  281. the status cluster toggles it. The panel itself is drawn with the
  282. ngui components: a battery/AC and clock summary, a brightness
  283. slider when the panel PWM is present, and a 2-column grid of
  284. quick-settings tiles for Network, Power, Date &amp; Time,
  285. Appearance, Windows and About. A tile is a launcher, not an
  286. inline editor: it asks the WM for that Settings section (see
  287. above), so network selection, Wi-Fi join, the clock editor,
  288. wallpaper selection and the WM preference toggles all live in
  289. the titled <code>bin/settings</code> window. The popover has no
  290. resizing path left; its content is static and the window height
  291. is computed once from the presence of the brightness slider.
  292. </p>
  293. <p>
  294. The WM is the ring-3 process loaded from
  295. <code>/ramfs/bin/wm</code>; init is its only creator and there is
  296. no kernel WM fallback. The kernel window server in
  297. <span class="file">wm.c</span> owns the shadow mapping, the
  298. per-window canvases, input routing, the cursor, kexec detection and
  299. the boot-console handoff. <code>SYS_WM_ATTACH</code> admits only a
  300. process named <code>wm</code> whose parent is the current init pid;
  301. it maps the shadow, resets the window mapping state and disables
  302. the boot console. If init or the WM binary is missing the console
  303. stays visible. The WM starts the first terminal after the storage
  304. mount (<code>wm_server_boot_ready</code>); the console uses the same
  305. 8×16 face and top-left origin as the terminal, so the first frame
  306. replaces it without a size or position jump. A wedged WM is killed
  307. by the kernel watchdog and init respawns it; its terminal, bootscan
  308. window and start-menu apps die with it.
  309. </p>
  310. <figure class="figure">
  311. <svg viewBox="0 0 920 260" role="img" aria-labelledby="wm-title wm-desc">
  312. <title id="wm-title">Window anatomy</title>
  313. <desc id="wm-desc">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.</desc>
  314. <rect class="svg-box" x="70" y="22" width="780" height="200" rx="10"/>
  315. <rect class="svg-box accent" x="70" y="22" width="780" height="34" rx="10"/>
  316. <text class="svg-text" x="88" y="45">Terminal · /ramfs/bin/ls</text>
  317. <text class="svg-text" x="800" y="45">×</text>
  318. <rect class="svg-box green" x="86" y="72" width="748" height="132" rx="6"/>
  319. <text class="svg-text" x="104" y="98">content canvas · RGB565 · mapped at 0x50000000</text>
  320. <text class="svg-sub" x="104" y="120">text cells, images, widgets, or arbitrary drawing</text>
  321. </svg>
  322. <figcaption>
  323. <strong>One window, one canvas.</strong> The title bar belongs to
  324. the WM; the content is whatever the owning process draws into its
  325. mapped back buffer. The WM never reads the process's memory — it
  326. composites the front canvas on <code>PRESENT</code>.
  327. </figcaption>
  328. </figure>
  329. <ul>
  330. <li><strong>Terminal windows</strong> are canvas clients: <span class="file">ucmd_term.c</span> renders its rows into the RGB565 window canvas; keys arrive through the generic <code>SYS_KEY_POLL</code> or <code>SYS_WIN_KEY_WAIT</code>. The WM no longer has a text-cell path.</li>
  331. <li><strong>Canvas windows</strong> are generic: the app gets a back buffer, pointer position/buttons/focus and queued press/release edges with capture.</li>
  332. <li><strong>Focus and z-order</strong> are explicit; closing a window kills its session and frees its canvas.</li>
  333. </ul>
  334. <h3>Compositing cost</h3>
  335. <p>
  336. The WM keeps a front-to-back order: the focused window first, then
  337. the remaining windows in descending slot order. For each damage
  338. rectangle it fills the desktop once and walks that order, subtracting
  339. every window in front from the region still uncovered. A window is
  340. drawn only in its exposed pieces, so a fully occluded window costs
  341. nothing and the stack is never repainted back-to-front. The kernel
  342. pointer hit-test uses the same order. A focused-window drag copies
  343. its shadow block to the new position and repaints only the old
  344. strips the new rectangle does not cover, instead of compositing the
  345. window at both positions. If either rectangle is partly off-screen
  346. the shadow has no valid pixels for the hidden part, so that step
  347. repaints the window rect instead of copying desktop background into
  348. it.
  349. </p>
  350. <p>
  351. <code>SYS_WIN_PRESENT</code> carries a content-relative damage
  352. rectangle. The terminal tracks its dirty rows, so a keystroke copies
  353. and composites one 8×16 row block instead of the whole 512×512
  354. canvas. The kernel unions the rectangles between WM polls and
  355. <code>SYS_WM_INFO</code> returns that union; a present with
  356. <code>w == 0</code> or <code>h == 0</code> still means the whole
  357. canvas. The WM overwrites <code>/share/wmstats</code> every two
  358. seconds with the interval's frame count, compositing time, worst
  359. frame and pixels drawn (<code>usurf_pixels</code>), which is the
  360. on-target compositor measurement.
  361. </p>
  362. </section>
  363. <section id="canvas">
  364. <h2>Canvas ABI</h2>
  365. <p>
  366. <code>SYS_WIN_CREATE</code> maps the calling command's window canvas
  367. read/write at <code>0x50000000</code>. The process draws RGB565
  368. pixels and publishes a finished frame with
  369. <code>SYS_WIN_PRESENT</code>, optionally passing a content-relative
  370. rectangle (<code>struct wm_win_present</code>) for the changed
  371. region. Present copies that region from the back buffer into the
  372. composited front canvas with interrupts off, so a half-drawn frame
  373. can never reach the screen. Frames carry monotonic sequence
  374. counters, so the WM cannot lose one. <code>content_gen</code> comes
  375. from a global counter and is unique per window creation, so a new
  376. window that reuses a just-closed slot forces the WM to remap its
  377. front canvas instead of reusing a stale mapping. The ring-3 WM
  378. revalidates the generation after <code>u_wm_begin()</code>:
  379. the kernel refuses client self-resizes while a frame is active,
  380. so a resize between the pre-frame map refresh and the draw can no
  381. longer unmap the canvas under the WM.
  382. </p>
  383. <p>
  384. <code>SYS_WIN_CREATE</code> creates a generic canvas window.
  385. <code>struct win_create.flags</code> can request
  386. <code>WIN_F_POPOVER</code>, a chromeless overlay: the canvas fills
  387. the window and the WM supplies only the topmost placement.
  388. <code>SYS_WIN_RESIZE_SELF</code> (115) resizes the caller's canvas
  389. and <code>SYS_SCREEN_INFO</code> (116) reports the framebuffer
  390. size, so a popover can collapse or grow. Input is exposed through
  391. <code>SYS_WIN_POINTER</code>
  392. (content-relative position, button mask, focus),
  393. <code>SYS_WIN_EVENT</code>, which
  394. queues press/release edges and a capture window, and
  395. <code>SYS_WIN_SCROLL</code>, which returns wheel/touchpad scroll
  396. accumulated for the window under the pointer in pixels
  397. (<code>+dy</code> is later content). A click that starts
  398. in a window still receives its release after the pointer leaves.
  399. The ngui helper <code>ngui_scroll_wheel()</code> applies the delta
  400. to a pane when the pointer is over it. A pane's scrollbar is an
  401. overlay: an 8 px rounded pill at its right edge that stays hidden
  402. while the pointer is outside, slides in over about 100 ms on
  403. hover, and never reduces the content rectangle or reflows a row.
  404. <code>hide_bar</code> suppresses it entirely.
  405. The WM process itself is special: it maps the screen shadow at
  406. <code>0x58000000</code> and each front canvas at
  407. <code>0x59000000 + index × 4 MB</code>, which is how it composites
  408. without reading another process's memory. The 4 MB slot covers a
  409. full-screen 1920×1080 RGB565 canvas (4.15 MB) minus the chrome;
  410. the old 2 MB slot capped a full-height window at roughly 1050 px
  411. wide.
  412. <code>SYS_WM_RESIZE</code> (WM side) and
  413. <code>SYS_WIN_ACK_RESIZE</code> (client side) swap in a resized
  414. canvas; the content size is bounded by the framebuffer, so a
  415. window can grow to the edge of the screen. <code>struct
  416. wm_size</code> carries the window-origin delta (new minus old) in
  417. <code>dx</code>/<code>dy</code>: the kernel copies the old front
  418. canvas into the new one anchored by that delta before freeing it,
  419. so a left/top edge drag keeps the content in place and only the
  420. newly exposed strip starts black until the owner acknowledges and
  421. repaints. A live resize commits at most every 30 ms
  422. (<code>WM_RESIZE_COMMIT_MS</code>) or after the edge moved 8 px
  423. (<code>WM_RESIZE_MIN_STEP</code>), and the button release forces
  424. the final geometry.
  425. </p>
  426. <p>
  427. Double-clicking a title bar maximizes the window to the work area
  428. below the system bar (<code>0, WM_BAR_H, fbw, fbh - WM_BAR_H</code>);
  429. the next double-click restores the saved geometry. Dropping a
  430. title-bar drag with the pointer on the left or right screen edge
  431. (<code>WM_SNAP_EDGE</code>, 2 px) snaps the window to that half of
  432. the work area at full height, and the top edge maximizes it. The
  433. restore geometry is saved only when a window leaves the normal state,
  434. so snapping and then maximizing still restores the original size.
  435. The Settings <em>Windows</em> page can turn edge snapping off
  436. (<code>wm_prefs.snap</code>); double-click maximize stays
  437. available. Edge resistance (<code>wm_prefs.resist</code>) is a
  438. separate toggle.
  439. Dragging a maximized or snapped window restores it first, with the
  440. grab point kept at the same fraction of the title bar, and a manual
  441. resize clears the state. While a window is dragged, the screen edges
  442. and the facing edges of other windows resist it: the window stays
  443. flush until the pointer overshoots by <code>WM_RESIST</code> (24 px),
  444. which makes side-by-side placement exact. Windows can be dragged past the left, right and
  445. bottom edges; <code>WM_DRAG_VISIBLE</code> (48 px) of the title bar
  446. always stays on-screen for recovery, and the top bar is never
  447. overlapped. An invisible resize band (1 px inside, 4 px outside)
  448. runs along every edge, with 12 px corner squares: the grabbed
  449. edges follow the
  450. pointer while the opposite edges stay put, clamped to the work
  451. area. While a drag or resize is active the WM owns the pointer,
  452. so the window content does not see the held button.
  453. </p>
  454. <div class="note">
  455. <p><strong>Buttons fire on the release edge.</strong> The toolkit keeps
  456. a button <code>active</code> until <code>ui-&gt;released</code>;
  457. inferring release from the sampled button mask races the WM event
  458. queue and drops clicks.</p>
  459. </div>
  460. <p>
  461. When a process exits or crashes, the reaper releases its window
  462. mappings and the window server frees the canvas. Closing a window
  463. kills its owner. Keys go through the window key queue
  464. (<code>SYS_WIN_KEY_WAIT</code>) or the generic
  465. <code>SYS_KEY_POLL</code>; Ctrl+C still reaches the terminal.
  466. </p>
  467. </section>
  468. <section id="ngui">
  469. <h2>ngui toolkit</h2>
  470. <p>
  471. <span class="file">ngui.c</span>/<span class="file">ngui.h</span> is an
  472. immediate-mode GUI toolkit shared by the ring-3 apps. It provides
  473. clipped RGB565 primitives, buttons, menu items, text fields, the
  474. Adwaita symbolic icons (see <a href="#icons">UI icons</a>), a theme palette, layout cut helpers and scrolling
  475. panes. It is linked into <code>files</code>, <code>mines</code>,
  476. <code>solitaire</code>, <code>process</code>, <code>chat</code>,
  477. <code>settings</code>, <code>netmenu</code> and the real
  478. <code>gallery.elf</code>.
  479. </p>
  480. <ul>
  481. <li><strong>Text fields</strong> 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 <code>disabled</code> ignores pointer and keyboard input, drops the focus and paints its value dimmed in the same proportional face. A field marked <code>secret</code> is measured and painted from a <code>*</code> mask (caret, selection and click positions follow the mask, Ctrl+Left/Right jump to the ends), and Tab returns <code>NGUI_INPUT_NEXT</code> together with <code>NGUI_INPUT_CANCEL</code> so forms can move the focus. Fields hold up to 511 characters (<code>NGUI_INPUT_MAX</code> 512). The terminal and editor keep the 8×16 cell grid.</li>
  482. <li><strong>Popover components</strong> give a menu panel its surface: <code>ngui_popover_begin()</code> fills the canvas and returns the body and footer rectangles (no title bar or close button); <code>ngui_section()</code> draws a captioned section header with an optional right-aligned action button; <code>ngui_list_row()</code> is a two-line hover/selected row with optional signal bars and trailing text; <code>ngui_tile()</code> is a rounded quick-settings tile and <code>ngui_slider()</code> a draggable horizontal slider. The WM draws no outer chrome, so the app paints the whole window.</li>
  483. <li><strong>Scroll panes</strong> keep the wheel and page keys, and draw a Firefox-style overlay pill instead of a permanent track. It is hidden by default, animates in from the pane's right edge while the pointer is over the pane, brightens over the hit strip and turns accent-coloured while dragged. Presses in the strip start a drag (or jump the thumb) and do not reach the rows or buttons beneath it; content uses the full pane width in every app.</li>
  484. <li><strong>Clip stack</strong> keeps nested panes and popups inside their parents.</li>
  485. <li><strong>Layout cuts</strong> split a rectangle into rows, columns and fixed margins without a constraint solver.</li>
  486. <li><strong>No retained widget tree.</strong> Apps redraw from state every frame, which keeps the toolkit small and predictable.</li>
  487. </ul>
  488. <p>
  489. Proportional text comes from <span class="file">ufont.c</span>: a
  490. fixed-point, integer-only TrueType parser and antialiased rasterizer.
  491. The pack carries Latin-1 Arimo regular/bold/italic/bold-italic,
  492. Liberation Mono and a curated monochrome Noto Emoji subset under
  493. <code>/ramfs/fonts</code>. The browser, ngui apps and the WM chrome
  494. use real pixel sizes from 8 to 48 px; the browser maps CSS
  495. <code>font-size</code>, <code>font-weight</code>,
  496. <code>font-style</code> and <code>font-family: monospace</code> to
  497. the faces. Pages may bring their own faces with
  498. <code>@font-face</code>: TrueType/OpenType (TrueType outlines) or
  499. WOFF&nbsp;1.0, which <span class="file">ufont_woff.c</span>
  500. unwraps by inflating each table; per family the browser keeps one
  501. face per weight/style and picks the nearest one at layout. Its
  502. arena is 3&nbsp;MB instead of the default 512&nbsp;KB so web fonts
  503. fit beside the built-in set. Missing fonts fall back to the 8×16 bitmap. The browser
  504. detaches the font arena before <code>heap_reset()</code> and
  505. reattaches after <code>heap_start()</code>; terminal content and
  506. the editor keep the bitmap cells.
  507. </p>
  508. <p>
  509. UTF-8 text is available through <code>ngui_text_utf8*</code> and
  510. <code>ngui_menu_item_utf8()</code>. Per codepoint, the selected
  511. primary face is tried first, then the lazily loaded emoji face;
  512. cmap format 12 covers codepoints above the BMP. The emoji set is
  513. deliberately limited to common single-codepoint glyphs that fit the
  514. rasterizer's 256-point/16-contour limits. ZWJ sequences, flags,
  515. skin tones and color glyphs fall back to a tofu or
  516. <code>?</code>; the browser keeps its Latin-1 byte path.
  517. </p>
  518. </section>
  519. <section id="apps">
  520. <h2>Applications</h2>
  521. <div class="grid">
  522. <div class="card">
  523. <h3>files</h3>
  524. <p>File browser on the VFS: opens text in <code>edit</code>, images in <code>view</code> and HTML in <code>browser</code>. The first ngui user.</p>
  525. </div>
  526. <div class="card">
  527. <h3>process</h3>
  528. <p>Graphical task manager (the start menu's <em>Tasks</em> entry or <code>process</code>, the ngui counterpart of <code>top</code>): 60 s CPU, physical-memory and NIC-throughput graphs fed by one sample per second, and a process tree (PID, state, CPU%, memory, CPU time, name) whose rows are indented under their <code>parent_pid</code>; sibling groups sort by clicking a header. A selected row shows its pid/ppid and details and <em>End task</em> terminates the subtree after a second confirming click; kernel threads, the monitor itself and init are protected. PgUp/PgDn and the wheel scroll, Esc closes.</p>
  529. </div>
  530. <div class="card">
  531. <h3>service</h3>
  532. <p>Init's service manager client (<code>service --gui</code>, or the start menu's <em>Services</em> entry): <code>init</code>, <code>wm</code> and user services with Start/Stop/Restart/Kill, status and a live log pane. Kill asks for a second click; WM stop is refused because it is the session service.</p>
  533. </div>
  534. <div class="card">
  535. <h3>gallery</h3>
  536. <p>Live showcase of every ngui control and primitive. Ships in the pack as <code>bin/gallery.app</code>; a launcher prefers <code>/share/GALLERY</code> for development.</p>
  537. </div>
  538. <div class="card">
  539. <h3>chat</h3>
  540. <p>Cloudron Chat client: native OIDC login, channel/DM sidebar with unread badges and presence dots, a wrapped timeline with avatars, day headers, reply snippets and link-preview cards (site, title, description and an optional thumbnail; clicking one opens the link in the browser), a composer and browse/new-DM pickers. Media downloads use a warm <code>curl __serve</code> helper; message images are also decoded there (480&times;320 bounds), while avatars decode at 32&times;32 on the chat thread, so the window keeps drawing. Saved sessions resume from <code>/data</code>. The start menu's <em>Chat</em> entry launches it.</p>
  541. </div>
  542. <div class="card">
  543. <h3>disks</h3>
  544. <p>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 start menu's <em>Disks</em> entry and the <em>Disks</em> button in <code>files</code> launch it.</p>
  545. </div>
  546. <div class="card">
  547. <h3>solitaire</h3>
  548. <p>Klondike with drag-and-drop, draw-one/three, scoring, animation and pixel-art cards on the canvas service.</p>
  549. </div>
  550. <div class="card">
  551. <h3>view</h3>
  552. <p>Image viewer with fit, 1:1, zoom, pan, EXIF orientation and animated GIF playback. Its <em>Background</em> button (or the <code>b</code> key) installs the image as the desktop wallpaper, persisted in <code>/data/WALLPAPR.BIN</code> when the data volume is mounted.</p>
  553. </div>
  554. <div class="card">
  555. <h3>settings</h3>
  556. <p>The real Settings window: a titled canvas window with a left section sidebar and a scrollable right pane. Network (NIC selection, DHCP, Wi-Fi scan/join/saved networks and details), Power (P-state modes, brightness, AC/battery), Date &amp; Time (RTC editor and SNTP), Appearance (desktop colour and an image picker for the wallpaper), Windows (soft shadows, edge snapping and drag resistance through <code>SYS_WM_PREFS</code>) and About (version, display, uptime, memory, CPU temperature). It is reused by the WM; a pill click focuses it and hands over the requested section.</p>
  557. </div>
  558. <div class="card">
  559. <h3>netmenu</h3>
  560. <p>The top-bar quick-settings popover: battery/AC and clock summary, a brightness slider and six launcher pills that open the matching Settings section.</p>
  561. </div>
  562. <div class="card">
  563. <h3>clock / colors / settime</h3>
  564. <p>Small canvas demos: an analog clock, a colour test window, and the standalone Date &amp; Time editor (<code>settime</code>). The Settings app's Date &amp; Time page has the same editor, which reads and writes the CMOS RTC and can fetch UTC from an SNTP server.</p>
  565. </div>
  566. <div class="card">
  567. <h3>browser</h3>
  568. <p>HTML/CSS renderer with flex rows, auto-fit and <code>repeat(N, 1fr)</code> card grids, <code>aspect-ratio</code> 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 <code>/share/IMGSTAT</code> reports where a load spent its time. Inline and external scripts run on the vendored QuickJS engine (ES2025), and forms render and submit natively. Right-clicking the page opens a context menu that saves images, link targets or the page itself into <code>/data/DOWNLOAD</code> (or <code>/share/DOWNLOAD</code>); a toolbar download button shows live progress and the download history. The largest ring-3 application in the tree.</p>
  569. </div>
  570. </div>
  571. </section>
  572. <section id="images">
  573. <h2>Image library</h2>
  574. <p>
  575. The codecs are independent of the OS and the toolkit: each takes an
  576. input buffer plus a caller-provided <code>struct img_mem</code> arena
  577. and returns an RGB565 image with an optional 8-bit alpha plane. The
  578. browser and the chat client link the same objects and decode HTTP
  579. bodies in memory.
  580. </p>
  581. <ul>
  582. <li><strong>Formats.</strong> PNG, baseline and progressive JPEG, animated GIF, BMP, TGA, PNM, ICO/CUR and PAM. The browser also takes SVG files (<code>&lt;img src="logo.svg"&gt;</code>, CSS backgrounds): the markup is parsed into a detached subtree and drawn by its inline-SVG renderer into an RGB565 + alpha bitmap.</li>
  583. <li><strong>Drawing.</strong> <code>img_draw()</code> is a clipped, scaled RGB565 blit: box-filter downscale, bilinear upscale, alpha over a checkerboard or over the destination. A 1:1 opaque source takes a row copy, and a 1:1 alpha source blends in RGB565 without the 8-bit round trip.</li>
  584. <li><strong>Display-size decode.</strong> <code>struct img_options</code> carries optional <code>max_w</code>/<code>max_h</code> bounds. JPEG honours them with a scaled IDCT (1/2 4x4, 1/4 2x2, 1/8 1x1, Loeffler/IGJ), so a 1200x800 photo painted at 400&times;267 is decoded at roughly 600&times;400 instead of full size and then box-filtered. PNG/GIF/other codecs ignore the bounds and the caller scales them with <code>img_draw()</code>. The browser's <code>curl __serve</code> helper runs this decode for remote <code>&lt;img&gt;</code> and publishes the finished RGB565+alpha bitmap, so the UI thread only copies it.</li>
  585. <li><strong>Orientation.</strong> EXIF orientation is applied; arithmetic JPEG and CMYK are rejected.</li>
  586. <li><strong>Cost.</strong> Downscaling runs on the CPU. The browser decodes at the CSS/attribute box and caches one display-size bitmap per image, so a repaint is a 1:1 blit; the viewer caches one image; the chat client caches 480&times;320 message images and 32&times;32 circular avatars. <code>/share/IMGSTAT</code> records the browser's net, io, decode, scale, paint and reflow times.</li>
  587. </ul>
  588. </section>
  589. <section id="icons">
  590. <h2>UI icons</h2>
  591. <p>
  592. ngui's icons (<code>ngui_icon()</code>, <code>ngui_icon_button()</code>:
  593. back/forward, reload, home and downloads in the browser toolbar,
  594. folder/file/drive in <code>files</code>) and the WM's top-bar network/battery
  595. indicators are GNOME Adwaita symbolic icons
  596. (adwaita-icon-theme 51, LGPL-3 or CC-BY-SA-3.0). The unchanged
  597. <code>*-symbolic.svg</code> files live in
  598. <span class="file">assets/icons/adwaita/</span>; the host tool
  599. <span class="file">tools/mkicons.c</span> rasterizes each one with the
  600. browser's <span class="file">svg_raster.c</span> into a 16&times;16
  601. 8-bit coverage mask and writes one <code>NBICO1</code> bundle,
  602. <code>/ramfs/icons/adwaita16.icn</code> (layout in
  603. <span class="file">include/icon_abi.h</span>): a 16-byte header and
  604. 25 masks, ~6.3&nbsp;KB raw and ~1.4&nbsp;KB gzip, so both the USB
  605. and the floppy pack carry it.
  606. </p>
  607. <ul>
  608. <li><strong>Icon list.</strong> <code>ICON_LIST</code> is an X-macro of enum suffix, short name and theme file. Its order is the icon id and the bundle order (append only); it generates <code>enum ngui_icon</code> and <code>ngui_icon_name()</code>, and the gallery shows every entry. <code>uwm_lib.h</code> applies the same list to <code>enum uwm_icon</code>, so the ring-3 WM can use ids without linking ngui.</li>
  609. <li><strong>Tinting.</strong> Symbolic icons are one colour, so only coverage is stored. <code>ngui_icon()</code> blends the mask in the caller's colour (the theme text colour on buttons, <code>icon_folder</code>/<code>icon_disk</code>/<code>icon_file</code> in <code>files</code>), centred and clipped. <code>usurf_icon()</code> does the same over the WM's 16/24/32 bpp shadow. The bar's battery clears the striped <code>battery</code> mask's interior to a quarter-brightness shade and draws its level fill over the lower part, so the gauge reads at 16&nbsp;px.</li>
  610. <li><strong>Loading.</strong> Each process (every ngui app and the WM) reads the bundle once into a BSS buffer, so the browser's <code>heap_reset()</code> cannot free it. The read is capped at the ids the process was built with, so an older app still works with a newer bundle. Without the bundle the icon is left blank; there is no line-drawn fallback, because it cost ~2&nbsp;KB of code in each app.</li>
  611. <li><strong>Strict converter.</strong> mkicons reads only what symbolic icons use (<code>&lt;svg viewBox&gt;</code>, <code>&lt;g&gt;</code>, <code>&lt;path&gt;</code>, <code>&lt;rect&gt;</code>, <code>&lt;circle&gt;</code>, <code>&lt;ellipse&gt;</code>, fill, fill-rule, opacity) and fails the build on transforms, strokes, <code>style</code> or unknown elements instead of drawing a wrong icon. <code>./mkicons assets/icons/adwaita 16 out.icn -v</code> prints an ASCII preview of every mask.</li>
  612. </ul>
  613. </section>
  614. <section id="appicons">
  615. <h2>App icons &amp; dock</h2>
  616. <p>
  617. The dock and the start menu use full-colour GNOME application
  618. icons instead of the symbolic masks. The 15 icons are the
  619. upstream app SVGs from GNOME GitLab (Console, Nautilus, Epiphany,
  620. Fractal, Text Editor, Adwaita Demo, Clocks, Palette, Mines,
  621. Aisleriot, Disks, System Monitor, Tweaks, Settings and Calendar),
  622. copied unchanged into
  623. <span class="file">assets/icons/apps/</span> and rendered once to
  624. 96&times;96 PNGs. The SVGs are the licence/source form; the build
  625. never parses them, because these icons use gradients, strokes and
  626. transforms that the in-tree SVG rasterizer intentionally does not
  627. support. <span class="file">assets/icons/apps/render_appicons.sh</span>
  628. is the maintainer-only rsvg-convert step; the committed PNGs are
  629. what every normal build consumes.
  630. </p>
  631. <ul>
  632. <li><strong>Bundle.</strong> <span class="file">tools/mkappicons.c</span> decodes the PNGs with the in-tree image library, premultiplies them and writes one <code>NBAPP1</code> bundle, <code>/ramfs/icons/apps96.icn</code> (layout in <span class="file">include/app_icon_abi.h</span>): a 16-byte header then 15 images of 96&times;96 premultiplied RGB565+alpha, ~415&nbsp;KB raw and ~29&nbsp;KB in the gzip pack. Both the USB and the floppy lite pack carry it. <code>APP_ICON_LIST</code> is the append-only id and bundle order; its names are the upstream file basenames.</li>
  633. <li><strong>Loading and scaling.</strong> <code>uwm_lib.c</code> reads the bundle once into BSS (the WM has no image decoder). <code>usurf_app_icon()</code> blits one image at any size: exact copy at 96&nbsp;px, 2&times;2/4&times;4 box sampling for the 48&nbsp;px dock and 18&nbsp;px menu icons, bilinear for the magnified in-between sizes. Premultiplied source-over avoids dark fringes on the transparent edges. The same function serves the start-menu rows and the dock; without the bundle both fall back to the coloured letter tiles.</li>
  634. <li><strong>Sources and licences.</strong> <span class="file">assets/icons/apps/README</span> records the upstream project, path, pinned commit and licence per icon; the GPL, LGPL and CC-BY-SA texts are next to it. The artwork is unchanged apart from the documented raster/format conversion.</li>
  635. </ul>
  636. </section>
  637. <section id="cursors">
  638. <h2>Mouse cursors</h2>
  639. <p>
  640. The cursor set is the GNOME Adwaita theme (adwaita-cursors 51,
  641. LGPL-3 or CC-BY-SA-3.0). Its 24&nbsp;px Xcursor images are copied
  642. into <span class="file">assets/cursors/adwaita/</span> (trimmed by
  643. <span class="file">tools/xcursor_trim.py</span>), and the host tool
  644. <span class="file">tools/mkcursors.c</span> turns them into one
  645. <code>NBCUR1</code> bundle, <code>/ramfs/cursors/adwaita24.cur</code>
  646. (layout in <span class="file">include/cursor_abi.h</span>):
  647. 35 shapes named after the CSS <code>cursor</code> keywords, each
  648. with its size, hotspot, frame count and premultiplied ARGB8888
  649. frames. The animated <code>wait</code>/<code>progress</code>
  650. spinners keep every fourth of Adwaita's 60 frames (15 frames at
  651. 64&nbsp;ms, the same speed). The bundle is ~146&nbsp;KB raw,
  652. ~18&nbsp;KB gzip, and only in the full pack: the floppy lite pack
  653. has no room, so a floppy boot keeps the built-in 16&times;16 arrow.
  654. </p>
  655. <ul>
  656. <li><strong>Loading.</strong> <span class="file">cursor.c</span> copies the bundle out of the ramfs into its own pages after <code>ramfs_init()</code> and after every <code>ramfs_replace()</code> (the old pack is freed), then tells <span class="file">mouse.c</span> to re-fetch its image.</li>
  657. <li><strong>Selection.</strong> On every <code>SYS_WM_POLL</code> the window server resolves the shape: the WM's override (<code>SYS_WM_SET_CURSOR</code>: resize arrows on the resize band and while resizing, the move cross during a title-bar drag, a hand over the start button, the start menu and the status cluster), else the cursor of the window holding the pointer capture, else the content cursor (<code>SYS_WIN_SET_CURSOR</code>) of the window under the pointer, else the arrow.</li>
  658. <li><strong>Clients.</strong> ngui resets the cursor to the arrow for each redrawn frame, a hovered text field asks for the I-beam, <code>ngui_cursor_rect()</code>/<code>ngui_set_cursor()</code> serve apps, and <code>ngui_end_ex()</code> sends it when it changed. The terminal uses the I-beam; the browser maps the inherited CSS <code>cursor</code> property and, for <code>auto</code>, a hand over links, an I-beam over text fields and the progress arrow while a page loads. The gallery's Cursors section shows every shape.</li>
  659. <li><strong>Drawing.</strong> <code>cur_x</code>/<code>cur_y</code> stay the hotspot; the image's top-left is the hotspot minus the image's hotspot and may be off-screen. The software cursor saves up to 32&times;32 pixels under it and blends the premultiplied pixels over them. Intel Ironlake and Radeon copy the ARGB image into their 64&times;64 planes (Intel uses CURPOS sign bits for negative positions and follows the matching primary plane's gamma enable, because the display palette is after the plane blender and a cursor-only gamma pass brightens its antialiased edges on a VBE mode whose primary bypasses the palette; Radeon uses <code>HORZ_VERT_OFF</code> plus a shifted <code>CUR_OFFSET</code>); Cirrus reduces it to its two colours and clamps the position at 0. Animated frames advance from <code>mouse_poll_update()</code>.</li>
  660. </ul>
  661. </section>
  662. <section id="gpu">
  663. <h2>GPU quirks</h2>
  664. <ul>
  665. <li><strong>ATI Mach64.</strong> A CRTC fixup is applied after mode set. The legacy CRTC is skipped under UEFI.</li>
  666. <li><strong>NVIDIA.</strong> VBE/GOP only; the kernel never touches the legacy VGA CRTC. On the ION, the framebuffer is stolen DRAM behind a BAR3 aperture; <span class="file">nvidia.c</span> finds the stolen range and writes through a cached alias once a WC MTRR covers it. The nv50 display-engine probe is gated to the ION/nv50 chipsets so Maxwell parts (the GM206 GTX 960) are not poked through nv50 registers. On AMD family 15h the WC MTRR path uses only a free variable entry, leaves <code>MTRRdefType</code> untouched and writes a zero high mask (the LFB is below 4 GB); this is validated on the 970A-DS3P.</li>
  667. <li><strong>Intel.</strong> The Ironlake-era path supports a hardware cursor where available; the software cursor is the common fallback. Cherryview/Braswell also exposes the panel backlight (below).</li>
  668. <li><strong>UEFI.</strong> <code>vga.c</code> honours the RGBX flag and skips the VBE-only ATI CRTC reset and NVIDIA stolen-VRAM alias. <span class="file">mouse.c</span> forces the software cursor.</li>
  669. </ul>
  670. </section>
  671. <section id="backlight">
  672. <h2>Panel backlight</h2>
  673. <p>
  674. The HP Chromebook 11 G5 (<code>google/setzer</code>, Braswell)
  675. drives its internal panel PWM from the display engine, not from
  676. the Chrome EC. The board VBT (<code>data.vbt</code>, block 43)
  677. declares PWM controller 0 at 200 Hz, active high. Linux uses the
  678. same Valleyview/Cherryview registers through
  679. <code>intel_backlight</code>.
  680. </p>
  681. <ul>
  682. <li><strong>Registers.</strong> <code>BLC_PWM_CTL2</code> at GPU BAR0 + <code>0x1E1250</code> (pipe A; pipe B is <code>+0x100</code>): bit 31 enables, bit 28 is polarity. <code>BLC_PWM_CTL</code> at <code>0x1E1254</code>: period in bits 31:16, duty in bits 15:0. The Cherryview PWM clock is 19.2 MHz with a fixed /16 increment, so 200 Hz is a period of 6000.</li>
  683. <li><strong>Probe.</strong> <span class="file">backlight.c</span> matches Intel <code>8086:22b0</code>/<code>22b1</code>, maps the graphics MMIO BAR, reads both pipes, follows the one the firmware enabled and falls back to controller 0. It logs the chosen pipe, period, duty and raw registers to COM1.</li>
  684. <li><strong>Use.</strong> The <code>backlight</code> command prints the percentage and PWM state; <code>backlight up|down</code> steps by 10%, <code>backlight 0-100</code> sets a level (clamped to 5..100), and <code>backlight probe</code> dumps both pipes' registers. <code>SYS_BACKLIGHT</code> gives ring 3 the same get/set/step, which drives the quick-settings popover's brightness slider and the Settings Power page. F6/F7 (the ChromeOS EC action-row brightness keys) and the standard <code>E0 14</code>/<code>E0 15</code> brightness scancodes adjust it; the keys are consumed in <span class="file">io.c</span> and never reach a window.</li>
  685. <li><strong>Overlay.</strong> <code>SYS_WM_POLL</code> also reports the backlight percentage and a change counter. After each change the ring-3 WM (<span class="file">ucmd_wm.c</span>) draws a centered <em>Brightness</em> bubble with a sun icon, the percentage and a level bar, keeps it up for 3 s, and composits it above the windows on every pass while it is visible.</li>
  686. <li><strong>Limits.</strong> Only the Cherryview/Braswell native PWM (<code>8086:22b0</code>/<code>22b1</code>) is driven. The level is not persisted; a cold boot returns to the firmware's duty.</li>
  687. </ul>
  688. </section>
  689. <section id="sources">
  690. <h2>Source map</h2>
  691. <ul class="filelist">
  692. <li><code>kernel/vga.c</code>, <code>kernel/vga.h</code> — framebuffer and damage</li>
  693. <li><code>kernel/bootcon.c</code> — direct-to-LFB boot console</li>
  694. <li><code>kernel/vga_copy.S</code> — copy primitives</li>
  695. <li><code>kernel/blit.c</code>, <code>kernel/blit.h</code> — pixel vtable</li>
  696. <li><code>kernel/cpu.c</code> — SSE2 probing</li>
  697. <li><code>kernel/wm.c</code>, <code>kernel/wm.h</code>, <code>include/wm_abi.h</code> — kernel window server and shared ABI</li>
  698. <li><code>kernel/init.c</code>, <code>kernel/init.h</code> — starts PID 1; init is the only WM creator</li>
  699. <li><code>user/apps/wm/ucmd_wm.c</code>, <code>user/lib/uwm/uwm_lib.c</code> — ring-3 WM</li>
  700. <li><code>user/apps/netmenu/ucmd_netmenu.c</code> — top-bar quick-settings popover (summary, brightness and the Settings section pills)</li>
  701. <li><code>user/apps/settings/ucmd_settings.c</code> — titled Settings window: Network, Power, Date &amp; Time, Appearance (wallpaper picker), Windows preferences and About</li>
  702. <li><code>user/apps/settime/ucmd_settime.c</code>, <code>kernel/rtc.c</code>, <code>kernel/ntp.c</code> — Date &amp; Time editor, RTC access and SNTP sync</li>
  703. <li><code>kernel/gfx.c</code>, <code>kernel/gfx.h</code> — RGB565 window canvases</li>
  704. <li><code>kernel/sys_wm.c</code>, <code>kernel/sys_wm.h</code> — WM/window ABI</li>
  705. <li><code>user/apps/browser/browser.c</code>, <code>user/apps/browser/browser_html.c</code> — HTML/CSS renderer and inline SVG</li>
  706. <li><code>user/lib/ngui/ngui.c</code>, <code>user/lib/ngui/ngui.h</code> — toolkit</li>
  707. <li><code>user/lib/ufont/ufont.c</code>, <code>user/lib/ufont/ufont_ttf.c</code>, <code>user/lib/ufont/ufont_draw.c</code> — fixed-point TrueType text</li>
  708. <li><code>user/lib/ufont/ufont_woff.c</code> — WOFF 1.0 to sfnt (browser only)</li>
  709. <li><code>fonts/*.ttf</code> — Arimo / Liberation Mono / Noto Emoji subsets in the pack</li>
  710. <li><code>user/apps/files/ucmd_files.c</code>, <code>user/apps/process/ucmd_process.c</code>, <code>user/apps/gallery/gallery.c</code>, <code>user/apps/solitaire/ucmd_solitaire.c</code>, <code>user/apps/chat/ucmd_chat.c</code></li>
  711. <li><code>user/lib/img/img*.c</code> — image codecs</li>
  712. <li><code>kernel/ati.c</code>, <code>kernel/nvidia.c</code>, <code>kernel/intel.c</code>, <code>kernel/nv50.c</code></li>
  713. <li><code>kernel/backlight.c</code>, <code>kernel/backlight.h</code> — Cherryview/VLV panel PWM</li>
  714. <li><code>kernel/cursor.c</code>, <code>kernel/cursor.h</code>, <code>kernel/mouse.c</code>, <code>kernel/cursor_shape.h</code> — cursor bundle loader, drawing and the built-in fallback arrow; <code>kernel/cirrus.c</code>, <code>kernel/radeon.c</code> — hardware cursors</li>
  715. <li><code>include/icon_abi.h</code>, <code>tools/mkicons.c</code>, <code>assets/icons/adwaita/</code> — UI icon list, the NBICO1 bundle and the Adwaita symbolic SVGs</li>
  716. <li><code>include/app_icon_abi.h</code>, <code>tools/mkappicons.c</code>, <code>assets/icons/apps/</code> — full-colour app icon list, the NBAPP1 bundle, the upstream GNOME app SVGs and their 96 px renders</li>
  717. <li><code>include/cursor_abi.h</code>, <code>tools/mkcursors.c</code>, <code>tools/xcursor_trim.py</code>, <code>tools/cursor_test.c</code>, <code>assets/cursors/adwaita/</code> — cursor shapes, the NBCUR1 bundle and the Adwaita source images</li>
  718. </ul>
  719. </section>
  720. </main>
  721. <footer class="site-footer">
  722. <div class="inner">
  723. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  724. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  725. </div>
  726. </footer>
  727. </body>
  728. </html>