feat(render): GPU grid with decorations from font metrics [2]

[AbysmalBiscuit]

TL;DR (human written)

This PR adds a new rendering approach for the terminal that is faster than the existing one. The speedup varies from 5% up to 25%.
It also adds support for all terminal styles of underlines, and handles double-width characters (e.g., CJK).

This PR almost guarantees that rendering won't be a bottle neck again, so future performance improvements can just focus on app logic instead.

To use this new renderer, you need to set gpu_grid = true in your config:

[ui]
gpu_grid = true

To customize the decorations, you can use the new [ui.decorations] table (inspired by how kitty does it):

[ui.decorations]
underline_position = "1px"
underline_thickness = "150%"
strikeout_position = "-0.5pt"
strikeout_thickness = "125%"

I am planning to support some more features for it later (e.g., colored underlines), so for now I'm leaving the old rendering path.

Closes AbysmalBiscuit#9
Closes AbysmalBiscuit#12
Closes AbysmalBiscuit#41

Claude summary follows:

---

Stacked on #202. The base is master, so the diff below also contains that PR's commits. Review #202 first.

Two changes, both behind config options that default to off:

• the terminal grid draws through an OpenGL callback instead of egui shapes
• underlines and strikeouts take their position and weight from the font's own metric tables, with four knobs to correct a face that reports bad ones

---

Part 1: drawing the grid on the GPU

Drawing the terminal grid costs about 212 ns per cell, and nearly all of that goes into building a list of shapes and then flattening it back into triangles. You can reproduce the number on master today:

cargo test -p alacritree --release -- --ignored --nocapture report_paint_cost

Per character the painter does a GlyphCache lookup, clones an Arc<Galley>, and pushes a TextShape onto egui's shape list. epaint's tessellator then walks each single-glyph galley to emit four vertices. The split is close to even: roughly 105 ns building shapes, roughly 102 ns turning them into triangles. On a 318x83 grid (a 2560x1440-point window at the default font size) that is 26,394 cells and about 105,000 vertices, written by the CPU every frame so the GPU can read them straight back.

I call that the mesh path below. It is what draws the grid today, and this branch leaves it as the default.

Damage tracking would only recover the first half of that. egui re-tessellates every frame whatever happens, and turned down caching it: context.rs says comparing last frame's shapes costs about half what tessellating them costs. So the ceiling inside egui's Shape model is around 2x, for a lot of restructuring.

What this does

egui lets a caller hand epaint an opaque draw callback instead of shapes. The grid takes that route through egui::PaintCallback, so epaint sees a single shape carrying no geometry and everything below it runs on our own GL context.

• One twelve-byte record per cell, in a flat array indexed row * cols + col (grid_instances.rs). The vertex shader derives the quad from that record, so no vertices cross the bus. Only rows the terminal reported damaged get rewritten.
• Three instanced draws over that one buffer (grid_gl.rs): backgrounds, glyphs, decorations, in that order. Decorations go last because alacritty draws its rects over the text in display::draw, so a descender crossing an underline has to come out the same way here.
• No new glyph atlas. egui_glow::Painter::texture hands over the atlas epaint already packed its glyphs into, so the shader samples the same artwork.
• Underlines and strikeouts become a sprite strip (decoration_sprites.rs) sampled per cell, rather than one shape per run for epaint to tessellate every frame.

Emoji and box-drawing glyphs stay on egui's painter. They carry their own textures or their own geometry, and there are few enough of them per screen to leave alone.

Both options default to off

[ui] gpu_grid turns the path on. An unmodified config keeps the mesh path. A GL context too old for instanced arrays logs once, loses the frame it was found on, and falls back for the rest of the session.

[debug] gpu_timing wraps the upload and each draw in timer queries and logs a median line per window. It exists so a bug report about this path can carry numbers rather than adjectives. Results are read a few frames late, because asking for one on the frame that issued it would block until the GPU caught up.

The wide-glyph bug this exposed

Underlines are new on this path, so every style got a look. Under CJK the decoration covered the left half of each character and stopped there.

The cause sits in GridSnapshot::capture, not in the new renderer, so the mesh path had it too.

A wide character occupies two cells: a lead holding the character and Flags::WIDE_CHAR, then a spacer holding a space and Flags::WIDE_CHAR_SPACER. alacritty_terminal writes both from the same cursor template (term/mod.rs, write_at_cursor), so the spacer carries identical colours and identical SGR flags and differs only in which of those two bits is set. capture groups cells into runs of one style, and Style::from_cell compared raw flags, so that single bit read as a style change. Every wide character ended its run early and its spacer was dropped from the frame entirely.

