MicrosoftIris/logs/UIXrender/Rendering.md

# UIXrender.dll — rendering & message pump log

Append-only. Do not edit previous entries. Newest first.

---

## 2026-07-22 — Landed: real StbTrueType text rendering + backend-agnostic message pump

Built, AOT-published, and tested. Summary of what's now real vs. before.

**Text rendering (was: ratio-approximated measurement + `E_NOTIMPL` rasterization):**
- `Subsystems/Text/LoadedFont.cs` — a TrueType face over StbTrueTypeSharp (pure managed,
  zero GPU). Pins the font bytes (stb stores the data pointer) and exposes scaled
  advance/kerning/ascent/line-height and glyph coverage rasterization.
- `FontStore.cs` — resolves a face name to a font: runtime-registered fonts
  (`SpLoadFontResource`, now real — reads the embedded resource and registers it) →
  platform system-font discovery (Windows/Linux/macOS dirs) → first-available fallback.
  Cached, thread-safe. Returns null when nothing resolves, so callers degrade to the ratio
  metrics rather than faking.
- `TextLayout.cs` — real measurement over actual glyph advances + kerning, with the old
  ratio `TextMetrics` kept strictly as the no-font fallback. Word wrap is real either way.
- `GlyphRun.cs` — the object `hGlyphRunInfo` points at; `Rasterize(color)` composites stb
  coverage bitmaps into a straight-alpha ARGB32 buffer (BGRA-in-memory, matching
  `SurfaceFormat.ARGB32`). `TextBitmap` owns that buffer; `SpFreeDib` (repointed to
  `HandleTable.Free`) releases it.
- Wired: `SpSimpleTextMeasure` now produces a real glyph run + real geometry;
  `SpRichTextRasterize` (was `E_NOTIMPL`) composites it to a bitmap;
  `SpRichTextMeasure`/`SpRichTextGetNaturalBounds`/`SpSimpleTextMeasurePossible` use the
  real font. Outline/shadow passes and rich-text multi-run `rrcb` remain TODO.

**Message pump (was: `PeekMessage`→0, `WaitMessage`→`Thread.Sleep`, `Invoke(null)`→no-op):**
- `Subsystems/Os/MessagePump.cs` — a `ConcurrentQueue<Action>` + `ManualResetEventSlim`,
  with a lost-wakeup guard (reset only when empty, re-check after). No windowing/GPU
  dependency. `IWindowMessageSource` is the pluggable seam for a host/optional backend to
  inject OS messages during Peek.
