ddidderr/ghostty-rs
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(font): add run iterator, shared grid set and config integration

Browse Source 
Completes the font engine port:
- shaper/run.rs ports run.zig: the RunIterator over terminal rows that
  splits text runs at style/face boundaries, selection and cursor,
  handles graphemes and ligatures; Shaper::shape_run shapes a run.
- shared_grid_set.rs ports SharedGridSet.zig: grids keyed by a config
  derived key, handed out as Arc<SharedGrid>.
- Font-related types now have one canonical definition in ghostty-config
  (Variation, Descriptor, CodepointMap, metric modifiers, freetype load
  flags, synthetic style, shaping break) which the font crate re-exports.
  MetricModifier::apply_i32 now saturates to -i32::MAX like Zig.
- The 23 terminal-driven harfbuzz shaper tests are ported, printing via
  Screen until Terminal lands.

Test Plan:
- cargo test -p ghostty-font (157 passed, 3 ignored - also skipped in
  Zig); Devanagari/Chakma/Bengali tests return early without system fonts
- cargo test -p ghostty-config (255 passed)
This commit is contained in:
ddidderr committed 2026-10-11 22:38:55 +02:00
1 parent b64a2886ec
commit 7b408257c4
19 files changed
+3204 -554
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

crates/ghostty-font/src/shaper/run.rs
+568
View File
@@ -0,0 +1,568 @@
//! Text runs and the run iterator. Port of `font/shaper/run.zig`.
//!
//! A [`RunIterator`] walks one terminal row (given as a slice of
//! [`RunCell`]) and yields [`TextRun`]s: maximal sequences of cells that can
//! be shaped together (same font, same style apart from background, not
//! crossing a selection or cursor boundary, ...). The codepoints of each run
//! are fed to the shaper through the [`RunIteratorHook`] trait
//! (`prepare` / `add_codepoint` / `finalize`).
#![allow(clippy::collapsible_if)]
use std::hash::{DefaultHasher, Hash, Hasher};
use ghostty_config::types_a::FontShapingBreak;
use ghostty_terminal::page::{Cell, ContentTag, Page, Wide};
use ghostty_terminal::style::{Color, Style as TermStyle};
use crate::collection::Index;
use crate::shared_grid::{Error as GridError, SharedGrid};
use crate::{Presentation, Style};
/// The Kitty graphics unicode placeholder codepoint
/// (`terminal.kitty.graphics.unicode.placeholder`).
// TODO(integration): use the constant from ghostty-terminal once the kitty
// graphics module lands there.
pub const KITTY_PLACEHOLDER: u32 = 0x10EEEE;
/// A single text run. A text run is only valid for one Shaper instance and
/// until the next run is created. A text run never goes across multiple
/// rows in a terminal, so it is guaranteed to always be one line.
///
/// Deviation: the Zig struct carries a `grid: *SharedGrid` field. Here the
/// grid is not part of the run; shapers take it explicitly
/// (`harfbuzz::Shaper::shape_run(grid, run)`), which keeps `TextRun` `Copy`
/// and lifetime-free.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TextRun {
/// A unique hash for this run. This can be used to cache the shaping
/// results. We don't provide a means to compare actual values if the
/// hash is the same, so we should continue to improve this hash to
/// lower the chance of hash collisions if they become a problem. If
/// there are hash collisions, it would result in rendering issues but
/// the core data would be correct.
///
/// The hash is position-independent within the row by using relative
/// cluster positions. This allows identical runs in different positions
/// to share the same cache entry, improving cache efficiency.
pub hash: u64,
/// The offset in the row where this run started. This is added to the
/// X position of the final shaped cells to get the absolute position
/// in the row where they belong.
pub offset: u16,
/// The total number of cells produced by this run.
pub cells: u16,
/// The font index to use for the glyphs of this run.
pub font_index: Index,
}
/// One cell of a row to shape: the equivalent of one element of
/// `terminal.RenderState.Cell` (`raw`, `grapheme`, `style`).
// TODO(integration): replace with the render-state cell type from
// ghostty-terminal once `RenderState` is ported there.
#[derive(Debug, Clone, Default)]
pub struct RunCell {
/// The raw page cell.
pub raw: Cell,
/// The extra codepoints of the grapheme (empty unless
/// `raw.has_grapheme()`).
pub grapheme: Vec<u32>,
/// The resolved style (default style if the cell has no styling).
pub style: TermStyle,
}
impl RunCell {
/// Build the run cells for row `y` of a page.
pub fn from_page_row(page: &Page, y: usize) -> Vec<RunCell> {
let Some(cells) = page.get_cells(y) else {
return Vec::new();
};
cells
.iter()
.enumerate()
.map(|(x, &raw)| {
let grapheme = if raw.has_grapheme() {
page.cell_index(x, y)
.ok()
.and_then(|i| page.lookup_grapheme(i))
.map(<[u32]>::to_vec)
.unwrap_or_default()
} else {
Vec::new()
};
let style = if raw.has_styling() {
page.style(raw)
} else {
TermStyle::default()
};
RunCell {
raw,
grapheme,
style,
}
})
.collect()
}
}
/// Options for [`RunIterator`] (`shape.RunOptions`).
pub struct RunOptions<'a> {
/// The font state for the terminal screen. Cached values may be updated
/// during shaping (the grid has interior locking).
pub grid: &'a SharedGrid,
/// The cells for the row to shape.
pub cells: &'a [RunCell],
/// The x boundaries of the selection in this row.
pub selection: Option<[u16; 2]>,
/// The cursor position within this row. This is used to break shaping
/// on cursor boundaries. This can be disabled by setting this to
/// None.
pub cursor_x: Option<usize>,
}
impl<'a> RunOptions<'a> {
pub fn new(grid: &'a SharedGrid, cells: &'a [RunCell]) -> Self {
RunOptions {
grid,
cells,
selection: None,
cursor_x: None,
}
}
/// Apply the font break configuration to the run.
pub fn apply_break_config(&mut self, config: FontShapingBreak) {
if !config.cursor {
self.cursor_x = None;
}
}
}
/// The hooks a shaper provides to the run iterator
/// (`font.Shaper.RunIteratorHook`).
pub trait RunIteratorHook {
/// Called before a new run is started.
fn prepare(&mut self);
/// Called for each codepoint of the run, with the (run relative) cluster.
fn add_codepoint(&mut self, cp: u32, cluster: u32);
/// Called when the run is complete.
fn finalize(&mut self);
}
impl RunIteratorHook for crate::shaper::harfbuzz::Shaper {
fn prepare(&mut self) {
Self::prepare(self);
}
fn add_codepoint(&mut self, cp: u32, cluster: u32) {
Self::add_codepoint(self, cp, cluster);
}
fn finalize(&mut self) {
Self::finalize(self);
}
}
impl RunIteratorHook for crate::shaper::noop::Shaper {
fn prepare(&mut self) {
Self::prepare(self);
}
fn add_codepoint(&mut self, cp: u32, cluster: u32) {
Self::add_codepoint(self, cp, cluster);
}
fn finalize(&mut self) {
Self::finalize(self);
}
}
/// RunIterator is an iterator that yields text runs. Unlike Zig, which
/// stores the hooks inside the iterator, the shaper is passed to
/// [`RunIterator::next`] so it can be used (to shape) between calls.
pub struct RunIterator<'a> {
pub opts: RunOptions<'a>,
i: usize,
}
impl<'a> RunIterator<'a> {
pub fn new(opts: RunOptions<'a>) -> Self {
RunIterator { opts, i: 0 }
}
pub fn next(&mut self, hooks: &mut dyn RunIteratorHook) -> Result<Option<TextRun>, GridError> {
let cells = self.opts.cells;
// Trim the right side of a row that might be empty
let max: usize = (0..cells.len())
.rev()
.find(|&i| !cells[i].raw.is_empty())
.map_or(0, |i| i + 1);
// Invisible cells don't have any glyphs rendered,
// so we explicitly skip them in the shaping process.
while self.i < max
&& (cells[self.i].raw.has_styling() && cells[self.i].style.flags.invisible)
{
self.i += 1;
}
// We're over at the max
if self.i >= max {
return Ok(None);
}
// Track the font for our current run
let mut current_font = Index::default();
// Allow the hook to prepare
hooks.prepare();
// Initialize our hash for this run.
let mut hasher = DefaultHasher::new();
// Let's get our style that we'll expect for the run.
let style: TermStyle = if cells[self.i].raw.has_styling() {
cells[self.i].style
} else {
TermStyle::default()
};
// Go through cell by cell and accumulate while we build our run.
let start = self.i;
let end = 'run: {
for j in start..max {
// Use relative cluster positions (offset from run start) to make
// the shaping cache position-independent. This ensures that runs
// with identical content but different starting positions in the
// row produce the same hash, enabling cache reuse.
let cluster = (j - start) as u32;
let cell = &cells[j];
let raw = cell.raw;
// If we have a selection and we're at a boundary point, then
// we break the run here.
if let Some(bounds) = self.opts.selection {
if j > start {
let (b0, b1) = (usize::from(bounds[0]), usize::from(bounds[1]));
if b0 > 0 && j == b0 {
break 'run j;
}
if b1 > 0 && j == b1 + 1 {
break 'run j;
}
}
}
// If we're a spacer, then we ignore it
match raw.wide() {
Wide::Narrow | Wide::Wide => {}
Wide::SpacerHead | Wide::SpacerTail => continue,
}
// If our cell attributes are changing, then we split the run.
// This prevents a single glyph for ">=" to be rendered with
// one color when the two components have different styling.
if j > start {
let prev_cell = cells[j - 1].raw;
// If the prev cell and this cell are both plain
// codepoints then we check if they are commonly "bad"
// ligatures and spit the run if they are.
if prev_cell.content_tag() == ContentTag::Codepoint
&& raw.content_tag() == ContentTag::Codepoint
{
let prev_cp = prev_cell.codepoint();
let cp = raw.codepoint();
match char::from_u32(prev_cp) {
// fl, fi
Some('f') if cp == u32::from('l') || cp == u32::from('i') => {
break 'run j;
}
// st
Some('s') if cp == u32::from('t') => break 'run j,
_ => {}
}
}
// If the style is exactly the change then fast path out.
// Otherwise the style is different. We allow differing
// background styles but any other change results in a
// new run.
if prev_cell.style_id() != raw.style_id() {
let c1 = comparable_style(style);
let c2 = comparable_style(if raw.has_styling() {
cell.style
} else {
TermStyle::default()
});
if c1 != c2 {
break 'run j;
}
}
}
// Text runs break when font styles change so we need to get
// the proper style.
let font_style = if style.flags.bold {
if style.flags.italic {
Style::BoldItalic
} else {
Style::Bold
}
} else if style.flags.italic {
Style::Italic
} else {
Style::Regular
};
// Determine the presentation format for this glyph.
let presentation: Option<Presentation> = if raw.has_grapheme() {
// We only check the FIRST codepoint because I believe the
// presentation format must be directly adjacent to the codepoint.
let cps = &cell.grapheme;
assert_ne!(cps.len(), 0);
match cps[0] {
0xFE0E => Some(Presentation::Text),
0xFE0F => Some(Presentation::Emoji),
_ => None,
}
} else {
// If we're not a grapheme, our individual char could be
// an emoji so we want to check if we expect emoji presentation.
// The font grid index_for_codepoint we use below will do this
// automatically.
None
};
// If our cursor is on this line then we break the run around the
// cursor. This means that any row with a cursor has at least
// three breaks: before, exactly the cursor, and after.
//
// We do not break a cell that is exactly the grapheme. If there
// are cells following that contain joiners, we allow those to
// break. This creates an effect where hovering over an emoji
// such as a skin-tone emoji is fine, but hovering over the
// joiners will show the joiners allowing you to modify the
// emoji.
if !raw.has_grapheme() {
if let Some(cursor_x) = self.opts.cursor_x {
// Exactly: self.i is the cursor and we iterated once. This
// means that we started exactly at the cursor and did at
// exactly one iteration. Why exactly one? Because we may
// start at our cursor but do many if our cursor is exactly
// on an emoji.
if start == cursor_x && j == start + 1 {
break 'run j;
}
// Before: up to and not including the cursor. This means
// that we started before the cursor (self.i < cursor_x)
// and j is now at the cursor meaning we haven't yet processed
// the cursor.
if start < cursor_x && j == cursor_x {
assert!(j > 0);
break 'run j;
}
// After: after the cursor. We don't need to do anything
// special, we just let the run complete.
}
}
// We need to find a font that supports this character. If
// there are additional zero-width codepoints (to form a single
// grapheme, i.e. combining characters), we need to find a font
// that supports all of them.
let (font_idx, fallback): (Index, Option<u32>) = 'font_info: {
// If we find a font that supports this entire grapheme
// then we use that.
if let Some(idx) = self.index_for_cell(cell, font_style, presentation)? {
break 'font_info (idx, None);
}
// Otherwise we need a fallback character. Prefer the
// official replacement character.
if let Some(idx) = self.opts.grid.get_index(0xFFFD, font_style, presentation)? {
break 'font_info (idx, Some(0xFFFD));
}
// Fallback to space
if let Some(idx) =
self.opts
.grid
.get_index(u32::from(' '), font_style, presentation)?
{
break 'font_info (idx, Some(u32::from(' ')));
}
// We can't render at all. This is a bug, we should always
// have a font that can render a space.
unreachable!("no font can render a space");
};
if j == start {
current_font = font_idx;
}
// If our fonts are not equal, then we're done with our run.
if font_idx != current_font {
break 'run j;
}
// If we're a fallback character, add that and continue; we
// don't want to add the entire grapheme.
if let Some(cp) = fallback {
add_codepoint(hooks, &mut hasher, cp, cluster);
continue;
}
// If we're a Kitty unicode placeholder then we add a blank.
if raw.codepoint() == KITTY_PLACEHOLDER {
add_codepoint(hooks, &mut hasher, u32::from(' '), cluster);
continue;
}
// Add all the codepoints for our grapheme
add_codepoint(
hooks,
&mut hasher,
if raw.codepoint() == 0 {
u32::from(' ')
} else {
raw.codepoint()
},
cluster,
);
if raw.has_grapheme() {
for &cp in &cell.grapheme {
// Do not send presentation modifiers
if cp == 0xFE0E || cp == 0xFE0F {
continue;
}
add_codepoint(hooks, &mut hasher, cp, cluster);
}
}
}
max
};
// Finalize our buffer
hooks.finalize();
// Add our length to the hash as an additional mechanism to avoid collisions
(end - start).hash(&mut hasher);
// Add our font index
current_font.hash(&mut hasher);
// Move our cursor.
self.i = end;
Ok(Some(TextRun {
hash: hasher.finish(),
offset: start as u16,
cells: (end - start) as u16,
font_index: current_font,
}))
}
/// Find a font index that supports the grapheme for the given cell,
/// or None if no such font exists.
///
/// This is used to find a font that supports the entire grapheme.
/// We look for fonts that support each individual codepoint and then
/// find the common font amongst all candidates.
fn index_for_cell(
&self,
cell: &RunCell,
style: Style,
presentation: Option<Presentation>,
) -> Result<Option<Index>, GridError> {
let raw = cell.raw;
let grid = self.opts.grid;
if raw.is_empty() || raw.codepoint() == 0 || raw.codepoint() == KITTY_PLACEHOLDER {
return grid.get_index(u32::from(' '), style, presentation);
}
// Get the font index for the primary codepoint.
let primary_cp = raw.codepoint();
let Some(primary) = grid.get_index(primary_cp, style, presentation)? else {
return Ok(None);
};
// Easy, and common: we aren't a multi-codepoint grapheme, so
// we just return whatever index for the cell codepoint.
if !raw.has_grapheme() {
return Ok(Some(primary));
}
// If this is a grapheme, we need to find a font that supports
// all of the codepoints in the grapheme.
let graphemes = &cell.grapheme;
let mut candidates: Vec<Index> = Vec::with_capacity(graphemes.len() + 1);
candidates.push(primary);
for &cp in graphemes {
// Ignore Emoji ZWJs
if cp == 0xFE0E || cp == 0xFE0F || cp == 0x200D {
continue;
}
// Find a font that supports this codepoint. If none support this
// then the whole grapheme can't be rendered so we return None.
//
// We explicitly do not require the additional grapheme components
// to support the base presentation, since it is common for emoji
// fonts to support the base emoji with emoji presentation but not
// certain ZWJ-combined characters like the male and female signs.
let Some(idx) = grid.get_index(cp, style, None)? else {
return Ok(None);
};
candidates.push(idx);
}
// We need to find a candidate that has ALL of our codepoints
for &idx in &candidates {
if !grid.has_codepoint(idx, primary_cp, presentation) {
continue;
}
let all = graphemes.iter().all(|&cp| {
// Ignore Emoji ZWJs
cp == 0xFE0E || cp == 0xFE0F || cp == 0x200D || grid.has_codepoint(idx, cp, None)
});
if all {
// We have a candidate that supports all of our codepoints.
return Ok(Some(idx));
}
}
Ok(None)
}
}
fn add_codepoint(
hooks: &mut dyn RunIteratorHook,
hasher: &mut DefaultHasher,
cp: u32,
cluster: u32,
) {
cp.hash(hasher);
cluster.hash(hasher);
hooks.add_codepoint(cp, cluster);
}
/// Returns a style that when compared must be identical for a run to
/// continue.
fn comparable_style(style: TermStyle) -> TermStyle {
let mut s = style;
// We allow background colors to differ because we'll just paint the
// cell background whatever the style is, and wherever the glyph
// lands on top of it will be the color of the glyph.
s.bg_color = Color::None;
s
}