The fix masks both bits out of the style comparison and stops discarding spacers. kitty reaches the same place from the other end: screen.c copies the lead cell's GPU record into the spacer at parse time, and its renderer then has no width logic anywhere. alacritty does the opposite, dropping spacers from its renderable iterator and adding the column back when it draws a line (renderer/rects.rs). I tried alacritty's shape first, reconstructing the missing column with width arithmetic in the loop that writes cell records. It worked and cost about 4% of that loop, measured against a captured snapshot replayed in one process. Masking two bits costs nothing, because the grid already holds what the arithmetic was recomputing.

One pleasant side effect: 你好 now captures as a single run spanning four columns instead of two runs of one column each, so a screen full of CJK produces about half as many runs.

Measurements

termbench (forked from the original termbench) drives the terminal with several output workloads and reports wall time for each, plus a total.

Every run here is paired. Two builds launch a minute apart and the ratio is taken within the pair, so machine drift divides out rather than landing on whichever build met it. Which build goes first alternates every pair. Four grid sizes, one machine. Below 1 means this branch was faster.

grid	cells	total	pairs kept
78x18	1,404	0.975	5 of 5
198x47	9,306	0.955	5 of 6
198x46	9,108	0.957	5 of 6
352x80	28,160	0.944	6 of 6

I threw out three pairs because a load check caught a CPU spike inside one of the two builds, which pairing cannot divide away.

The advantage grows with cell count, which is what a per-cell cost predicts and a fixed overhead would not. 352x80 is the row to trust: every pair inside 2% on the load check, all six pointing the same way. The two 198x4x rows are the same experiment run twice, landing within 0.002 of each other, which is what makes the gap up to 78x18 readable as signal rather than noise.

Per workload, at three of those grid sizes:

workload	1,404 cells	9,108 cells	28,160 cells
sc.noscroll	1.003	0.877	0.744
sg.plain	0.977	0.850	0.778
tb.LongLine	0.944	0.920	0.879
sc.scroll	0.942	0.928	0.875

sc.noscroll fills the screen without scrolling it, and it is the clearest case: no gain at all on a tiny grid, 25.6% faster on a full-screen one. That is a per-cell submit cost showing up only once there are enough cells to pay for it.

What these numbers do not settle

The faster build also carried the PTY packet-storm fix from #195, which was unmerged at the time and changes how quickly the reader drains bytes while the paint lock is contended. termbench measures almost exactly that. So 0.944 is an upper bound on what this renderer contributes, not an isolated figure for it. The direction and the growth with cell count still hold. A clean re-run against current master, now that #195 has landed, would replace the bound with a number, and I have not done it.

termbench also measures throughput rather than frame time. It asks how fast the terminal swallows a stream, which is mostly parser and grid-update bound, so a paint saving shows up as UI-thread headroom sitting behind a bottleneck somewhere else.

One regression, and it is by design

Three SGR-heavy workloads move the other way, and unlike the wins they do not scale:

workload	1,404 cells	9,108 cells	28,160 cells
sg.percellbg	1.001	1.046	1.021
sg.underline	0.985	1.030	1.018
sg.percell	0.979	1.006	1.013

Every cell gets an instance in all three passes. A screen where each cell carries its own background colour and its own decoration therefore pays every pass at full width, where the mesh path emitted shapes only for the runs that differed. That trade is what buys the flat per-cell cost in the table above. On the workload built to stress SGR it costs 1 to 4%, and it is worth naming rather than burying.

---

Part 2: decorations from the font's own metrics

Underlines and strikeouts were placed by three constants scaled off the cell height:

thickness: (cell_h * ppp / 14.0).round().max(1.0),
underline_y: (cell_h - 1.5) * ppp,
strikeout_y: cell_h * 0.5 * ppp,

The font's own numbers went unread, so a face that asks for a fine stroke and a low underline got neither. The post table carries underlinePosition and underlineThickness; OS/2 carries yStrikeoutPosition and yStrikeoutSize. Upstream alacritty reads all four plus the descent through crossfont::Metrics and places its lines from them in renderer/rects.rs, so this was a divergence rather than a shared limitation.

ttf-parser was already in the lockfile. Face::underline_metrics() and Face::strikeout_metrics() read those two tables and apply variable-font metric variations, so a variable face reports metrics for its instantiated weight rather than its default master. The primary face is parsed once at startup.

Finding the baseline

