Cerneala UI
Documentation GitHub
NATIVE WINDOWS · MONOGAME HOST · IDRAWINGBACKEND

Compiled authoring · retained runtime · C#

Cerneala

A retained UI framework for native windows and game hosts.

Author views in .crn and partial C#. Run typed properties, aspects, templates, routed input, incremental layout, motion, and cached drawing on one deterministic frame contract.

View on GitHub Read the Docs
runtime://MainWindow Committed
Cerneala Playground Button
SHOWCASES Controls Layout Input Motion Markup
Templated control

Retained by default.

State settles once. Drawing commands stay cached until something actually changes.

Run command
LayoutClean
Render cacheReused
Hit routeCurrent
› relay drained · root committed · command stream ready · backend-neutral draw

Framework surface

The whole UI stack, from source file to submitted frame.

Cerneala owns the load-bearing layers: compiled authoring and bindings, retained state, bounded cross-thread marshaling, layout and input, motion, dirty scheduling, cached drawing, native hosting, and diagnostics. Controls are the visible part, not the entire damn framework.

Author .crn + generated bindings + partial C#
Model Tree + properties + aspects
Frame Relay + input + layout + motion
Output Caches + commands + backend
01 Authoring

Compiled Markup

.crn additional files compile into partial windows and controls with named elements, event hooks, resources, aspects, templates, logical conditions, and typed OneWay/TwoWay data bindings. Behavior stays in matching C#.

.crn · UiMarkupGenerator · $DataContext · partial classes
02 State

Typed Properties & Binding

UiProperty<T> carries defaults, validation, coercion, precedence, inheritance, and invalidation metadata. Generated paths, Binding<T>, and observable values connect model changes without runtime reflection in the hot path.

UiProperty<T> · BindingOperations · INotifyPropertyChanged
03 Style

Aspects, Resources & Templates

Aspect rules cascade through defaults, states, and variants while named resources supply brushes, fonts, tokens, values, and templates. Reactive conditions update styling without rebuilding the tree.

Aspect · $resources · control/content templates
04 Controls

Controls & Text Editing

Window, Button, RepeatButton, TextBox, ListBox, ScrollViewer, ComboBox, TabControl, Slider, and the supporting content/items primitives share templates, focus, selection, commands, and text infrastructure.

Window · RepeatButton · ItemsControl · TextBox · PasswordBox
05 Layout

Layout & Virtualization

Measure and arrange run through Grid, StackPanel, Canvas, scrolling, and virtualized stacks, with layout boundaries, rounding, and incremental parent escalation built into the frame scheduler.

LayoutManager · ScrollViewer · VirtualizingStackPanel
06 Input

Routed Input & Semantics

Pointer, keyboard, and text feed hit testing, capture, focus, commands, navigation, and tunneled/bubbled events. Touch, stylus, manipulation, and drag surfaces remain platform-gated prototypes; a semantics tree exists while native accessibility adapters remain later work.

ElementInputBridge · RoutedEvent · SemanticsTree
07 Motion

Frame-Coordinated Motion

Tweens, springs, decay, keyframes, layout transitions, presence, and gesture motion share the host clock. Hooks sample around layout and render, with reduced-motion policy in the same system.

MotionSystem · layout motion · presence
08 Runtime

Relay, Scheduler & Caches

A root-owned MPSC Relay drains bounded FIFO snapshots before retained work. Off-thread binding, command, resource, collection, and theme notifications coalesce onto the UI thread; deduplicated phase queues and idle checks stay allocation-conscious.

UiRelay · UiFrameScheduler · RetainedRenderCache
09 Platform

Hosts, Backends & Diagnostics

UiHost, MonoGame integration, and the native Windows runtime drive the same abstract command stream. Frame stats, traces, cache dumps, screenshots, and platform probes expose what happened.

UiHost · IDrawingBackend · FrameDiagnostics

Frame pipeline

One host frame. Dirty work only.

