graphics.html 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506
  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="#gpu">GPU quirks</a></li>
  61. <li><a href="#backlight">Panel backlight</a></li>
  62. <li><a href="#sources">Source map</a></li>
  63. </ul>
  64. </nav>
  65. <section id="framebuffer">
  66. <h2>Framebuffer</h2>
  67. <p>
  68. The boot path writes a <code>struct vga_boot_fb_info</code> to
  69. <code>0x600</code>: LFB base, pitch, width, height, bits per pixel
  70. and an RGBX flag for GOP's byte order. The legacy VESA stage chooses
  71. a mode with at least 16 bpp, a linear framebuffer, it must fit the
  72. card's VRAM, at most 1920 pixels wide, and its shadow (pitch ×
  73. height) must fit the 8 MB reserve. 1920×1080 is the practical
  74. maximum: its 8.29 MB shadow fits, and its 4.15 MB RGB565 canvas
  75. fits the 4 MB window slot; 1920×1200 is rejected because its
  76. canvas would need 4.6 MB. The UEFI loader applies the same GOP
  77. limits.
  78. </p>
  79. <p>
  80. <span class="file">vga.c</span> owns the visible surface. On a
  81. normal boot the render target is a RAM shadow buffer at
  82. <code>0x100000</code>, not the LFB; the 8 MB reserve holds a
  83. 1920×1080×32 frame (8.29 MB) with about 94 KB to spare. A surface
  84. carries width, height, pitch, format and a
  85. pixel-pointer, so the same drawing code can target a window layer or
  86. a canvas.
  87. </p>
  88. </section>
  89. <section id="shadow">
  90. <h2>Shadow buffer &amp; damage</h2>
  91. <p>
  92. Drawing never writes VRAM directly. Each operation records a damage
  93. rectangle; overlapping or touching rectangles merge, so a keystroke's
  94. cells collapse into one small rect while unrelated damage stays
  95. apart. The main loop calls <code>vga_present_shadow()</code> on every
  96. iteration with a byte budget of <code>VGA_FLUSH_BUDGET_BYTES</code>
  97. (1 MiB by default).
  98. </p>
  99. <ul>
  100. <li><strong>Small rects copy whole.</strong> A window repaint within the budget never tears.</li>
  101. <li><strong>Large rects are chunked.</strong> A full-screen redraw continues across loop iterations; newer damage is queued behind it.</li>
  102. <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>
  103. <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>
  104. <li><strong>Window drags flush immediately.</strong> <code>wm_drag_shadow</code> copies each drag step as one consistent frame.</li>
  105. </ul>
  106. <p>
  107. When the target is not the screen — a window layer or an app canvas —
  108. <code>vga_target_damage()</code> is a no-op. The render target
  109. override is stored in the PCB, so a preempted draw cannot leak into
  110. another process's window.
  111. </p>
  112. </section>
  113. <section id="blit">
  114. <h2>Blit backends</h2>
  115. <p>
  116. <span class="file">blit.c</span> is the pixel-operation vtable:
  117. fill, copy, blend, canvas, present and flip. Software is the only
  118. backend today, but the WM calls the vtable rather than a fixed
  119. function, so an accelerator can replace individual operations
  120. without touching window logic.
  121. </p>
  122. <p>
  123. The software fill uses an SSE2 row store when the CPU supports it.
  124. Rows that do not fit the cache use streaming stores
  125. (<code>movntdq</code>, one <code>sfence</code> per fill), which
  126. avoids read-for-ownership traffic that makes large fills DRAM-bound
  127. on the Atom. SSE/SSE2 are never assumed: the kernel is built with
  128. <code>-mno-sse</code>, and <code>cpu_has_sse2()</code> probes CPUID,
  129. sets <code>CR4.OSFXSR/OSXMMEXCPT</code> and is re-run on every AP.
  130. </p>
  131. <p>
  132. <code>gfxbench</code> times fill, copy, cell, canvas and flush paths
  133. and reports the bytes actually copied by the presenter.
  134. </p>
  135. </section>
  136. <section id="wm">
  137. <h2>Window manager</h2>
  138. <p>
  139. The WM is a process that owns the desktop and a fixed array of eight
  140. windows. It draws a system bar with the banner, launcher buttons,
  141. clock, the temperature, and, on ThinkPads and Chromebooks, an
  142. AC/battery status icon at the far right (a plug on AC, a
  143. level-filled battery on battery, with a percentage tooltip below
  144. the bar on hover, painted above the windows), plus draggable
  145. terminal and canvas windows with a title bar and close button.
  146. Click-to-focus, drag-by-title-bar and close are routed through the
  147. same pointer path. To the left of the rightmost AC/battery status
  148. icon, a network status icon shows a
  149. cable for wired Ethernet, signal bars for a connected WiFi link, a
  150. USB mark for RNDIS tethering, or a red X when no link is up.
  151. The whole right status area — temperature, date/time, network
  152. and AC/battery items plus the gaps between them — is one button:
  153. it opens the anchored <code>bin/netmenu</code> control panel (a
  154. second click closes it).
  155. It opens collapsed: the battery/clock summary and Quick settings
  156. pills are visible, while the network, power-mode and date/time
  157. settings stay hidden until their pill is clicked. Present NICs
  158. can then be selected (DHCP runs), and scanned WiFi networks can be
  159. joined, asking for the WPA2 passphrase first when the AP requires
  160. one.
  161. </p>
  162. <p>
  163. A popover is a chromeless canvas window created with
  164. <code>u_win_create_popover()</code> (<code>WIN_F_POPOVER</code>).
  165. The WM anchors it flush under the top bar at the right screen
  166. edge, treats it as always topmost in painting and hit-testing,
  167. and draws no chrome at all:
  168. the canvas fills the whole window rectangle, with no title bar,
  169. shadow, rim or rounded outer corners, so it reads as a flat menu
  170. panel. The kernel uses the window origin for content-relative
  171. pointer and scroll coordinates. An outside press dismisses the
  172. popover and the click then continues normally; a second click on
  173. any status target toggles it. The panel itself is drawn with the
  174. ngui components: a battery/AC and clock summary, a brightness
  175. slider when the panel PWM is present, and Quick settings tiles for
  176. Network, the CPU power mode (<code>SYS_CPUFREQ</code>) and Date
  177. &amp; Time. Clicking a tile expands that section in place — the
  178. network devices/Wi-Fi/connection lists, the three power modes, or
  179. an inline date/time editor with Set, Now and Sync NTP (no separate
  180. window). <code>SYS_WIN_RESIZE_SELF</code> grows or shrinks the
  181. popover to the section, clamped to <code>SYS_SCREEN_INFO</code>'s
  182. framebuffer; the section scrolls with the wheel, touchpad or page
  183. keys when it is taller than the screen, without drawing a
  184. scrollbar.
  185. </p>
  186. <p>
  187. The WM is the ring-3 process loaded from
  188. <code>/ramfs/bin/wm</code>; there is no kernel WM fallback. The
  189. kernel window server in <span class="file">wm.c</span> owns the
  190. shadow mapping, the per-window canvases, input routing, the cursor,
  191. kexec detection and the boot-console handoff. It starts the first
  192. terminal after the storage mount
  193. (<code>wm_server_boot_ready</code>) and leaves the boot console
  194. visible until the WM attaches. The console uses the same 8×16 face
  195. and top-left origin as the terminal, so the first frame replaces it
  196. without a size or position jump.
  197. </p>
  198. <figure class="figure">
  199. <svg viewBox="0 0 920 260" role="img" aria-labelledby="wm-title wm-desc">
  200. <title id="wm-title">Window anatomy</title>
  201. <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>
  202. <rect class="svg-box" x="70" y="22" width="780" height="200" rx="10"/>
  203. <rect class="svg-box accent" x="70" y="22" width="780" height="34" rx="10"/>
  204. <text class="svg-text" x="88" y="45">Terminal · /ramfs/bin/ls</text>
  205. <text class="svg-text" x="800" y="45">×</text>
  206. <rect class="svg-box green" x="86" y="72" width="748" height="132" rx="6"/>
  207. <text class="svg-text" x="104" y="98">content canvas · RGB565 · mapped at 0x50000000</text>
  208. <text class="svg-sub" x="104" y="120">text cells, images, widgets, or arbitrary drawing</text>
  209. </svg>
  210. <figcaption>
  211. <strong>One window, one canvas.</strong> The title bar belongs to
  212. the WM; the content is whatever the owning process draws into its
  213. mapped back buffer. The WM never reads the process's memory — it
  214. composites the front canvas on <code>PRESENT</code>.
  215. </figcaption>
  216. </figure>
  217. <ul>
  218. <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>
  219. <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>
  220. <li><strong>Focus and z-order</strong> are explicit; closing a window kills its session and frees its canvas.</li>
  221. </ul>
  222. <h3>Compositing cost</h3>
  223. <p>
  224. The WM keeps a front-to-back order: the focused window first, then
  225. the remaining windows in descending slot order. For each damage
  226. rectangle it fills the desktop once and walks that order, subtracting
  227. every window in front from the region still uncovered. A window is
  228. drawn only in its exposed pieces, so a fully occluded window costs
  229. nothing and the stack is never repainted back-to-front. The kernel
  230. pointer hit-test uses the same order. A focused-window drag copies
  231. its shadow block to the new position and repaints only the old
  232. strips the new rectangle does not cover, instead of compositing the
  233. window at both positions. If either rectangle is partly off-screen
  234. the shadow has no valid pixels for the hidden part, so that step
  235. repaints the window rect instead of copying desktop background into
  236. it.
  237. </p>
  238. <p>
  239. <code>SYS_WIN_PRESENT</code> carries a content-relative damage
  240. rectangle. The terminal tracks its dirty rows, so a keystroke copies
  241. and composites one 8×16 row block instead of the whole 512×512
  242. canvas. The kernel unions the rectangles between WM polls and
  243. <code>SYS_WM_INFO</code> returns that union; a present with
  244. <code>w == 0</code> or <code>h == 0</code> still means the whole
  245. canvas. The WM overwrites <code>/share/wmstats</code> every two
  246. seconds with the interval's frame count, compositing time, worst
  247. frame and pixels drawn (<code>usurf_pixels</code>), which is the
  248. on-target compositor measurement.
  249. </p>
  250. </section>
  251. <section id="canvas">
  252. <h2>Canvas ABI</h2>
  253. <p>
  254. <code>SYS_WIN_CREATE</code> maps the calling command's window canvas
  255. read/write at <code>0x50000000</code>. The process draws RGB565
  256. pixels and publishes a finished frame with
  257. <code>SYS_WIN_PRESENT</code>, optionally passing a content-relative
  258. rectangle (<code>struct wm_win_present</code>) for the changed
  259. region. Present copies that region from the back buffer into the
  260. composited front canvas with interrupts off, so a half-drawn frame
  261. can never reach the screen. Frames carry monotonic sequence
  262. counters, so the WM cannot lose one. <code>content_gen</code> comes
  263. from a global counter and is unique per window creation, so a new
  264. window that reuses a just-closed slot forces the WM to remap its
  265. front canvas instead of reusing a stale mapping.
  266. </p>
  267. <p>
  268. <code>SYS_WIN_CREATE</code> creates a generic canvas window.
  269. <code>struct win_create.flags</code> can request
  270. <code>WIN_F_POPOVER</code>, a chromeless overlay: the canvas fills
  271. the window and the WM supplies only the topmost placement.
  272. <code>SYS_WIN_RESIZE_SELF</code> (115) resizes the caller's canvas
  273. and <code>SYS_SCREEN_INFO</code> (116) reports the framebuffer
  274. size, so a popover can collapse or grow. Input is exposed through
  275. <code>SYS_WIN_POINTER</code>
  276. (content-relative position, button mask, focus),
  277. <code>SYS_WIN_EVENT</code>, which
  278. queues press/release edges and a capture window, and
  279. <code>SYS_WIN_SCROLL</code>, which returns wheel/touchpad scroll
  280. accumulated for the window under the pointer in pixels
  281. (<code>+dy</code> is later content). A click that starts
  282. in a window still receives its release after the pointer leaves.
  283. The ngui helper <code>ngui_scroll_wheel()</code> applies the delta
  284. to a pane when the pointer is over it; a pane can set
  285. <code>hide_bar</code> to keep wheel/key scrolling without a visible
  286. scrollbar (the control panel does this so every card uses the full
  287. width).
  288. The WM process itself is special: it maps the screen shadow at
  289. <code>0x58000000</code> and each front canvas at
  290. <code>0x59000000 + index × 4 MB</code>, which is how it composites
  291. without reading another process's memory. The 4 MB slot covers a
  292. full-screen 1920×1080 RGB565 canvas (4.15 MB) minus the chrome;
  293. the old 2 MB slot capped a full-height window at roughly 1050 px
  294. wide.
  295. <code>SYS_WM_RESIZE</code> (WM side) and
  296. <code>SYS_WIN_ACK_RESIZE</code> (client side) swap in a resized
  297. canvas; the content size is bounded by the framebuffer, so a
  298. window can grow to the edge of the screen.
  299. </p>
  300. <p>
  301. Double-clicking a title bar maximizes the window to the work area
  302. below the system bar (<code>0, WM_BAR_H, fbw, fbh - WM_BAR_H</code>);
  303. the next double-click restores the saved geometry. Dropping a
  304. title-bar drag with the pointer on the left or right screen edge
  305. (<code>WM_SNAP_EDGE</code>, 2 px) snaps the window to that half of
  306. the work area at full height, and the top edge maximizes it. The
  307. restore geometry is saved only when a window leaves the normal state,
  308. so snapping and then maximizing still restores the original size.
  309. Dragging a maximized or snapped window restores it first, with the
  310. grab point kept at the same fraction of the title bar, and a manual
  311. resize clears the state. While a window is dragged, the screen edges
  312. and the facing edges of other windows resist it: the window stays
  313. flush until the pointer overshoots by <code>WM_RESIST</code> (24 px),
  314. which makes side-by-side placement exact. Windows can be dragged past the left, right and
  315. bottom edges; <code>WM_DRAG_VISIBLE</code> (48 px) of the title bar
  316. always stays on-screen for recovery, and the top bar is never
  317. overlapped. The resize grip is clamped to the full work area and
  318. snaps to it when dragged into the screen corner.
  319. </p>
  320. <div class="note">
  321. <p><strong>Buttons fire on the release edge.</strong> The toolkit keeps
  322. a button <code>active</code> until <code>ui-&gt;released</code>;
  323. inferring release from the sampled button mask races the WM event
  324. queue and drops clicks.</p>
  325. </div>
  326. <p>
  327. When a process exits or crashes, the reaper releases its window
  328. mappings and the window server frees the canvas. Closing a window
  329. kills its owner. Keys go through the window key queue
  330. (<code>SYS_WIN_KEY_WAIT</code>) or the generic
  331. <code>SYS_KEY_POLL</code>; Ctrl+C still reaches the terminal.
  332. </p>
  333. </section>
  334. <section id="ngui">
  335. <h2>ngui toolkit</h2>
  336. <p>
  337. <span class="file">ngui.c</span>/<span class="file">ngui.h</span> is an
  338. immediate-mode GUI toolkit shared by the ring-3 apps. It provides
  339. clipped RGB565 primitives, buttons, menu items, text fields, nine
  340. procedural icons, a theme palette, layout cut helpers and scrolling
  341. panes. It is linked into <code>files</code>, <code>mines</code>,
  342. <code>solitaire</code>, <code>chat</code>, the control panel and
  343. the real <code>gallery.elf</code>.
  344. </p>
  345. <ul>
  346. <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>
  347. <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>
  348. <li><strong>Clip stack</strong> keeps nested panes and popups inside their parents.</li>
  349. <li><strong>Layout cuts</strong> split a rectangle into rows, columns and fixed margins without a constraint solver.</li>
  350. <li><strong>No retained widget tree.</strong> Apps redraw from state every frame, which keeps the toolkit small and predictable.</li>
  351. </ul>
  352. <p>
  353. Proportional text comes from <span class="file">ufont.c</span>: a
  354. fixed-point, integer-only TrueType parser and antialiased rasterizer.
  355. The pack carries Latin-1 Arimo regular/bold/italic/bold-italic,
  356. Liberation Mono and a curated monochrome Noto Emoji subset under
  357. <code>/ramfs/fonts</code>. The browser, ngui apps and the WM chrome
  358. use real pixel sizes from 8 to 48 px; the browser maps CSS
  359. <code>font-size</code>, <code>font-weight</code>,
  360. <code>font-style</code> and <code>font-family: monospace</code> to
  361. the faces. Missing fonts fall back to the 8×16 bitmap. The browser
  362. detaches the font arena before <code>heap_reset()</code> and
  363. reattaches after <code>heap_start()</code>; terminal content and
  364. the editor keep the bitmap cells.
  365. </p>
  366. <p>
  367. UTF-8 text is available through <code>ngui_text_utf8*</code> and
  368. <code>ngui_menu_item_utf8()</code>. Per codepoint, the selected
  369. primary face is tried first, then the lazily loaded emoji face;
  370. cmap format 12 covers codepoints above the BMP. The emoji set is
  371. deliberately limited to common single-codepoint glyphs that fit the
  372. rasterizer's 256-point/16-contour limits. ZWJ sequences, flags,
  373. skin tones and color glyphs fall back to a tofu or
  374. <code>?</code>; the browser keeps its Latin-1 byte path.
  375. </p>
  376. </section>
  377. <section id="apps">
  378. <h2>Applications</h2>
  379. <div class="grid">
  380. <div class="card">
  381. <h3>files</h3>
  382. <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>
  383. </div>
  384. <div class="card">
  385. <h3>gallery</h3>
  386. <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>
  387. </div>
  388. <div class="card">
  389. <h3>chat</h3>
  390. <p>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 <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 top-bar <em>Chat</em> button launches it.</p>
  391. </div>
  392. <div class="card">
  393. <h3>solitaire</h3>
  394. <p>Klondike with drag-and-drop, draw-one/three, scoring, animation and pixel-art cards on the canvas service.</p>
  395. </div>
  396. <div class="card">
  397. <h3>view</h3>
  398. <p>Image viewer with fit, 1:1, zoom, pan, EXIF orientation and animated GIF playback.</p>
  399. </div>
  400. <div class="card">
  401. <h3>clock / colors / settime</h3>
  402. <p>Small canvas demos: an analog clock, a colour test window, and the standalone Date &amp; Time editor (<code>settime</code>). The control panel's Date &amp; Time tile reveals its own inline editor, which reads and writes the CMOS RTC and can fetch UTC from an SNTP server.</p>
  403. </div>
  404. <div class="card">
  405. <h3>browser</h3>
  406. <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. The largest ring-3 application in the tree.</p>
  407. </div>
  408. </div>
  409. </section>
  410. <section id="images">
  411. <h2>Image library</h2>
  412. <p>
  413. The codecs are independent of the OS and the toolkit: each takes an
  414. input buffer plus a caller-provided <code>struct img_mem</code> arena
  415. and returns an RGB565 image with an optional 8-bit alpha plane. The
  416. browser and the chat client link the same objects and decode HTTP
  417. bodies in memory.
  418. </p>
  419. <ul>
  420. <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>
  421. <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>
  422. <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>
  423. <li><strong>Orientation.</strong> EXIF orientation is applied; arithmetic JPEG and CMYK are rejected.</li>
  424. <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>
  425. </ul>
  426. </section>
  427. <section id="gpu">
  428. <h2>GPU quirks</h2>
  429. <ul>
  430. <li><strong>ATI Mach64.</strong> A CRTC fixup is applied after mode set. The legacy CRTC is skipped under UEFI.</li>
  431. <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>
  432. <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>
  433. <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>
  434. </ul>
  435. </section>
  436. <section id="backlight">
  437. <h2>Panel backlight</h2>
  438. <p>
  439. The HP Chromebook 11 G5 (<code>google/setzer</code>, Braswell)
  440. drives its internal panel PWM from the display engine, not from
  441. the Chrome EC. The board VBT (<code>data.vbt</code>, block 43)
  442. declares PWM controller 0 at 200 Hz, active high. Linux uses the
  443. same Valleyview/Cherryview registers through
  444. <code>intel_backlight</code>.
  445. </p>
  446. <ul>
  447. <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>
  448. <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>
  449. <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 control panel's brightness slider. 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>
  450. <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>
  451. <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>
  452. </ul>
  453. </section>
  454. <section id="sources">
  455. <h2>Source map</h2>
  456. <ul class="filelist">
  457. <li><code>kernel/vga.c</code>, <code>kernel/vga.h</code> — framebuffer and damage</li>
  458. <li><code>kernel/bootcon.c</code> — direct-to-LFB boot console</li>
  459. <li><code>kernel/vga_copy.S</code> — copy primitives</li>
  460. <li><code>kernel/blit.c</code>, <code>kernel/blit.h</code> — pixel vtable</li>
  461. <li><code>kernel/cpu.c</code> — SSE2 probing</li>
  462. <li><code>kernel/wm.c</code>, <code>kernel/wm.h</code>, <code>include/wm_abi.h</code> — kernel window server and shared ABI</li>
  463. <li><code>user/apps/wm/ucmd_wm.c</code>, <code>user/lib/uwm/uwm_lib.c</code> — ring-3 WM</li>
  464. <li><code>user/apps/netmenu/ucmd_netmenu.c</code> — top-bar control panel (network/WiFi, brightness, power mode, Date &amp; Time)</li>
  465. <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>
  466. <li><code>kernel/gfx.c</code>, <code>kernel/gfx.h</code> — RGB565 window canvases</li>
  467. <li><code>kernel/sys_wm.c</code>, <code>kernel/sys_wm.h</code> — WM/window ABI</li>
  468. <li><code>user/apps/browser/browser.c</code>, <code>user/apps/browser/browser_html.c</code> — HTML/CSS renderer and inline SVG</li>
  469. <li><code>user/lib/ngui/ngui.c</code>, <code>user/lib/ngui/ngui.h</code> — toolkit</li>
  470. <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>
  471. <li><code>fonts/*.ttf</code> — Arimo / Liberation Mono / Noto Emoji subsets in the pack</li>
  472. <li><code>user/apps/files/ucmd_files.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>
  473. <li><code>user/lib/img/img*.c</code> — image codecs</li>
  474. <li><code>kernel/ati.c</code>, <code>kernel/nvidia.c</code>, <code>kernel/intel.c</code>, <code>kernel/nv50.c</code></li>
  475. <li><code>kernel/backlight.c</code>, <code>kernel/backlight.h</code> — Cherryview/VLV panel PWM</li>
  476. </ul>
  477. </section>
  478. </main>
  479. <footer class="site-footer">
  480. <div class="inner">
  481. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  482. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  483. </div>
  484. </footer>
  485. </body>
  486. </html>