Geometry needs the baseline's position inside the cell, and deriving it from the face drifts from where glyphs actually sit. FontImpl::new quantizes the ascent it stores: epaint divides the scaled ascent by pixels_per_point and calls round_ui, which snaps to a multiple of 1/32 of a logical point. The face's ascent and the one epaint lays out against are different numbers.

Glyph.font_ascent on a laid-out galley is the quantized one, so that is what the geometry uses. The grid's own GlyphCache already holds a galley for M at the paint size, so reading the ascent is a map lookup rather than a fresh layout per frame.

That also yields the em size without depending on epaint's scaling internals: px_per_em = font_ascent_px / metrics.ascender.

The descent area

baseline and descent are new on Geometry, and together they give the band from baseline to baseline + descent. Two styles anchor there rather than on underline_y, which is what alacritty does:

• double: two stems, centred at baseline + 0.25 * descent and baseline + 0.75 * descent
• curly: a sine wave filling the band, centre baseline + descent / 2, amplitude (descent - underline_thickness) / 2

Straight, dashed and dotted keep underline_y and the font's thickness. This matters because once thickness comes from the font, deriving a curl's height from it gives a face with a fine stroke a curl too shallow to read, and a double underline whose stems merge.

alacritty reaches the same band from the cell's bottom edge, which works there because its cell height is the font's. Here cell_h is a floored row height plus font.offset.y, so the cell bottom and baseline + descent are two different places and only the baseline tracks where glyphs sit.

The single thickness field splits in two, because the font reports separate weights for the two lines and nothing justified picking one of them for both.

A face can ship a table with a zero in it, which kitty and ghostty both guard against. Same guards here: a missing underline thickness falls back to 0.05 em, a missing position to -0.1 em, a missing strikeout thickness to the resolved underline thickness, and a missing strikeout position to 0.35 x ascender. A face that will not parse at all yields every default and one log::warn!.

The knobs

Four optional string fields, for correcting a face whose metrics are wrong:

[ui.decorations]
underline_position = "-2px"
underline_thickness = "150%"
strikeout_position = "2pt"
strikeout_thickness = "200%"

suffix	means
px	physical pixels, added
pt or none	points, added after scaling by pixels_per_point
%	multiplies the resolved pixel value

Positive moves the line down, matching kitty and ghostty, so a value copied from either behaves the same way. kitty spells points as a bare number; pt is accepted as well so a config can say what it means, and everything kitty accepts still parses.

"0" adds nothing and "100%" multiplies by one, so both units express the same no-op and an unmodified config follows the face. A percentage carries no sign: kitty takes the absolute value of a negative one, which is a silent surprise, so this rejects it and logs. Any value that will not parse logs a warning naming the field and the offending text, then behaves as "0". Nothing here panics.

Scaling happens before rounding, because rounding first would quantize the value a percentage then scales, leaving a 50% request against a 1px line with nothing to halve.

One caveat worth stating for anyone porting a kitty config: because double and curly anchor on the descent, underline_position does not move them. kitty derives both from underline_position instead (decorations.c, add_double_underline and add_curl_underline). This follows alacritty.

The mesh path is unchanged

The old renderer keeps its constants and its single straight rule. It is slated for removal once the GL path is stable, and the comment at the construction site now records that the two paths differ deliberately.

---

Tests

cargo test -p alacritree runs 1,116 unit tests plus 7 in tests/cli_isolation.rs and 2 in tests/config_schema.rs.

One test fails on my machine right now: session::tests::a_pane_runs_its_child_without_a_console_host_handshake asserts cmd /c echo ready exits within 2 seconds, and under load it does not. That test and its assertion are byte-identical to master's, and nothing in this branch touches it.

The GL path runs headless through a GpuGrid whose callback is emitted and never invoked, which covers everything on the CPU side (capture, run building, record writing) and the fallback when the context will not build. Two tests cover the wide-glyph fix: one asserts a spacer keeps its background and its decoration, the other that a run holds one character for every column it spans.

The decoration work is covered headless with no GL context: the suffix parser over the values that should and should not parse, FaceMetrics read from the bundled alacritree-symbols.ttf with each value asserted normalized to the em, each fallback from a synthetic FaceMetrics with one field zeroed, and the geometry resolved with zero adjustments. The assertion that catches an anchor read off the cell bottom instead of the baseline is on rasterized output: on a Geometry whose descent area sits clear of the cell edges, the curly tile's ink stays inside [baseline, baseline + descent] and the double tile's two stems straddle its midpoint.

---

Written by Claude Opus 5 in Claude Code.