use crate::unicode;
use cosmic_text::fontdb;
use cosmic_text::{
Attrs, Buffer, CacheKey, CacheKeyFlags, Family, FontSystem, LayoutGlyph, Metrics, Shaping,
SwashCache, SwashContent, Weight, Wrap,
};
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::{Arc, Mutex, OnceLock};
const MAX_RUN_CELLS: usize = 256;
const MAX_CONTIGUOUS_RUN_CELLS: usize = 512;
fn run_chunk_limit(cells: &[RunCell]) -> usize {
if cells
.iter()
.any(|cell| unicode::cluster_forces_contiguous_run(&cell.text))
{
MAX_CONTIGUOUS_RUN_CELLS
} else {
MAX_RUN_CELLS
}
}
const MAX_GLYPH_PIXELS: usize = 1 << 20;
const MAX_GLYPH_CACHE_BYTES: usize = 32 * 1024 * 1024;
const MAX_GLYPH_CACHE_ENTRIES: usize = 32 * 1024;
fn glyph_cache_full(entries: usize, bytes: usize) -> bool {
entries >= MAX_GLYPH_CACHE_ENTRIES || bytes >= MAX_GLYPH_CACHE_BYTES
}
const MAX_SHAPE_CACHE_ENTRIES: usize = 4096;
const MAX_EXPLICIT_FACES: usize = 64;
fn explicit_faces_fit(current: usize, additional: usize) -> bool {
current
.checked_add(additional)
.is_some_and(|total| total <= MAX_EXPLICIT_FACES)
}
const MIN_FIT_SCALE: f32 = 0.5;
const MAX_FIT_SCALE: f32 = 1.5;
const KNOWN_EMOJI_FAMILIES: &[&str] = &[
"Noto Color Emoji",
"Apple Color Emoji",
"Segoe UI Emoji",
"Twemoji Mozilla",
"Twitter Color Emoji",
"JoyPixels",
"OpenMoji Color",
"EmojiOne Color",
];
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct ShapingOptions {
pub enabled: bool,
pub system_fonts: bool,
}
impl Default for ShapingOptions {
fn default() -> Self {
Self {
enabled: true,
system_fonts: true,
}
}
}
impl ShapingOptions {
pub fn deterministic() -> Self {
Self {
enabled: true,
system_fonts: false,
}
}
pub fn disabled() -> Self {
Self {
enabled: false,
system_fonts: false,
}
}
pub fn with_enabled(mut self, enabled: bool) -> Self {
self.enabled = enabled;
self
}
pub fn with_system_fonts(mut self, system_fonts: bool) -> Self {
self.system_fonts = system_fonts;
self
}
pub fn from_env() -> Self {
let mut options = Self::default();
if env_flag("UNICODE_SHAPING") == Some(false) {
options.enabled = false;
}
if env_flag("SYSTEM_FONTS") == Some(false) {
options.system_fonts = false;
}
options
}
fn locale(&self) -> String {
if self.system_fonts {
sys_locale::get_locale().unwrap_or_else(|| "en-US".to_string())
} else {
"en-US".to_string()
}
}
}
fn env_flag(name: &str) -> Option<bool> {
let current = format!("TERMSHOT_{name}");
let legacy = format!("SCREENSHOT_MCP_{name}");
let raw = match std::env::var(¤t) {
Ok(value) => value,
Err(_) => match std::env::var(&legacy) {
Ok(value) => {
tracing::warn!("{legacy} is deprecated, use {current} instead");
value
}
Err(_) => return None,
},
};
match raw.trim().to_ascii_lowercase().as_str() {
"0" | "false" | "off" | "no" => Some(false),
"1" | "true" | "on" | "yes" => Some(true),
_ => {
tracing::warn!(
"ignoring invalid {current} value {:?}; use 0/1, false/true, off/on, or no/yes",
raw
);
None
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub(crate) enum FontSource {
Embedded(&'static [u8]),
File(PathBuf),
}
#[derive(Debug, Clone)]
pub(crate) struct RunCell {
pub text: String,
pub cols: u32,
}
#[derive(Debug, Clone)]
pub(crate) struct RunRequest<'a> {
pub cells: &'a [RunCell],
pub cell_w: u32,
pub font_size: f32,
pub ascent: f32,
pub bold: bool,
pub italic: bool,
}
#[derive(Debug)]
pub(crate) struct GlyphBitmap {
pub width: u32,
pub height: u32,
pub color: bool,
pub data: Vec<u8>,
}
#[derive(Debug, Clone)]
pub(crate) struct PlacedGlyph {
pub x: i32,
pub y: i32,
pub bitmap: Arc<GlyphBitmap>,
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct ShapeKey {
text: String,
size_bits: u32,
bold: bool,
italic: bool,
emoji: bool,
}
#[derive(Debug)]
struct ShapedRun {
glyphs: Vec<LayoutGlyph>,
rtl: bool,
}
struct ShapingState {
font_system: FontSystem,
swash: SwashCache,
families: Vec<String>,
emoji_family: Option<String>,
shape_cache: HashMap<ShapeKey, Arc<ShapedRun>>,
glyph_cache: HashMap<CacheKey, Option<Arc<RasterGlyph>>>,
glyph_bytes: usize,
}
#[derive(Debug)]
struct RasterGlyph {
bitmap: Arc<GlyphBitmap>,
left: i32,
top: i32,
}
pub(crate) struct ShapingEngine {
options: ShapingOptions,
sources: Vec<FontSource>,
state: OnceLock<Option<Mutex<ShapingState>>>,
}
impl std::fmt::Debug for ShapingEngine {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ShapingEngine")
.field("options", &self.options)
.field("sources", &self.sources)
.field("initialized", &self.state.get().is_some())
.finish()
}
}
impl ShapingEngine {
pub(crate) fn new(sources: Vec<FontSource>, options: ShapingOptions) -> Self {
Self {
options,
sources,
state: OnceLock::new(),
}
}
pub(crate) fn enabled(&self) -> bool {
self.options.enabled
}
fn state(&self) -> Option<&Mutex<ShapingState>> {
self.state
.get_or_init(|| {
if !self.options.enabled {
return None;
}
Some(Mutex::new(ShapingState::build(
&self.sources,
&self.options,
)))
})
.as_ref()
}
pub(crate) fn place_run(&self, request: &RunRequest<'_>) -> Vec<PlacedGlyph> {
if !self.options.enabled || request.cells.is_empty() || request.cell_w == 0 {
return Vec::new();
}
let Some(state) = self.state() else {
return Vec::new();
};
let Ok(mut state) = state.lock() else {
tracing::warn!("shaping state was poisoned; falling back to unshaped rendering");
return Vec::new();
};
state.place_run(request)
}
#[cfg(test)]
pub(crate) fn families(&self) -> Vec<String> {
match self.state() {
Some(state) => state.lock().map(|s| s.families.clone()).unwrap_or_default(),
None => Vec::new(),
}
}
#[cfg(test)]
pub(crate) fn emoji_family(&self) -> Option<String> {
match self.state() {
Some(state) => state.lock().ok().and_then(|s| s.emoji_family.clone()),
None => None,
}
}
#[cfg(test)]
pub(crate) fn loaded_faces(&self) -> Vec<(String, u32)> {
let Some(state) = self.state() else {
return Vec::new();
};
let Ok(state) = state.lock() else {
return Vec::new();
};
let db = state.font_system.db();
db.faces()
.filter_map(|face| {
let (_, index) = db.face_source(face.id)?;
let family = face.families.first()?.0.clone();
Some((family, index))
})
.collect()
}
}
impl ShapingState {
fn build(sources: &[FontSource], options: &ShapingOptions) -> Self {
let mut db = fontdb::Database::new();
let mut families: Vec<String> = Vec::new();
let mut explicit_ids: Vec<fontdb::ID> = Vec::new();
for source in sources {
if explicit_ids.len() >= MAX_EXPLICIT_FACES {
tracing::warn!(
"ignoring font {:?}: more than {} explicit faces were configured",
source,
MAX_EXPLICIT_FACES
);
break;
}
let make_source = || match source {
FontSource::Embedded(bytes) => Some(fontdb::Source::Binary(Arc::new(*bytes))),
FontSource::File(path) => {
if !path.is_file() {
tracing::warn!("ignoring unreadable shaping font {:?}", path);
return None;
}
Some(fontdb::Source::File(path.clone()))
}
};
let Some(probe_source) = make_source() else {
continue;
};
let mut probe = fontdb::Database::new();
let face_count = probe.load_font_source(probe_source).len();
if !explicit_faces_fit(explicit_ids.len(), face_count) {
let remaining = MAX_EXPLICIT_FACES - explicit_ids.len();
tracing::warn!(
"ignoring font {:?}: its {} faces exceed the remaining explicit-face \
limit of {}",
source,
face_count,
remaining
);
continue;
}
let Some(load_source) = make_source() else {
continue;
};
let loaded = db.load_font_source(load_source);
for id in loaded {
explicit_ids.push(id);
if let Some(face) = db.face(id)
&& let Some((family, _)) = face.families.first()
&& !families.iter().any(|known| known == family)
{
families.push(family.clone());
}
}
}
let explicit_emoji = first_color_family(&db, explicit_ids.iter().copied());
if options.system_fonts {
db.load_system_fonts();
}
if let Some(primary) = families.first() {
db.set_monospace_family(primary.clone());
}
let emoji_family = explicit_emoji.or_else(|| discover_emoji_family(&db));
let locale = options.locale();
let font_system = FontSystem::new_with_locale_and_db(locale, db);
Self {
font_system,
swash: SwashCache::new(),
families,
emoji_family,
shape_cache: HashMap::new(),
glyph_cache: HashMap::new(),
glyph_bytes: 0,
}
}
fn place_run(&mut self, request: &RunRequest<'_>) -> Vec<PlacedGlyph> {
let mut placed = Vec::new();
let mut origin_cols = 0u32;
let chunk_cells = run_chunk_limit(request.cells);
for chunk in request.cells.chunks(chunk_cells) {
let chunk_request = RunRequest {
cells: chunk,
..request.clone()
};
let origin_x = i32::try_from(origin_cols * request.cell_w).unwrap_or(i32::MAX);
self.place_chunk(&chunk_request, origin_x, &mut placed);
origin_cols += chunk.iter().map(|cell| cell.cols).sum::<u32>();
}
placed
}
fn place_chunk(&mut self, request: &RunRequest<'_>, origin_x: i32, out: &mut Vec<PlacedGlyph>) {
let mut text = String::new();
let mut ranges: Vec<std::ops::Range<usize>> = Vec::with_capacity(request.cells.len());
let mut lefts: Vec<u32> = Vec::with_capacity(request.cells.len());
let mut widths: Vec<u32> = Vec::with_capacity(request.cells.len());
let mut pen = 0u32;
for cell in request.cells {
let start = text.len();
text.push_str(&cell.text);
ranges.push(start..text.len());
lefts.push(pen);
widths.push(cell.cols * request.cell_w);
pen += cell.cols * request.cell_w;
}
if text.is_empty() {
return;
}
let emoji = unicode::cluster_is_emoji(&text);
let contiguous = unicode::cluster_forces_contiguous_run(&text);
let shaped = self.shape(&text, request, emoji);
if shaped.glyphs.is_empty() {
return;
}
if request
.cells
.iter()
.any(|cell| unicode::is_split_emoji_fragment(&cell.text))
{
tracing::debug!(
"terminal core split {:?} across {} cells; the sequence is drawn at its own \
width and the extra columns are left blank",
text,
request.cells.len()
);
}
let mut starts_group = vec![true; ranges.len()];
if contiguous {
starts_group.iter_mut().skip(1).for_each(|s| *s = false);
} else {
for glyph in &shaped.glyphs {
let first = cell_of_byte(&ranges, glyph.start);
let last = cell_of_byte(&ranges, glyph.end.saturating_sub(1)).max(first);
for slot in starts_group.iter_mut().take(last + 1).skip(first + 1) {
*slot = false;
}
}
}
let mut start = 0usize;
while start < ranges.len() {
let mut end = start + 1;
while end < ranges.len() && !starts_group[end] {
end += 1;
}
let bytes = ranges[start].start..ranges[end - 1].end;
let members: Vec<&LayoutGlyph> = shaped
.glyphs
.iter()
.filter(|glyph| glyph.glyph_id != 0 && bytes.contains(&glyph.start))
.collect();
if !members.is_empty() {
let target_x = lefts[start];
let target_w: u32 = widths[start..end].iter().sum();
self.place_group(
&members, request, origin_x, target_x, target_w, shaped.rtl, out,
);
}
start = end;
}
}
#[allow(clippy::too_many_arguments)]
fn place_group(
&mut self,
members: &[&LayoutGlyph],
request: &RunRequest<'_>,
origin_x: i32,
target_x: u32,
target_w: u32,
rtl: bool,
out: &mut Vec<PlacedGlyph>,
) {
let min_x = members.iter().fold(f32::INFINITY, |acc, g| acc.min(g.x));
let max_x = members
.iter()
.fold(f32::NEG_INFINITY, |acc, g| acc.max(g.x + g.w));
let natural = (max_x - min_x).max(0.0);
let cell_w = request.cell_w.max(1);
let natural_cells = ((natural / cell_w as f32).ceil() as u32).max(1);
let fit_w = (natural_cells * cell_w).min(target_w);
let scale = if natural > 0.0 && fit_w > 0 {
(fit_w as f32 / natural).clamp(MIN_FIT_SCALE, MAX_FIT_SCALE)
} else {
1.0
};
let scaled = natural * scale;
let used = if scaled <= 0.0 {
target_w
} else {
(((scaled / cell_w as f32).ceil() as u32).max(1) * cell_w).min(target_w)
};
let lead = ((used as f32 - scaled) / 2.0).round();
let anchor = if rtl {
target_x as f32 + (target_w - used) as f32 + lead
} else {
target_x as f32 + lead
};
let offset = (anchor - min_x * scale, request.ascent);
for glyph in members {
let physical = glyph.physical(offset, scale);
let Some(raster) = self.rasterize(physical.cache_key) else {
continue;
};
out.push(PlacedGlyph {
x: origin_x + physical.x + raster.left,
y: physical.y - raster.top,
bitmap: Arc::clone(&raster.bitmap),
});
}
}
fn shape(&mut self, text: &str, request: &RunRequest<'_>, emoji: bool) -> Arc<ShapedRun> {
let key = ShapeKey {
text: text.to_string(),
size_bits: request.font_size.to_bits(),
bold: request.bold,
italic: request.italic,
emoji,
};
if let Some(cached) = self.shape_cache.get(&key) {
return Arc::clone(cached);
}
if self.shape_cache.len() >= MAX_SHAPE_CACHE_ENTRIES {
self.shape_cache.clear();
}
let family = self.family_for(text, emoji, request.bold);
let weight = if request.bold {
Weight::BOLD
} else {
Weight::NORMAL
};
let mut attrs = Attrs::new().family(Family::Name(&family)).weight(weight);
if request.italic {
attrs = attrs.cache_key_flags(CacheKeyFlags::FAKE_ITALIC);
}
let metrics = Metrics::new(request.font_size, request.font_size.max(1.0));
let mut buffer = Buffer::new(&mut self.font_system, metrics);
{
let mut buffer = buffer.borrow_with(&mut self.font_system);
buffer.set_wrap(Wrap::None);
buffer.set_size(None, None);
buffer.set_text(text, &attrs, Shaping::Advanced, None);
buffer.shape_until_scroll(false);
}
let mut glyphs = Vec::new();
let mut rtl = false;
for run in buffer.layout_runs() {
rtl |= run.rtl;
glyphs.extend(run.glyphs.iter().cloned());
}
let shaped = Arc::new(ShapedRun { glyphs, rtl });
self.shape_cache.insert(key, Arc::clone(&shaped));
shaped
}
fn family_for(&mut self, text: &str, emoji: bool, bold: bool) -> String {
if emoji && let Some(family) = self.emoji_family.clone() {
return family;
}
let weight = if bold { Weight::BOLD } else { Weight::NORMAL };
let wanted: Vec<char> = text
.chars()
.filter(|c| !unicode::is_variation_selector(*c) && *c != unicode::ZWJ)
.collect();
if !wanted.is_empty() {
for family in self.families.clone() {
let ids: Vec<fontdb::ID> = self
.font_system
.db()
.faces()
.filter(|face| face.families.iter().any(|(name, _)| *name == family))
.map(|face| face.id)
.collect();
for id in ids {
if self.face_covers(id, weight, &wanted) {
return family;
}
}
}
}
self.families.first().cloned().unwrap_or_default()
}
fn face_covers(&mut self, id: fontdb::ID, weight: Weight, wanted: &[char]) -> bool {
let Some(font) = self.font_system.get_font(id, weight) else {
return false;
};
let charmap = font.as_swash().charmap();
wanted.iter().all(|c| charmap.map(*c) != 0)
}
fn rasterize(&mut self, key: CacheKey) -> Option<Arc<RasterGlyph>> {
if let Some(cached) = self.glyph_cache.get(&key) {
return cached.clone();
}
if glyph_cache_full(self.glyph_cache.len(), self.glyph_bytes) {
self.glyph_cache.clear();
self.swash.image_cache.clear();
self.glyph_bytes = 0;
}
let raster = self
.swash
.get_image_uncached(&mut self.font_system, key)
.and_then(|image| {
let width = image.placement.width;
let height = image.placement.height;
if width == 0 || height == 0 {
return None;
}
let pixels = (width as usize).saturating_mul(height as usize);
if pixels > MAX_GLYPH_PIXELS {
tracing::warn!("skipping a {width}x{height} glyph bitmap: over the size limit");
return None;
}
let color = matches!(image.content, SwashContent::Color);
let expected = if color { pixels * 4 } else { pixels };
if image.data.len() < expected {
return None;
}
Some(Arc::new(RasterGlyph {
bitmap: Arc::new(GlyphBitmap {
width,
height,
color,
data: image.data[..expected].to_vec(),
}),
left: image.placement.left,
top: image.placement.top,
}))
});
if let Some(raster) = &raster {
self.glyph_bytes = self.glyph_bytes.saturating_add(raster.bitmap.data.len());
}
self.glyph_cache.insert(key, raster.clone());
raster
}
}
fn cell_of_byte(ranges: &[std::ops::Range<usize>], byte: usize) -> usize {
match ranges.iter().position(|range| range.contains(&byte)) {
Some(index) => index,
None => ranges.len().saturating_sub(1),
}
}
fn first_color_family(
db: &fontdb::Database,
ids: impl Iterator<Item = fontdb::ID>,
) -> Option<String> {
for id in ids {
let has_color = db.with_face_data(id, has_color_table).unwrap_or(false);
if has_color
&& let Some(face) = db.face(id)
&& let Some((family, _)) = face.families.first()
{
return Some(family.clone());
}
}
None
}
fn discover_emoji_family(db: &fontdb::Database) -> Option<String> {
for wanted in KNOWN_EMOJI_FAMILIES {
let ids = db
.faces()
.filter(|face| face.families.iter().any(|(name, _)| name == wanted))
.map(|face| face.id);
if let Some(family) = first_color_family(db, ids) {
return Some(family);
}
}
let mut candidates: Vec<(String, fontdb::ID)> = db
.faces()
.filter_map(|face| {
let (family, _) = face.families.first()?;
family
.to_ascii_lowercase()
.contains("emoji")
.then(|| (family.clone(), face.id))
})
.collect();
candidates.sort();
for (_, id) in candidates {
if let Some(family) = first_color_family(db, std::iter::once(id)) {
return Some(family);
}
}
None
}
fn has_color_table(data: &[u8], index: u32) -> bool {
const COLOR_TABLES: [&[u8]; 4] = [b"COLR", b"CBDT", b"sbix", b"SVG "];
let read_u16 = |at: usize| -> Option<u16> {
let bytes = data.get(at..at.checked_add(2)?)?;
Some(u16::from_be_bytes([bytes[0], bytes[1]]))
};
let read_u32 = |at: usize| -> Option<u32> {
let bytes = data.get(at..at.checked_add(4)?)?;
Some(u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
};
let mut directory = 0usize;
if data.get(0..4) == Some(b"ttcf".as_slice()) {
let Some(count) = read_u32(8) else {
return false;
};
if index >= count {
return false;
}
let Some(offset) = read_u32(12 + index as usize * 4) else {
return false;
};
directory = offset as usize;
}
let Some(num_tables) = read_u16(directory + 4) else {
return false;
};
(0..num_tables as usize).any(|table| {
let record = directory + 12 + table * 16;
data.get(record..record + 4)
.is_some_and(|tag| COLOR_TABLES.contains(&tag))
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn option_presets_say_what_they_mean() {
let options = ShapingOptions::default();
assert!(options.enabled);
assert!(options.system_fonts);
assert!(!ShapingOptions::disabled().enabled);
assert!(ShapingOptions::deterministic().enabled);
assert!(!ShapingOptions::deterministic().system_fonts);
assert!(!ShapingOptions::default().with_enabled(false).enabled);
assert!(
!ShapingOptions::default()
.with_system_fonts(false)
.system_fonts
);
assert_eq!(ShapingOptions::deterministic().locale(), "en-US");
}
#[test]
fn explicit_face_limit_rejects_oversized_collections() {
assert!(explicit_faces_fit(0, MAX_EXPLICIT_FACES));
assert!(explicit_faces_fit(MAX_EXPLICIT_FACES - 1, 1));
assert!(!explicit_faces_fit(MAX_EXPLICIT_FACES, 1));
assert!(!explicit_faces_fit(1, MAX_EXPLICIT_FACES));
assert!(!explicit_faces_fit(usize::MAX, 1));
}
#[test]
fn cache_limits_cover_failed_glyphs_as_well_as_bitmap_bytes() {
assert!(!glyph_cache_full(0, 0));
assert!(glyph_cache_full(MAX_GLYPH_CACHE_ENTRIES, 0));
assert!(glyph_cache_full(0, MAX_GLYPH_CACHE_BYTES));
}
#[test]
fn supported_width_contiguous_runs_are_never_split() {
let arabic = vec![
RunCell {
text: "\u{0645}".to_string(),
cols: 1,
};
500
];
let emoji = vec![
RunCell {
text: "\u{1F600}".to_string(),
cols: 2,
};
500
];
assert_eq!(run_chunk_limit(&arabic), 512);
assert_eq!(run_chunk_limit(&emoji), 256);
}
#[test]
fn a_plain_font_has_no_color_table() {
let data = std::fs::read("fonts/JetBrainsMono-Regular.ttf").expect("embedded font");
assert!(!has_color_table(&data, 0));
}
#[test]
fn malformed_font_data_is_rejected_rather_than_panicking() {
assert!(!has_color_table(&[], 0));
assert!(!has_color_table(b"ttcf", 0));
assert!(!has_color_table(b"ttcf\x00\x01\x00\x00\x00\x00\x00\x01", 0));
assert!(!has_color_table(b"\x00\x01\x00\x00\xff\xff", 0));
assert!(!has_color_table(b"\x00\x01\x00\x00\x00\x01\x00\x00", 7));
}
#[test]
fn a_byte_maps_to_the_cell_that_contributed_it() {
let ranges = vec![0..1, 1..4, 4..5];
assert_eq!(cell_of_byte(&ranges, 0), 0);
assert_eq!(cell_of_byte(&ranges, 2), 1);
assert_eq!(cell_of_byte(&ranges, 4), 2);
assert_eq!(cell_of_byte(&ranges, 99), 2);
}
}