Zayden-Jung/endorphin-tessera-gui
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: explain text shaping and viewport projection flows

Browse Source
This commit is contained in:
Codex Bot
2026-11-12 19:04:37 +08:00
parent 03241d4ac1
commit 9517053a75
2 changed files with 108 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/render/text.rs
+57
View File
@@ -14,6 +14,7 @@ use crate::display_list::Color;
#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
/// 界面比例字体与源码等宽字体的选择，不直接指定某个必然安装的系统字体。
// TextStyle 携带字体选择，TextEngine::prepare_width 将其解析为实际字体族；Custom ID 由 register_font 返回。
pub enum TextFamily {
Interface,
Code,
@@ -24,6 +25,7 @@ pub enum TextFamily {
#[derive(Clone, Copy, Debug)]
/// 字号、行高和字体类别，测量与绘制必须使用兼容样式。
pub struct TextStyle {
// 目标坐标空间中的字体像素尺寸；scaled 同时缩放它与 line_height，以保持排版比例。
pub font_size: f32,
pub line_height: f32,
pub family: TextFamily,
@@ -31,6 +33,7 @@ pub struct TextStyle {
impl TextStyle {
/// 生成界面文字的基准字号与行高，size 是协议使用的字号倍率。
// 布局默认文本与宿主 UI 使用，协议等级乘基础 14/20 得到字号及行高；构造本身不验证等级范围。
pub fn ui(size: u32) -> Self {
Self {
font_size: 14.0 * size as f32,
@@ -40,6 +43,7 @@ impl TextStyle {
}
/// 生成源码/Console 使用的等宽风格基础尺寸。
// 侧栏、Console 和源码预览使用的等宽样式，实际字体由引擎启动时发现。
pub fn code() -> Self {
Self {
font_size: 13.0,
@@ -49,6 +53,7 @@ impl TextStyle {
}
/// 同比缩放字号与行高，保持设备比例变化后的排版比例一致。
// display_list 的设备比例、页面缩放和 draw_clipped 的字形 LOD 都用同一缩放操作。
pub fn scaled(self, scale: f32) -> Self {
Self {
font_size: self.font_size * scale,
@@ -68,6 +73,7 @@ pub struct TextSize {
#[derive(Clone, Hash, PartialEq, Eq)]
/// 文字整形缓存键，包含文本、样式和可选换行宽度。
struct TextKey {
// 缓存拥有文本副本，命中比较全部文本内容；不会借用源文件或 VM 字符串的生命周期。
value: String,
// 用浮点原始位模式做键，精确区分整形参数；不是把字号取整为 u32。
font_size: u32,
@@ -86,8 +92,10 @@ struct PreparedText {
/// 共享字体系统、字形缓存和整形缓存；调用通过全局锁串行访问。
struct TextEngine {
fonts: FontSystem,
// 已注册字体族名与内容哈希，数组下标就是 TextFamily::Custom ID，最多保留 32 个族。
custom: Vec<(String, u64)>,
code_family: Option<String>,
// 字形栅格缓存与整段 Buffer 缓存分开维护，draw_clipped 根据位图条数/字节量整批清理。
swash: SwashCache,
buffers: HashMap<TextKey, PreparedText>,
// 累计缓存文本的 UTF-8 字节数，只衡量源文本预算，并非 Buffer/字形的总内存。
@@ -96,6 +104,7 @@ struct TextEngine {
impl TextEngine {
/// 扫描系统字体，选择可用的界面/等宽字体偏好，并建立空整形和栅格缓存。
// engine 的 OnceLock 首次使用时调用，加载系统字体只做一次，测量与绘制随后共享此实例。
fn new() -> Self {
let mut fonts = FontSystem::new();
// Select installed, readable families rather than assuming an OS font
@@ -110,6 +119,7 @@ impl TextEngine {
.then(|| (*choice).to_owned())
})
};
// 界面族按安装情况选第一个可用偏好，不保证每个平台得到同一个字体或相同逐像素结果。
let sans = choose(&[
".AppleSystemUIFont",
"SF Pro Text",
@@ -119,10 +129,13 @@ impl TextEngine {
"DejaVu Sans",
"Liberation Sans",
]);
// 保留等宽族名供 Code 使用；不存在偏好族时回退 FontSystem 的 Monospace。
let mono = choose(&["Menlo", "Consolas", "DejaVu Sans Mono", "Liberation Mono"]);
// 只有找到已安装的偏好族才替换字体库默认 sans-serif 配置。
if let Some(name) = sans {
fonts.db_mut().set_sans_serif_family(name);
}
// 代码族配置与保存的 code_family 保持一致，具体字符缺失仍由整形系统做字体回退。
if let Some(name) = &mono {
fonts.db_mut().set_monospace_family(name);
}
@@ -137,11 +150,13 @@ impl TextEngine {
}
/// 对不指定换行宽度的文本复用统一整形准备过程。
// measure 的无换行入口，实际整形和缓存逻辑统一委托 prepare_width，避免另建自然宽度算法。
fn prepare(&mut self, value: &str, style: TextStyle) -> TextKey {
self.prepare_width(value, style, None)
}
/// 为文本、字体样式和可选换行宽度建立整形缓存，超过缓存预算先清理旧结果。
// measure_wrapped 和 draw_clipped 共用；调用方已持引擎锁，返回键可直接用于访问 buffers 中的结果。
fn prepare_width(&mut self, value: &str, style: TextStyle, wrap_width: Option<f32>) -> TextKey {
// 键包含全部排版输入；命中后测量与绘制都复用同一 Buffer，避免两套排版产生偏差。
let key = TextKey {
@@ -151,6 +166,7 @@ impl TextEngine {
family: style.family,
wrap_width: wrap_width.map(f32::to_bits),
};
// 完全相同的文本、样式与宽度复用已整形 Buffer，返回前不再次累计 source_bytes。
if self.buffers.contains_key(&key) {
return key;
}
@@ -161,6 +177,7 @@ impl TextEngine {
self.buffers.clear();
self.source_bytes = 0;
}
// Custom 直接用注册 ID 查族名，因此调用方应只使用 register_font 返回的有效 ID。
let family = match style.family {
TextFamily::Interface => Family::SansSerif,
TextFamily::Custom(id) => Family::Name(&self.custom[id as usize].0),
@@ -171,6 +188,7 @@ impl TextEngine {
.as_deref()
.map_or(Family::Monospace, Family::Name),
};
// 先建立对应字体尺寸/行高的 Buffer，再设置换行宽度、文本和对齐，最后执行整形。
let mut buffer = Buffer::new(
&mut self.fonts,
Metrics::new(style.font_size, style.line_height),
@@ -196,10 +214,12 @@ impl TextEngine {
width: 0.0,
height: style.line_height,
};
// 逐行汇总最大实际宽度和最下行底，不按字符数量估算中文、比例字或换行高度。
for run in buffer.layout_runs() {
size.width = size.width.max(run.line_w);
size.height = size.height.max(run.line_top + run.line_height);
}
// 只在新整形条目插入时累计源文本字节；返回克隆键供调用方马上取测量值或字形。
self.source_bytes += value.len();
self.buffers
.insert(key.clone(), PreparedText { buffer, size });
@@ -215,13 +235,16 @@ fn engine() -> &'static Mutex<TextEngine> {
}
/// 返回不受换行宽度约束时的字体整形尺寸。
// layout 的原生文本测量、宿主控件尺寸及 fit 的宽度比较共用此入口，不设置自动换行宽度。
pub fn measure(value: &str, style: TextStyle) -> TextSize {
let mut engine = engine().lock().expect("text engine lock");
// prepare 确保当前缓存里存在此键，借用的 size 可复制返回而不把 Buffer 或锁带给调用方。
let key = engine.prepare(value, style);
engine.buffers[&key].size
}
/// 按可用宽度整形并测量多行高度，供布局与实际段落绘制共用。
// layout 在内容宽度约束下调用，完整段落高度用于布局；屏幕 clip 不影响测量宽度或行数。
pub fn measure_wrapped(value: &str, style: TextStyle, width: f32) -> TextSize {
// 零或负可用宽度直接返回零宽与一行高，避免给整形器无效换行宽度。
if width <= 0.0 {
@@ -239,6 +262,7 @@ pub fn measure_wrapped(value: &str, style: TextStyle, width: f32) -> TextSize {
/// bitmap and sample it at the requested size instead of allocating an enormous
/// font image. Layout and wrapping still use proportionally identical metrics.
/// 限制字形分辨率并只采样可见像素；保留文字布局比例，同时避免极端相机缩放产生巨型位图。
// software_renderer 的普通/换行文字路径调用，clip 和回调坐标都相对文字原点，最终平移与混合由 Canvas 负责。
pub fn draw_clipped(
value: &str,
style: TextStyle,
@@ -247,6 +271,7 @@ pub fn draw_clipped(
clip: crate::geometry::Rect,
mut pixel: impl FnMut(i32, i32, Color),
) {
// 空裁剪或无效字号直接跳过，不进入字体锁和字形位图生成；其他样式约束由调用边界保证。
if clip.width <= 0.
|| clip.height <= 0.
|| !style.font_size.is_finite()
@@ -258,6 +283,7 @@ pub fn draw_clipped(
// 字体、行高和换行宽度一起缩小，后续用 1/lod 恢复目标几何比例。
let lod = (512. / style.font_size).min(1.);
let mut engine = engine().lock().expect("text engine lock");
// 用同一 lod 缩放字号、行高和可选换行宽度，在低分辨率整形后以倒 lod 恢复输出空间。
let key = engine.prepare_width(value, style.scaled(lod), width.map(|width| width * lod));
// 拆借可变字段以便在保留 Buffer 借用时访问字体和 Swash 缓存，不复制整形结果。
let TextEngine {
@@ -266,6 +292,7 @@ pub fn draw_clipped(
buffers,
..
} = &mut *engine;
// 以下遍历只读已整形 Buffer，同时分开借用 fonts/swash 生成字形，不克隆整段布局。
let buffer = &buffers[&key].buffer;
// 从已有 image_cache 统计位图字节；不包含整形 Buffer，也不含字体数据库本身。
let mut cache_bytes: usize = swash
@@ -274,8 +301,10 @@ pub fn draw_clipped(
.flatten()
.map(|image| image.data.len())
.sum();
// 逐行保留基线位置，再逐个整形字形处理；一个源字素不一定对应一个渲染字形。
for run in buffer.layout_runs() {
for glyph in run.glyphs {
// 将字形布局转换为可缓存的物理位置/键，run.line_y 提供该行基线偏移。
let physical = glyph.physical((0., run.line_y), 1.);
// Conservative font-sized guard includes bearings/overhangs. The
// exact bitmap bounds below determine the actual visible pixels.
@@ -283,6 +312,7 @@ pub fn draw_clipped(
let guard = glyph.font_size * 4. / lod;
let gx = physical.x as f32 / lod;
let gy = physical.y as f32 / lod;
// 粗筛完全远离 clip 的字形可省下位图生成；通过粗筛后仍用实际 placement 做精确可见范围。
if gx + guard < clip.x
|| gx - guard > clip.x + clip.width
|| gy + guard < clip.y
@@ -296,10 +326,12 @@ pub fn draw_clipped(
cache_bytes = 0;
}
// 只对新生成的图像增加字节统计；缓存中的生成失败项由 None 跳过，不参与绘制。
// get_image 可能命中或新生成；只给新条目累加数据字节，避免重复命中把预算重复计费。
let cached = swash.image_cache.contains_key(&physical.cache_key);
let Some(image) = swash.get_image(fonts, physical.cache_key) else {
continue;
};
// 生成成功才增加位图数据长度；无可用图像的字形在上面 None 分支直接跳过。
if !cached {
cache_bytes += image.data.len();
}
@@ -322,6 +354,7 @@ pub fn draw_clipped(
.min(image.placement.width.saturating_sub(1));
let v = (((y as f32 + 0.5 - top) * lod) as u32)
.min(image.placement.height.saturating_sub(1));
// u/v 是位图内像素下标，先计算单像素索引；不同 content 分支再决定每像素字节数。
let index = (v * image.placement.width + u) as usize;
// 灰度 Mask 把覆盖率乘整体 alpha；Color 保留位图 RGB 并乘其 alpha。
// SubpixelMask 不适用此软件合成路径，直接跳过。
@@ -332,6 +365,7 @@ pub fn draw_clipped(
base.blue,
(u16::from(image.data[index]) * u16::from(color.alpha) / 255) as u8,
),
// 彩色字形每像素占 RGBA 四字节，保留位图 RGB 而非普通文字的 base RGB。
cosmic_text::SwashContent::Color => {
let i = index * 4;
Color::rgba(
@@ -353,6 +387,7 @@ pub fn draw_clipped(
/// Fit a single displayed source line without slicing a UTF-8/grapheme cluster.
/// 按真实字体测量截断到给定宽度，以字素簇边界拼接省略号，避免切开组合字符。
// 侧栏和工具的单行展示调用，结果只用于预览；不会改源文本、AST 范围或编辑器存储。
pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
use unicode_segmentation::UnicodeSegmentation;
@@ -361,6 +396,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
// 仅预览截断至约 8 KiB 字素边界，不改保存的源码。单个超长字素也不能被拆开。
let truncated = value.len() > 8192;
let value = if truncated {
// 在 8 KiB 内选择最后一个字素起点作为切片边界，超长首字素可能让预览正文变空。
let end = value
.grapheme_indices(true)
.map(|(index, _)| index)
@@ -376,6 +412,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
return value.to_owned();
}
let ellipsis = "…";
// 没有正宽度或连省略号都放不下时返回空串，不输出超出分配宽度的占位符。
if width <= 0.0 || measure(ellipsis, style).width > width {
return String::new();
}
@@ -384,6 +421,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
.grapheme_indices(true)
.map(|(start, part)| start + part.len())
.collect();
// 二分上下界是完整字素数量，不是 UTF-8 字节数；真正切片位置由 ends 转换。
let mut low = 0;
let mut high = ends.len();
// 二分搜索可容纳的最长字素前缀；取上中位数使成功分支能推进 low，避免相邻边界时死循环。
@@ -392,6 +430,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
let end = ends[count - 1];
// 省略号也参与真实整形测量，不能简单从总宽度减去字符数估算。
let candidate = format!("{}{ellipsis}", &value[..end]);
// 每次候选连同省略号一起整形测量；成功提高下界，失败排除当前长度及更长候选。
if measure(&candidate, style).width <= width {
low = count;
} else {
@@ -405,19 +444,26 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
/// Register an explicit face for graphics resources. Repeated identical loads
/// reuse the family; conflicting content and unbounded global growth fail.
/// 注册显式字体族并返回稳定 ID；同名但内容哈希不同，或超过族数量预算时拒绝注册。
// graphics 的字体资源 API 读取有限字体数据后调用，返回可放入绘制样式的稳定族 ID。
pub fn register_font(bytes: Vec<u8>, family: &str) -> anyhow::Result<TextFamily> {
use std::hash::{Hash, Hasher};
// 内容哈希与族名用于重复注册检查，哈希留在内存中，不替代文件路径或字体族名。
let mut hash = std::collections::hash_map::DefaultHasher::new();
bytes.hash(&mut hash);
let hash = hash.finish();
// 字体注册与整形/绘制共用全局锁，修改字体数据库期间不会有另一调用同时使用旧数据库。
let mut e = engine().lock().expect("text engine lock");
// 同名同哈希复用原 ID，同名不同内容直接报错，不替换已经发布给样式的字体身份。
if let Some((id, (_, old))) = e.custom.iter().enumerate().find(|(_, v)| v.0 == family) {
anyhow::ensure!(*old == hash, "font family already has different content");
return Ok(TextFamily::Custom(id as u32));
}
anyhow::ensure!(e.custom.len() < 32, "font registry exceeds 32 families");
// 保存数据库副本用于请求族名验证失败时回滚；成功注册才写 custom 和清整形缓存。
let previous = e.fonts.db().clone();
e.fonts.db_mut().load_font_data(bytes);
// 加载后检查字体库是否存在请求族名；这里按整个库查询，不是单独解析此次文件的族名列表。
if !e
.fonts
.db()
@@ -427,6 +473,7 @@ pub fn register_font(bytes: Vec<u8>, family: &str) -> anyhow::Result<TextFamily>
*e.fonts.db_mut() = previous;
anyhow::bail!("font data does not contain requested family");
}
// 尾部追加保持既有 ID 不变；字体库变化后旧 Buffer 可能引用旧选择，因此清空整形结果。
let id = e.custom.len() as u32;
e.custom.push((family.into(), hash));
e.buffers.clear();
@@ -443,6 +490,7 @@ mod tests {
/// 用一万倍缩放检验绘制回调被限制在32x32裁剪内，同时检查字形缓存字号不超过512以控制中间资源。
fn extreme_zoom_rasterizes_only_the_clip_with_bounded_glyph_sizes() {
// 极端缩放测试限制实际回调在 32×32 裁剪区，同时检查缓存字号不超过 512。
// 统计实际输出回调数，坐标断言验证只遍历 32×32 可见区域，不按巨型字形面积扫描。
let mut count = 0;
draw_clipped(
"M",
@@ -457,6 +505,7 @@ mod tests {
},
);
assert_eq!(count, 1024);
// 绘制结束已释放全局锁，再获取它检查真实字形缓存键中的字号，而非只看局部 lod 变量。
let engine = engine().lock().unwrap();
assert!(
engine
@@ -473,6 +522,7 @@ mod tests {
let style = TextStyle::ui(1);
// 混合中文、长英文词、组合字符和 emoji，验证窄/宽换行缓存隔离且不改变无换行测量结果。
let text = "中文段落 with words and long_unbroken_identifier é 👩‍💻 中文段落";
// 先记录无约束宽度，再分别测窄宽段落，验证两套缓存不会污染自然宽度。
let intrinsic = measure(text, style);
let narrow = measure_wrapped(text, style, 70.0);
let wide = measure_wrapped(text, style, 240.0);
@@ -481,7 +531,9 @@ mod tests {
assert!(narrow.width <= 70.1);
assert_eq!(measure(text, style).width, intrinsic.width);
assert_eq!(measure_wrapped(text, style, 0.0).width, 0.0);
// 检查真实缓存键和 Buffer 高度，除了测量结果还验证宽度确实参与缓存区分。
let mut engine = engine().lock().unwrap();
// 文本与样式相同，仅 Some(width) 不同，键及排版高度都应不同。
let narrow_key = engine.prepare_width(text, style, Some(70.0));
let wide_key = engine.prepare_width(text, style, Some(240.0));
assert!(narrow_key != wide_key);
@@ -497,6 +549,7 @@ mod tests {
let mono = TextStyle::code();
assert!((measure("WWWW", mono).width - measure("iiii", mono).width).abs() < 0.1);
assert_eq!(measure("one\ntwo", ui).height, ui.line_height * 2.0);
// 以实际整形结果为基准检查同比例字号的宽度变化，容许少量字体整形舍入差异。
let width = measure("Hello Endor", ui).width;
assert!((measure("Hello Endor", ui.scaled(1.25)).width - width * 1.25).abs() < 0.5);
}
@@ -506,8 +559,10 @@ mod tests {
fn system_fallback_shapes_chinese_without_missing_glyphs() {
let mut engine = engine().lock().unwrap();
// 两种字体风格都要求四个中文字符生成非零 glyph_id，确保系统回退实际找到了字形。
// 界面与代码字体各检查一次中文回退，缺少环境 CJK 字体时该测试会暴露缺字，不能只凭非零宽度判断。
for style in [TextStyle::ui(1), TextStyle::code()] {
let key = engine.prepare("中文字体", style);
// 直接查看整形 glyph_id，ID=0 表示缺字；中文用例期望四个字符各有可用字形。
let glyphs: Vec<_> = engine.buffers[&key]
.buffer
.layout_runs()
@@ -523,10 +578,12 @@ mod tests {
/// 按实际测量宽度截断带组合字符的文本，结果需是原文字素边界前缀加省略号，且整体不超宽。
fn ellipsis_fits_actual_width_and_preserves_graphemes() {
let style = TextStyle::code();
// 短代码行能完全放下时应原样返回，随后再测试带组合音标的必须截断输入。
let short_source = "let s = ui.text(\"中文字体\")";
assert_eq!(fit(short_source, 365.0, style), short_source);
let value = "e\u{301}e\u{301}中文字体e\u{301}e\u{301}";
let width = measure("e\u{301}e\u{301}中…", style).width + 0.01;
// 目标宽度来自已知带省略号文本的真实测量，加少量余量避免边缘舍入影响判断。
let fitted = fit(value, width, style);
// 检查结果前缀确实来自原文且结束于字素边界，而不仅是合法 UTF-8 字节边界。
let prefix = fitted.strip_suffix('…').unwrap();