A host frame first drains one bounded Relay snapshot, can settle existing scheduled work before input, dispatches that input, then runs a second retained pass only when the tree becomes dirty. State settles before layout, caches refresh independently, and drawing submits the committed command stream.

Motion Hooks span the frame
Begin Before layout After layout Before render After render
RL
Relay

Cross-thread posts, invocations, and async continuations drain as a bounded FIFO snapshot on the root UI thread.

IN
Input

Pointer, keyboard, and text dispatch through hit testing, capture, focus, commands, navigation, and routed events.

ST
State & Aspects

Inherited values drain, command state refreshes, aspects run, then inherited propagation drains again before layout.

ME
Measure

Only pending work is ordered. Redundant propagated entries are skipped, and parents escalate only when desired size changes.

AR
Arrange

Required entries write final bounds in deterministic visual order; propagated-only work can clear without redundant layout.

RC
Render Cache

Dirty elements refresh retained caches. Unchanged entries and the shared visual-order index stay reusable.

HT
Hit Test

Input routes and hit-test data refresh as their own phase after render work, ready for the next dispatch.

BE
Commit & Backend

The host commits root commands, then draw submits them to IDrawingBackend; MonoGame consumes the stream.

Idle fast path With no Relay, scheduler, or active-motion work, the host records a no-work frame and reuses the committed root list without building phase snapshots or sort state.

Markup + code-behind

Describe the tree. Keep behavior in C#.

A .crn additional file declares the retained window, named elements, and event hooks. Its matching .crn.cs partial class receives typed names and handler wiring at build time.

One view, one generated partial type
Build time Typed names No runtime XML parser
MainWindow.crn Markup
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22
<Window Title="Cerneala Playground" Width="800" Height="600" FrameRendered="OnFrameRendered"> <Grid Name="PlaygroundLayout"> <Grid.RowDefinitions> <RowDefinition Height="Auto" /> <RowDefinition Height="*" /> </Grid.RowDefinitions> <TextBlock Name="FrameDiagnosticsText" Grid.Row="0" Text="Waiting for first frame..." FontFamily="Consolas" /> <TextBlock Grid.Row="1" Text="Retained content goes here." /> </Grid> </Window>
MainWindow.crn.cs Behavior
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19
using Cerneala.UI.Controls; using Cerneala.UI.Diagnostics; namespace Cerneala.Playground; public partial class MainWindow : Window { private void OnFrameRendered(object? sender, EventArgs args) { if (LastFrame is null) { return; } FrameDiagnosticsText.Text = $"{LastFrame.ElapsedTime.TotalMilliseconds:0.00} ms | " + FrameDiagnostics.Format(LastFrame.Stats); } }
01 Additional file MSBuild feeds every .crn file to the incremental generator.
02 Build-time pairing The matching partial class supplies behavior while markup supplies the retained tree.
03 Typed result Named elements and event hooks become compiled C#, with no XML parsing in the frame loop.

Runtime diagnostics

See inside the frame.

Cerneala exposes frame snapshots, invalidation traces, dirty-tree dumps, routed event routes, render cache diagnostics, layout captures, input targets, motion traces, and platform/resource probes.

Use the diagnostic layer to see what changed, which caches were reused, why layout ran, how input routed, and what services the runtime can actually reach.

Frame stats measure=1 / arrange=1
Invalidation trace request -> queue -> phase
Relay + work queues pending=0 · Relay idle=0 B
Render cache rootValid + commands
Element cache cacheValid / stale / deps
Input route Tunnel -> target -> Bubble
Focused element Button#Increment
Motion trace sampled + writes + completed
Runtime probes clipboard / cursor / dpi

Get started

Start building game UI that thinks in frames.

Cerneala UI is under active development. Read the docs, browse the source, or drop a retained-mode panel into your next MonoGame project.

View on GitHub Read the Docs
git clone https://github.com/Chevalier12/Cerneala.git