graphics.html 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327
  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="#sources">Source map</a></li>
  62. </ul>
  63. </nav>
  64. <section id="framebuffer">
  65. <h2>Framebuffer</h2>
  66. <p>
  67. The boot path writes a <code>struct vga_boot_fb_info</code> to
  68. <code>0x600</code>: LFB base, pitch, width, height, bits per pixel
  69. and an RGBX flag for GOP's byte order. The legacy VESA stage chooses
  70. a mode with at least 16 bpp, a linear framebuffer, it must fit the
  71. card's VRAM, and width at most 1280 pixels. The UEFI loader imposes
  72. its own GOP constraints.
  73. </p>
  74. <p>
  75. <span class="file">vga.c</span> owns the visible surface. On a
  76. normal boot the render target is a RAM shadow buffer at
  77. <code>0x100000</code>, not the LFB; the 8 MB reserve leaves room for
  78. future modes. A surface carries width, height, pitch, format and a
  79. pixel-pointer, so the same drawing code can target a window layer or
  80. a canvas.
  81. </p>
  82. </section>
  83. <section id="shadow">
  84. <h2>Shadow buffer &amp; damage</h2>
  85. <p>
  86. Drawing never writes VRAM directly. Each operation records a damage
  87. rectangle; overlapping or touching rectangles merge, so a keystroke's
  88. cells collapse into one small rect while unrelated damage stays
  89. apart. The main loop calls <code>vga_present_shadow()</code> on every
  90. iteration with a byte budget of <code>VGA_FLUSH_BUDGET_BYTES</code>
  91. (1 MiB by default).
  92. </p>
  93. <ul>
  94. <li><strong>Small rects copy whole.</strong> A window repaint within the budget never tears.</li>
  95. <li><strong>Large rects are chunked.</strong> A full-screen redraw continues across loop iterations; newer damage is queued behind it.</li>
  96. <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>
  97. <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>
  98. <li><strong>Window drags flush immediately.</strong> <code>wm_drag_shadow</code> copies each drag step as one consistent frame.</li>
  99. </ul>
  100. <p>
  101. When the target is not the screen — a window layer or an app canvas —
  102. <code>vga_target_damage()</code> is a no-op. The render target
  103. override is stored in the PCB, so a preempted draw cannot leak into
  104. another process's window.
  105. </p>
  106. </section>
  107. <section id="blit">
  108. <h2>Blit backends</h2>
  109. <p>
  110. <span class="file">blit.c</span> is the pixel-operation vtable:
  111. fill, copy, blend, canvas, present and flip. Software is the only
  112. backend today, but the WM calls the vtable rather than a fixed
  113. function, so an accelerator can replace individual operations
  114. without touching window logic.
  115. </p>
  116. <p>
  117. The software fill uses an SSE2 row store when the CPU supports it.
  118. Rows that do not fit the cache use streaming stores
  119. (<code>movntdq</code>, one <code>sfence</code> per fill), which
  120. avoids read-for-ownership traffic that makes large fills DRAM-bound
  121. on the Atom. SSE/SSE2 are never assumed: the kernel is built with
  122. <code>-mno-sse</code>, and <code>cpu_has_sse2()</code> probes CPUID,
  123. sets <code>CR4.OSFXSR/OSXMMEXCPT</code> and is re-run on every AP.
  124. </p>
  125. <p>
  126. <code>gfxbench</code> times fill, copy, cell, canvas and flush paths
  127. and reports the bytes actually copied by the presenter.
  128. </p>
  129. </section>
  130. <section id="wm">
  131. <h2>Window manager</h2>
  132. <p>
  133. The WM is a process that owns the desktop and a fixed array of eight
  134. windows. It draws a system bar with the banner, launcher buttons and
  135. clock, plus draggable terminal and canvas windows with a title bar and
  136. close button. Click-to-focus, drag-by-title-bar and close are routed
  137. through the same pointer path.
  138. </p>
  139. <p>
  140. The WM is the ring-3 process loaded from
  141. <code>/ramfs/bin/wm</code>; there is no kernel WM fallback. The
  142. kernel window server in <span class="file">wm.c</span> owns the
  143. shadow mapping, the per-window canvases, input routing, the cursor,
  144. kexec detection and the boot-console handoff. It starts the first
  145. terminal after the storage mount
  146. (<code>wm_server_boot_ready</code>) and leaves the boot console
  147. visible until the WM attaches.
  148. </p>
  149. <figure class="figure">
  150. <svg viewBox="0 0 920 260" role="img" aria-labelledby="wm-title wm-desc">
  151. <title id="wm-title">Window anatomy</title>
  152. <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>
  153. <rect class="svg-box" x="70" y="22" width="780" height="200" rx="10"/>
  154. <rect class="svg-box accent" x="70" y="22" width="780" height="34" rx="10"/>
  155. <text class="svg-text" x="88" y="45">Terminal · /ramfs/bin/ls</text>
  156. <text class="svg-text" x="800" y="45">×</text>
  157. <rect class="svg-box green" x="86" y="72" width="748" height="132" rx="6"/>
  158. <text class="svg-text" x="104" y="98">content canvas · RGB565 · mapped at 0x50000000</text>
  159. <text class="svg-sub" x="104" y="120">text cells, images, widgets, or arbitrary drawing</text>
  160. </svg>
  161. <figcaption>
  162. <strong>One window, one canvas.</strong> The title bar belongs to
  163. the WM; the content is whatever the owning process draws into its
  164. mapped back buffer. The WM never reads the process's memory — it
  165. composites the front canvas on <code>PRESENT</code>.
  166. </figcaption>
  167. </figure>
  168. <ul>
  169. <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>
  170. <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>
  171. <li><strong>Focus and z-order</strong> are explicit; closing a window kills its session and frees its canvas.</li>
  172. </ul>
  173. </section>
  174. <section id="canvas">
  175. <h2>Canvas ABI</h2>
  176. <p>
  177. <code>SYS_WIN_CREATE</code> maps the calling command's window canvas
  178. read/write at <code>0x50000000</code>. The process draws RGB565
  179. pixels and publishes a finished frame with
  180. <code>SYS_WIN_PRESENT</code>. Present copies the back buffer into
  181. the composited front canvas with interrupts off, so a half-drawn
  182. frame can never reach the screen. Frames carry monotonic sequence
  183. counters, so the WM cannot lose one.
  184. </p>
  185. <p>
  186. <code>SYS_WIN_CREATE</code> creates a generic canvas window. Input is
  187. exposed through <code>SYS_WIN_POINTER</code> (content-relative
  188. position, button mask, focus) and <code>SYS_WIN_EVENT</code>, which
  189. queues press/release edges and a capture window. A click that starts
  190. in a window still receives its release after the pointer leaves.
  191. The WM process itself is special: it maps the screen shadow at
  192. <code>0x58000000</code> and each front canvas at
  193. <code>0x59000000 + index × 2 MB</code>, which is how it composites
  194. without reading another process's memory.
  195. <code>SYS_WM_RESIZE</code> (WM side) and
  196. <code>SYS_WIN_ACK_RESIZE</code> (client side) swap in a resized
  197. canvas.
  198. </p>
  199. <div class="note">
  200. <p><strong>Buttons fire on the release edge.</strong> The toolkit keeps
  201. a button <code>active</code> until <code>ui-&gt;released</code>;
  202. inferring release from the sampled button mask races the WM event
  203. queue and drops clicks.</p>
  204. </div>
  205. <p>
  206. When a process exits or crashes, the reaper releases its window
  207. mappings and the window server frees the canvas. Closing a window
  208. kills its owner. Keys go through the window key queue
  209. (<code>SYS_WIN_KEY_WAIT</code>) or the generic
  210. <code>SYS_KEY_POLL</code>; Ctrl+C still reaches the terminal.
  211. </p>
  212. </section>
  213. <section id="ngui">
  214. <h2>ngui toolkit</h2>
  215. <p>
  216. <span class="file">ngui.c</span>/<span class="file">ngui.h</span> is an
  217. immediate-mode GUI toolkit shared by the ring-3 apps. It provides
  218. clipped RGB565 primitives, buttons, menu items, text fields, nine
  219. procedural icons, a theme palette, layout cut helpers and scrolling
  220. panes. It is linked into <code>files</code>, <code>mines</code>,
  221. <code>solitaire</code> and the real <code>gallery.elf</code>.
  222. </p>
  223. <ul>
  224. <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.</li>
  225. <li><strong>Clip stack</strong> keeps nested panes and popups inside their parents.</li>
  226. <li><strong>Layout cuts</strong> split a rectangle into rows, columns and fixed margins without a constraint solver.</li>
  227. <li><strong>No retained widget tree.</strong> Apps redraw from state every frame, which keeps the toolkit small and predictable.</li>
  228. </ul>
  229. </section>
  230. <section id="apps">
  231. <h2>Applications</h2>
  232. <div class="grid">
  233. <div class="card">
  234. <h3>files</h3>
  235. <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>
  236. </div>
  237. <div class="card">
  238. <h3>gallery</h3>
  239. <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>
  240. </div>
  241. <div class="card">
  242. <h3>solitaire</h3>
  243. <p>Klondike with drag-and-drop, draw-one/three, scoring, animation and pixel-art cards on the canvas service.</p>
  244. </div>
  245. <div class="card">
  246. <h3>view</h3>
  247. <p>Image viewer with fit, 1:1, zoom, pan, EXIF orientation and animated GIF playback.</p>
  248. </div>
  249. <div class="card">
  250. <h3>clock / colors</h3>
  251. <p>Small canvas demos: a clock and a colour test window. Both are early users of the window canvas API.</p>
  252. </div>
  253. <div class="card">
  254. <h3>browser</h3>
  255. <p>HTML/CSS renderer with flex rows, auto-fit card grids, inline-block runs, basic tables and inline SVG diagrams. It decodes inline images and fetches through a headless helper; there is no JavaScript or form submission. The largest ring-3 application in the tree.</p>
  256. </div>
  257. </div>
  258. </section>
  259. <section id="images">
  260. <h2>Image library</h2>
  261. <p>
  262. The codecs are independent of the OS and the toolkit: each takes an
  263. input buffer plus a caller-provided <code>struct img_mem</code> arena
  264. and returns an RGB565 image with an optional 8-bit alpha plane. The
  265. browser links the same objects and decodes HTTP bodies in memory.
  266. </p>
  267. <ul>
  268. <li><strong>Formats.</strong> PNG, baseline and progressive JPEG, animated GIF, BMP, TGA, PNM, ICO/CUR and PAM.</li>
  269. <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.</li>
  270. <li><strong>Orientation.</strong> EXIF orientation is applied; arithmetic JPEG and CMYK are rejected.</li>
  271. <li><strong>Cost.</strong> Downscaling runs on the CPU. The viewer caches one image; the browser keeps a display bitmap but still rescales on repaint.</li>
  272. </ul>
  273. </section>
  274. <section id="gpu">
  275. <h2>GPU quirks</h2>
  276. <ul>
  277. <li><strong>ATI Mach64.</strong> A CRTC fixup is applied after mode set. The legacy CRTC is skipped under UEFI.</li>
  278. <li><strong>NVIDIA.</strong> VBE-only. The legacy VGA CRTC is never touched. 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.</li>
  279. <li><strong>Intel.</strong> The Ironlake-era path supports a hardware cursor where available; the software cursor is the common fallback.</li>
  280. <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>
  281. </ul>
  282. </section>
  283. <section id="sources">
  284. <h2>Source map</h2>
  285. <ul class="filelist">
  286. <li><code>vga.c</code>, <code>vga.h</code> — framebuffer and damage</li>
  287. <li><code>vga_copy.S</code> — copy primitives</li>
  288. <li><code>blit.c</code>, <code>blit.h</code> — pixel vtable</li>
  289. <li><code>cpu.c</code> — SSE2 probing</li>
  290. <li><code>wm.c</code>, <code>wm.h</code> — kernel window server</li>
  291. <li><code>ucmd_wm.c</code>, <code>uwm_lib.c</code> — ring-3 WM</li>
  292. <li><code>gfx.c</code>, <code>gfx.h</code> — RGB565 window canvases</li>
  293. <li><code>sys_wm.c</code>, <code>sys_wm.h</code> — WM/window ABI</li>
  294. <li><code>browser.c</code>, <code>browser_html.c</code> — HTML/CSS renderer and inline SVG</li>
  295. <li><code>ngui.c</code>, <code>ngui.h</code> — toolkit</li>
  296. <li><code>ucmd_files.c</code>, <code>gallery.c</code>, <code>ucmd_solitaire.c</code></li>
  297. <li><code>img*.c</code> — image codecs</li>
  298. <li><code>ati.c</code>, <code>nvidia.c</code>, <code>intel.c</code>, <code>nv50.c</code></li>
  299. </ul>
  300. </section>
  301. </main>
  302. <footer class="site-footer">
  303. <div class="inner">
  304. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  305. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  306. </div>
  307. </footer>
  308. </body>
  309. </html>