- Wired through `EngineService`: `PeekMessage` → drain+run queued work, report
  ProcessedMessage(1)/None(0); `WaitMessage` → real bounded wait that returns early on a
  post; `Invoke(null ptr)` → `PostWake` (**the InterThreadWake fix** — a blocked
  `WaitMessage` now actually wakes); async `Invoke(real ptr)` → deferred onto the pump
  thread; `SetWindowMessageSource` exposes the seam. `SpPostDeferredImeMessage` now posts
  its dispatch onto the pump (genuinely deferred). `SpCreateNotifyWindow` now returns
  `S_OK` + a token (was `E_NOTIMPL`, which threw inside `UIForm.Initialize`'s `IFC`).

**Verified:** `dotnet build UIXrender -f net8.0` clean; whole solution builds except the
pre-existing `SimpleDebugClient`/`SimpleIrisApp` errors; NativeAOT `linux-x64` publish
succeeds with **zero trim/AOT warnings** (StbTrueTypeSharp is pure-managed, AOT-safe) and
exports **exactly 193/193** (surface unchanged). `Tests/UIXrender.Engine.Tests` extended
to **66 checks, all passing**, exercising real behaviour: proportional metrics ('WWW' >
'iii', which the ratio path could never produce), word-wrap growth, rasterized ink
(non-zero alpha pixels — glyphs actually drawn), deferred-work execution on Peek,
`InterThreadWake` unblocking a blocked `WaitMessage` in ~50ms (not the 5s timeout),
`WaitMessage` honouring its timeout, and `PeekMessage` reporting the right WorkResult.

**Still open / not done (flagged, not hidden):**
- **No on-screen compositing / real window.** By design (backend-agnostic): text
  measurement + CPU rasterization is complete, but presenting pixels to a screen needs a
  window+GPU backend, which stays out of core. `IWindowMessageSource` is the seam for a
  later optional backend package. `SpPeekMessage` therefore never returns
  `NewUserMessage(2)` (no HWND to Win32-dispatch).
- Text: DPI scaling (fontHeightPts treated as pixels for now), complex-script shaping
  (stb is Latin-oriented), and outline/shadow/underline rendering passes.
- Font family matching is filename-heuristic, not the TTF `name` table / fontconfig — a
  bold/italic style request currently resolves the family's plain face.

## 2026-07-22 — Course-correction: no GLFW/SDL; backend-agnostic pump + pluggable window seam

**What happened:** I asked the user (AskUserQuestion) how to back the message pump and
they picked "Silk.NET.Windowing real window". While setting that up the user pushed back:
*"why are you adding a dependency on GLFW? That's not backend-agnostic."* Correct.

**The constraint, stated plainly:** `Silk.NET.Windowing` is an abstraction over `IWindow`,
but there is **no backend-agnostic way to create a real OS window** — `Window.Create()`
needs a concrete platform provider (GLFW *or* SDL) registered via a backend package at
runtime, or it throws "no platform registered". So "real window" unavoidably pulls in
GLFW or SDL, which violates the backend-agnostic requirement that has governed this whole
effort (and matches FullSurface.md decision 2: UIXrender is loaded into a host that
already owns its window). Nothing windowing-related had been added to the real project
yet — only a throwaway scratchpad probe — so there was nothing to revert.

**Revised design (what's actually being built):**
- **Message pump = a backend-agnostic message queue** owned by the render-session thread.
  This is exactly and only what the render engine's loop uses the pump for, verified from
  the call sites (`UIX.RenderApi/.../Internal/RenderEngine.cs`):
  `IRenderEngine.WaitForWork` → `SpWaitMessage(timeout)` (block until work or timeout);
  `IRenderEngine.ProcessNativeEvents` → `SpPeekMessage(drain)` (drain + report a
  WorkResult); `IRenderEngine.InterThreadWake` → `SpInvoke(ctx, NULL, NULL, false)` (wake
  a blocked wait from another thread). A `ConcurrentQueue` + a wait handle implements all
  three correctly with no windowing/GPU dependency at all.
- **`ProcessNativeEvents`'s `NewUserMessage` (2) path is deliberately never taken.** That
  branch forwards a Win32 `MSG` to `RenderWindow.ForwardWindowMessage` then calls
  `Win32Api.TranslateMessage`/`DispatchMessage` — genuine Win32/HWND dispatch that only
  exists on Windows with a real window. The backend-agnostic pump has no HWND, so
  `SpPeekMessage` returns `ProcessedMessage` (1) when it ran queued work, else `0` (none),
  and leaves `out msg` default — which routes `ProcessNativeEvents` down its non-Win32
  branch (`return TestFlag(nResult, 1)`), exactly right for a windowless pump.
- **Pluggable window seam, no dependency:** a small `IWindowMessageSource` interface plus
  `EngineService.SetWindowMessageSource(...)` lets a host that owns a window (or an
  *optional, separate* Silk.NET.Windowing backend package that never ships in UIXrender
  core) inject OS window/input messages into the pump later. The pump harvests from the
  source during Peek if one is registered. This preserves the "windowing can plug in"
  intent of the user's original menu choice while keeping UIXrender core free of GLFW/SDL.

**Deferred-invoke semantics fixed at the same time:** `SpInvoke` with a **null** function
pointer is `InterThreadWake` → post a wake to the pump (this is *the* fix the user's "must
implement a pump" requirement was about: a blocked `SpWaitMessage` now actually wakes). A
**non-null** async `SpInvoke` enqueues the callback to run *on the pump thread* during the
next Peek (real "deferred invoke to the render thread" semantics), not on a random
threadpool thread as the interim wiring did; a non-null sync `SpInvoke` runs inline.

---

## 2026-07-22 — Plan: text rendering (StbTrueTypeSharp) + message pump

**Task (user):** implement rendering, specifically text rendering, and — mandatory — a
message pump so `SpPeekMessage`/`SpWaitMessage` work correctly. Backend-agnostic; pause
and ask if no suitable abstraction exists (which is why the font backend was an
AskUserQuestion — Silk.NET has no font/text abstraction, and the community option
SilkyNvg was rejected for being OpenGL-only).

**Font backend chosen (user):** StbTrueTypeSharp — pure-managed stb_truetype port,
zero-GPU, NativeAOT-clean, pairs with the StbImageSharp decoder already referenced. Gives
glyph metrics (real measurement) and CPU glyph rasterization (real `SpRichTextRasterize`).
No complex-script shaping — line/word layout is built here (the ratio-based `TextMetrics`
already did the layout; only the per-glyph *width* becomes real).

**Text subsystem shape (`Subsystems/Rendering/Text/`):**
- `FontStore` — resolves a TextStyle font-face name to a loaded font: registered fonts
  (via `SpLoadFontResource`), then platform system-font discovery (Windows `Fonts`, Linux
  `/usr/share/fonts` & friends, macOS), then a first-available fallback. Cached,
  thread-safe. When nothing resolves, callers fall back to the existing ratio metrics and
  rasterization reports `E_NOTIMPL` — honest degradation, not a fake.
- `LoadedFont` — wraps `stbtt_fontinfo` + v-metrics; scaled advance/kerning/ascent/line
  height, and glyph coverage-bitmap rasterization.
- `TextLayout` — real measurement (word wrap over real advances) and a measured run.
- `GlyphRun` — a measured run stored behind a `HandleTable` handle (this becomes the
  `hGlyphRunInfo` the managed side round-trips from measure to rasterize).

**Rasterize lifecycle (read off the managed consumers, not guessed):**
`SpRichTextRasterize` returns `phTextBitmap` + `ppvBits` + size, which
`Microsoft.Iris.Drawing.RichText.Rasterize` wraps in a `Dib`
(`UIX/.../RenderAPI/Drawing/Dib.cs`) that frees `phTextBitmap` via **`SpFreeDib`**. So the
rasterizer allocates one unmanaged ARGB buffer, returns a `HandleTable` handle as
`phTextBitmap` and the buffer pointer as `ppvBits`, and `SpFreeDib` is repointed to
`HandleTable.Free` (its previous body referenced a since-removed GDI helper and only ever
mattered on Windows; the only producer of "DIBs" in this reimplementation is this
rasterizer). `SpRichTextDestroyGlyphRunInfo` already frees the glyph-run handle.