Windowing
Donkeh.Windowing is the native desktop host. It owns the
window loop, the OpenGL renderer, input and focus, text and font atlases,
image and media caches, scrollbars, the built-in inspector, and the desktop
entry point that turns an [AppRoot] into a running application.
It is the layer where the portable engine meets a real platform.
Entry and lifetime
Desktop apps do not write a Main. The build targets generate one
that calls AppRootHost.RunDesktop(args). That helper discovers
the app root, creates a DonkehWindow from its settings, and runs
the root component and merged stylesheet. The host also understands
--screenshot <path>, which captures frame 120 and closes
the window for deterministic smoke tests.
DonkehWindow can run either a Silk.NET desktop window or an
attached IView supplied by a platform host. That is the seam
the Android host uses: the same window, layout and renderer logic runs
against an externally owned surface instead of creating a desktop window.
The frame loop
OnRender is a fixed sequence. The ordering matters because each
stage decides whether the next one can reuse work:
- Process pending pointer movement and pointer auto-scroll.
- Raise
BeforeFrame, the earliest host hook. - Advance smooth-scroll animations and sample the monotonic animation clock.
- Flush UILab (and the inspector's renderer), then drain inspector edits and sync audio/video elements.
- Read view size, framebuffer size and DPI; reserve space for a docked inspector.
- Full layout, animated-style repaint, or scroll-only repaint — whichever is needed.
- Prune interaction nodes, build overlays, submit the display lists and flush the renderer.
- Run batched canvas recordings, then raw GL canvas callbacks.
- Update inspector sampling and handle a pending screenshot.
The window distinguishes NeedsLayout, NeedsPaint
and NeedsAnimatedPaint. A UILab version change or a resize forces
layout; a scroll forces only the display list; a transform or opacity
animation refreshes styles and paint without rebuilding geometry. CSS
animations are re-laid-out at 60 Hz while presentation can stay at 144 Hz,
which bounds CPU cost without making motion look choppy.
The OpenGL renderer
GLRenderer executes LayoutLab's instruction stream. It does not
issue one draw per element. Every paint instruction becomes a fixed-size
160-byte GpuInstance carrying its clip rectangle, affine
transform, colour, SDF parameters and texture selector. Shapes, text and
images all become instanced quads in one GPU-resident stream.
| Mechanism | Effect |
|---|---|
| Per-instance clip and transform | Clip or transform changes do not split batches; they are fragment-shader inputs. |
| 16 texture slots | Up to sixteen textures per batch; exceeding it starts a new texture epoch while preserving paint order. |
| Indirect path | One indirect command per segment, submitted with multi-draw when available, otherwise draw-indirect. |
| Direct fallback | Same geometry, one instanced draw per batch, for drivers without indirect support or for benchmarking. |
| Three stream slots | Persistent mapped instance/command buffers rotate so the CPU can prepare frame N+1 while the GPU reads N. |
| Unified shader | Rects, rounded rects, borders, ellipses, shadows, glyphs and images share one vertex expansion path. |
| Window mask | Rounded window corners are applied in the shader and mirrored into the native window region where supported. |
The renderer owns the shader program, VAOs, instance and command buffers,
fallback white texture and gradient cache. FontManager and
ImageCache are borrowed and must outlive it. Every member must
run on the GL context thread.
Text and fonts
FontManager is a compact TrueType pipeline shared by layout and
painting. It discovers system fonts, caches faces per normalised request and
builds a fallback chain per face set. Glyphs are rasterised into atlases per
rounded pixel size; metrics are cached per quarter CSS pixel. Because
TrueTypeTextMeasurer and the renderer use the same manager,
measured line widths and painted advances always agree.
Measurement adds glyph advances and letter spacing, kerns adjacent runes on the same face, and selects fallback faces per rune while keeping ascent and descent from the primary face for stable line boxes. There is no shaping, bidi reordering or tab expansion. Font and glyph caches are never evicted; they live until the GL context is disposed.
The native host accepts WOFF 1.0 and WOFF 2.0 files in addition to TTF and
OTF. Containers are expanded to sfnt bytes with the fully managed
Meziantou.Framework.Fonts decoder, so the same path works on
desktop and Android without a native FreeType build. The expanded bytes then
go through the existing StbTrueType face, metrics and atlas pipeline.
var window = new DonkehWindow(settings);
// CSS: font-family: Inter;
window.Fonts.RegisterFont("Inter", "Assets/Inter.woff2");
window.Run(root, styles);
RegisterFont takes an optional weight and italic flag and wins
over system-font discovery for the same family. A single regular registration
also serves bold and italic requests when no matching style was registered.
Advanced hosts can expose the window's Fonts manager directly;
the browser host uses the browser's own font loading instead.
Author stylesheets are not limited to embedded files. Before compiling the
cascade, the native host expands @import URLs (HTTP, file and
data), fetches each @font-face source, caches it under the temp
directory and registers the family automatically. Imports are cycle-guarded
and relative URLs resolve against the declaring sheet. This is what lets a
CDN icon font load without a manual RegisterFont call.
Two CSS details matter for icon fonts. Simple :is(a, b) selector
lists in author CSS are expanded into comma-separated selectors because the
matcher deliberately rejects logical pseudo-classes. ::before
and ::after content strings decode CSS hexadecimal escapes such
as \f0c9, so icon codepoints resolve to real glyphs.
donkeh enable-feature hot-reload adds the separate
Donkeh.HotReload package to the Debug configuration. It maps
embedded declarations back to source files and polls them from the window's
frame loop. A change calls SetStylesheet, so the complete
table, both layout engines, style caches and the inspector's sheet ranges
are rebuilt exactly as a programmatic stylesheet change would. The same
package watches component source files; after the .NET Hot Reload agent
patches a method body it calls RefreshComponents, which marks
every mounted component dirty and lets the normal diff produce the new
output without remounting or resetting hook state. Release builds never
reference the package, so the watcher is not part of the application
output.
Images, audio, video and canvas
These primitives all live at the host boundary because they need platform resources the layout engine must not know about:
| Primitive | Windowing responsibility |
|---|---|
img | Resolve file/data/packed sources, decode intrinsic dimensions, upload textures, apply object-fit and share the cache with CSS backgrounds. |
audio | Own the SoundFlow device and one player per element; playback setup runs on a worker, while controls and events are serviced on the frame thread. |
video | Own the LibVLC player, request 640×360 RGBA frames, copy the latest frame into a dynamic texture and paint host controls. |
canvas | Run OnDraw recordings inside the indirect batch and OnContext callbacks after the batch flush. |
Audio and video players are created asynchronously and pruned when their elements leave the tree. Audio publishes state only after construction finishes; video keeps a CPU frame buffer and uploads only when a new frame arrives. The same screenshot, media and canvas paths are unavailable or different on the browser host, which mirrors the DOM instead of running this GL pipeline.
Input, focus and interaction
Input is resolved against the layout tree, not the DOM. A pointer hit walks
the box tree, respects pointer-events, scroll containers and
fixed boxes, and updates a chain of hovered and active elements. Focus is a
separate chain with optional focus-visible state, caret placement and
selection.
| Interaction | Implementation |
|---|---|
| Hover / active | Element flags on the node chain; style caches use an interaction version so sibling and descendant selectors refresh. |
| Text editing | Focused text controls own caret, selection, clipboard, IME composition and keyboard navigation. |
| Select menus | Host-painted popup list positioned from the select box; hit testing and option selection are explicit overlays. |
| Scrolling | Wheel deltas find the nearest scroll container, clamp offsets, animate smooth scroll and repaint without relayout. |
| Touch pan | With EnableTouchScrolling, a finger drag pans the nearest container that scrolls on the gesture's dominant axis; taps replay as clicks. |
| Context menu | A right-button press bubbles to the nearest ancestor with an OnContextMenu handler. The event carries the deepest clicked node, the handling node and both window and element-local coordinates. |
| Scrollbars | Host-painted thumbs and tracks with drag interaction and pointer auto-scroll. Touch hosts get a wider grab area beside the bar. |
| Media controls | Play/pause, scrubber and seek-drag handled directly by the window. |
| Frameless windows | app-region: drag starts a native window drag; edge/corner hit testing provides resize handles. |
| Cursor | Computed cursor maps to a native standard cursor and is applied on the hover chain. |
Context menus are opt-in per element. Attach the handler to a container to
treat a whole list as one menu area, then read e.Target to find
the row that was actually clicked:
H("div", new Props
{
OnContextMenu = e =>
{
var clicked = e.Target; // deepest element under the pointer
var owner = e.CurrentTarget; // element that owns this handler
Console.WriteLine($"menu at {e.WindowX},{e.WindowY}");
}
}, rows);
Android and desktop share the same right-button path. Desktop dispatches the event on the right-button press. Android also treats a stationary 500 ms touch as a context-menu request; moving more than 10 px or starting a drag/pan cancels it, and the release click is suppressed after it fires.
Scrolling is especially important to the frame budget. Box geometry stays in unscrolled coordinates; scroll offsets are clamped per container and applied as paint translations. A wheel event or scrollbar drag therefore rebuilds the display list and hit-test offsets, but never the box tree or resolved styles.
The inspector
The built-in inspector runs as a separate UILab tree with its own
Renderer, LayoutEngine, renderer context and
display list. When docked, it reduces the app viewport so the page reflows
instead of being covered. In window mode it runs in its own native window and
edits are queued back to the frame thread before layout.
Inspector work is throttled. The Performance tab samples roughly four times per second rather than every frame; the Elements tab refreshes on UILab version changes; selection scrolling is requested explicitly. Disabling devtools removes its key handling and skips its stylesheet, layout engine and overlay work entirely.
DPI, sizing and window shape
The window works in CSS pixels and maps from the framebuffer using the
reported ratio, or an explicit DpiScale on platforms that report
physical surfaces. Pointer coordinates are divided by the same ratio, so hits
land on the CSS pixel layout used. Min/max client sizes are enforced by
nudging the native window back into range; resize events collapse into one
layout per rendered frame.
Frameless windows use the CSS app-region and host-provided
resize handles. A configured corner radius is applied both in the shader and,
where the platform supports it, to the native window region. The clear colour
is skipped for rounded windows so the corners can show the desktop while the
root element paints the visible surface.
Trade-offs and sharp edges
| Decision | Cost |
|---|---|
| One frame thread | No locking in the hot path, but layout, rendering, input and media synchronisation must stay on that thread. |
| OpenGL-only native path | Fast and portable across desktop/Android, but requires a GL context and has no software fallback. |
| Approximate text shaping | Fallback and kerning only; no complex shaping, bidi or tab layout. |
| Unbounded font/image caches | No steady-state re-decoding, but memory grows with distinct fonts and image sources. |
| Fixed video frame size | 640×360 keeps uploads predictable, at the cost of resolution for large displays. |
| Optional input backend | Rendering survives a failed input platform, but the app is non-interactive until input works. |
| Separate inspector tree | Isolation and independent layout, but duplicated renderers, style state and overlay submission. |
| Desktop-oriented host | Android reuses the window through an attached view; browser rendering is a different DOM host entirely. |
Code tour
| File | Read it for… |
|---|---|
AppRootHost.cs | The generated desktop entry point and screenshot mode. |
DonkehWindow.cs | Window lifecycle, frame loop, layout/repaint decisions, input, scrolling, focus, devtools and screenshots. |
Rendering/GLRenderer.cs | Instanced batching, indirect submission, GPU stream slots and shader-driven clips. |
Rendering/ShaderProgram.cs / GradientCache.cs | Shader setup and cached gradient textures. |
Text/FontManager.cs / TrueTypeTextMeasurer.cs | Font discovery, fallback, metrics, glyph atlases and the layout adapter. |
Text/ImageCache.cs | Source resolution, decoding, SVG rasterisation and texture caching. |
Audio/AudioHost.cs / Video/VideoHost.cs | Asynchronous media players, state publishing and frame upload. |
HtmlDefaults.cs | The built-in user-agent stylesheet and tag defaults. |
WindowRegion.cs | Native rounded-window regions. |
The mental model: Windowing is the platform adapter between a portable frame description and a real GL surface. LayoutLab decides what to paint; Windowing decides where the pixels go, what the pointer is over, which textures exist, and how much of the previous frame can be reused.