D Donkeh docs
GitHub

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.

AppRootHost.RunDesktop(args) ├── AppRootLocator.Find() ├── new DonkehWindow(app.Settings) // compiles UA + inspector CSS └── window.Run(app.CreateRoot(), app.Styles) ├── Silk.NET window / view creation ├── Load: GL, fonts, images, renderer, input ├── Render: flush → layout → paint → submit └── Close: release GPU resources, dispose window

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:

  1. Process pending pointer movement and pointer auto-scroll.
  2. Raise BeforeFrame, the earliest host hook.
  3. Advance smooth-scroll animations and sample the monotonic animation clock.
  4. Flush UILab (and the inspector's renderer), then drain inspector edits and sync audio/video elements.
  5. Read view size, framebuffer size and DPI; reserve space for a docked inspector.
  6. Full layout, animated-style repaint, or scroll-only repaint — whichever is needed.
  7. Prune interaction nodes, build overlays, submit the display lists and flush the renderer.
  8. Run batched canvas recordings, then raw GL canvas callbacks.
  9. 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.

MechanismEffect
Per-instance clip and transformClip or transform changes do not split batches; they are fragment-shader inputs.
16 texture slotsUp to sixteen textures per batch; exceeding it starts a new texture epoch while preserving paint order.
Indirect pathOne indirect command per segment, submitted with multi-draw when available, otherwise draw-indirect.
Direct fallbackSame geometry, one instanced draw per batch, for drivers without indirect support or for benchmarking.
Three stream slotsPersistent mapped instance/command buffers rotate so the CPU can prepare frame N+1 while the GPU reads N.
Unified shaderRects, rounded rects, borders, ellipses, shadows, glyphs and images share one vertex expansion path.
Window maskRounded 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:

PrimitiveWindowing responsibility
imgResolve file/data/packed sources, decode intrinsic dimensions, upload textures, apply object-fit and share the cache with CSS backgrounds.
audioOwn the SoundFlow device and one player per element; playback setup runs on a worker, while controls and events are serviced on the frame thread.
videoOwn the LibVLC player, request 640×360 RGBA frames, copy the latest frame into a dynamic texture and paint host controls.
canvasRun 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.

InteractionImplementation
Hover / activeElement flags on the node chain; style caches use an interaction version so sibling and descendant selectors refresh.
Text editingFocused text controls own caret, selection, clipboard, IME composition and keyboard navigation.
Select menusHost-painted popup list positioned from the select box; hit testing and option selection are explicit overlays.
ScrollingWheel deltas find the nearest scroll container, clamp offsets, animate smooth scroll and repaint without relayout.
Touch panWith EnableTouchScrolling, a finger drag pans the nearest container that scrolls on the gesture's dominant axis; taps replay as clicks.
Context menuA 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.
ScrollbarsHost-painted thumbs and tracks with drag interaction and pointer auto-scroll. Touch hosts get a wider grab area beside the bar.
Media controlsPlay/pause, scrubber and seek-drag handled directly by the window.
Frameless windowsapp-region: drag starts a native window drag; edge/corner hit testing provides resize handles.
CursorComputed 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

DecisionCost
One frame threadNo locking in the hot path, but layout, rendering, input and media synchronisation must stay on that thread.
OpenGL-only native pathFast and portable across desktop/Android, but requires a GL context and has no software fallback.
Approximate text shapingFallback and kerning only; no complex shaping, bidi or tab layout.
Unbounded font/image cachesNo steady-state re-decoding, but memory grows with distinct fonts and image sources.
Fixed video frame size640×360 keeps uploads predictable, at the cost of resolution for large displays.
Optional input backendRendering survives a failed input platform, but the app is non-interactive until input works.
Separate inspector treeIsolation and independent layout, but duplicated renderers, style state and overlay submission.
Desktop-oriented hostAndroid reuses the window through an attached view; browser rendering is a different DOM host entirely.

Code tour

FileRead it for…
AppRootHost.csThe generated desktop entry point and screenshot mode.
DonkehWindow.csWindow lifecycle, frame loop, layout/repaint decisions, input, scrolling, focus, devtools and screenshots.
Rendering/GLRenderer.csInstanced batching, indirect submission, GPU stream slots and shader-driven clips.
Rendering/ShaderProgram.cs / GradientCache.csShader setup and cached gradient textures.
Text/FontManager.cs / TrueTypeTextMeasurer.csFont discovery, fallback, metrics, glyph atlases and the layout adapter.
Text/ImageCache.csSource resolution, decoding, SVG rasterisation and texture caching.
Audio/AudioHost.cs / Video/VideoHost.csAsynchronous media players, state publishing and frame upload.
HtmlDefaults.csThe built-in user-agent stylesheet and tag defaults.
WindowRegion.csNative 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.