Hosting and rendering
Three thin hosts over one renderer. A host maps input, supplies a frame clock and hands the frame to the platform; the grid, its interaction and its drawing are the same code on all three.
The three hosts
| Host | Control, target, how the frame reaches the screen |
|---|---|
ArionUI.Rendering.Avalonia | ArionGrid, net10.0. On Windows the grid presents its frames itself: a swap chain of its own, shown by a DirectComposition visual over the window and paced on the vertical blank. Where that visual cannot show the grid 1:1 (an ancestor that scales, rotates or mirrors it, a layered window, another platform), it hands its frames to Avalonia's compositor; without a GPU, it draws into a bitmap on the CPU. |
ArionUI.Rendering.Wpf | ArionGrid, net10.0-windows. Skia draws through ANGLE on Direct3D 11, on the grid's own render thread, into a swap chain of its own, shown by a DirectComposition visual over the window and paced on the vertical blank. Where that visual cannot show the grid 1:1 (a window with AllowsTransparency, an ancestor that scales, rotates or mirrors it), the grid is drawn through a D3DImage. |
ArionUI.Rendering.WinForms | ArionGridControl, net10.0-windows10.0.19041. Presents on a swap chain of its own, shown by a DirectComposition visual on the control's own window; without DirectComposition, into an ANGLE surface on that window. A child control added to ArionGridControl.Controls cannot be seen. DataSource takes a DataTable, a DataView, a list of objects or a BindingSource over one. dotnet add package ArionUI.Rendering.WinForms --prerelease. |
Presenting itself costs airspace on Avalonia (on Windows) and WPF: content of the same window cannot be drawn over the grid. A control that overlaps it lies under it, and so do adorners such as a focus visual. The grid's own panes are drawn over it. On WPF, popups, tooltips and context menus are drawn over it too. On Avalonia, popups, tooltips, context menus and flyouts in windows of their own are drawn over it; with OverlayPopups set, popups are drawn in the window's overlay layer and lie under it.
Each control is an ordinary element of its framework: put it in a window, a tab, a split panel, several per window. A view belongs to one control at a time; attaching a view that is already shown by another control throws and changes nothing. Development and the automated tests run on Windows.
var view = new GridView<OrderRecord>(
[
Column.Text<OrderRecord>("Customer", o => o.Customer).WithKey("customer").WithWidth(180),
TypedColumn.Number<OrderRecord>("Amount", o => o.Amount, format: "#,##0.00").WithKey("amount"),
],
new ListItemsSource<OrderRecord>(orders))
.AsDataGrid();
Controls.Add(new ArionGridControl(view)
{
Dock = DockStyle.Fill,
VisualTheme = ArionTheme.Light(),
});GPU path and CPU path
By default the grid draws on the GPU. Where Avalonia hands the grid no GPU context, the Avalonia host falls back to a CPU path on its own: it shifts the existing bitmap when scrolling and repaints only the strip that scrolled into view. Neither path scales with the number of rows; the CPU path scales with the pixel area it has to repaint.
On the GPU path the plain cells of a table — backgrounds, value scales and text — are drawn by ArionUI's own shader program in one instanced draw call; a cell the program cannot describe is drawn the regular way over its slot, and without a GL context every cell is. Under ANGLE the first compile of the program takes a few hundred milliseconds, and the cells draw on the CPU meanwhile, with the same pixels. The compiled program is kept in %LOCALAPPDATA%\ArionUI\ShaderCache, so later starts load it in a few milliseconds; set ARION_SHADER_CACHE=0, or ShaderBinaryCache.Default = null before the first grid is shown, to keep nothing on disk.
The fallback is not silent. It is written to the diagnostic log as
[ArionUI] GPU lease unavailable → CPU fallback: <reason>and the control says which path ran. ActiveRenderer and FallbackReason are on all three hosts; RendererKind is in the namespace ArionUI.Grid.
if (grid.ActiveRenderer == RendererKind.Bitmap)
{
// the CPU path: the reason is also written to ArionGrid.DiagnosticLog
Log($"GPU path not available: {grid.FallbackReason}");
}ActiveRenderer is RendererKind.None before the first frame. Only the Avalonia host has a CPU path, so only it reports Bitmap and a FallbackReason; on WPF and WinForms ActiveRenderer is Gpu once a frame is drawn (on WPF None again after a failed frame), FallbackReason stays null, and a frame that could not be drawn is reported in RendererFailure.
The WPF and WinForms hosts render through ANGLE; RendererName shows the adapter they got, which can be a software rasterizer such as the Microsoft Basic Render Driver. Charts draw their lines and areas on the GPU too and fall back to the surface by themselves. The 3D views of ArionUI.Charts3D have no CPU path; without a GPU they show their FallbackText.
Diagnostics
ArionGrid.DiagnosticLog = line => Log(line); // default: Console.WriteLine
grid.RendererFailed += (_, e) => Log($"drawing failed: {e.Exception.Message}");
grid.FrameRendered += stats => Log($"{stats.FrameMs:0.00} ms, {stats.DrawnSlots} rows drawn");
string? adapter = grid.RendererName; // the GL_RENDERER string, once a GPU frame ran
string? failure = grid.RendererFailure; // why the last frame could not be drawn, or nullDiagnosticLog is static per host type and defaults to Console.WriteLine. RendererFailed is raised once per distinct failure, not once per frame. FrameRendered delivers FrameStats after each frame: its duration, the rows visible and drawn, and whether it was a full redraw; set ProfileFrames for a breakdown by phase. TryWriteFramePng(stream) forces a complete frame and writes the control's own pixels to a PNG — for bug reports and image tests.
Choosing the graphics adapter
On a laptop with two GPUs the display usually hangs on the integrated one, and that is what a host gets unless something asks for the other. The environment variable ARION_GPU decides before start-up:
| Value | Adapter |
|---|---|
high | The hardware adapter with the most dedicated video memory. |
low | The one with the least. |
| any other text | The first adapter whose description contains it, ignoring case (nvidia, intel). |
| unset | The host's default. |
RendererName then tells you which adapter really drew. On WPF's D3DImage path (see the table above) the texture has to reach a Direct3D 9 device on the same adapter, and a shared texture does not cross adapters. Where ARION_GPU names an adapter Direct3D 9 does not list, the host stays on its default adapter and says so in the log. A software adapter is copied through system memory. The composition path has no such restriction.
Fonts and text
The default font family is Segoe UI; the Skia package bundles JetBrains Mono. Any other font is registered once at start-up and then named in the theme:
ArionFonts.Register("Inter", File.OpenRead("Fonts/Inter-Regular.ttf"));
ArionFonts.Register("Inter", File.OpenRead("Fonts/Inter-SemiBold.ttf"), FontWeight.SemiBold);
grid.VisualTheme = ArionTheme.Light() with { FontFamily = "Inter" };
ArionFonts.Shaping = TextShaping.Simple; // one glyph per character, no HarfBuzzText is shaped with HarfBuzz by default, with fallback to an installed font for characters the requested one lacks. Programming ligatures are off (ArionFonts.Ligatures), so -> stays two characters. TextShaping.Simple draws one glyph per character, which is also what happens when the native HarfBuzz library is missing — fine for Latin, Greek and Cyrillic, wrong for joined scripts such as Arabic. The environment variable ARION_SHAPING=0 forces the simple path whatever the application sets.