docs: explain intrinsic visual paths and shared font cache lifetimes

This commit is contained in:
2026-11-12 20:46:56 +08:00
parent afff46c0a8
commit cd0f292b78
3 changed files with 16 additions and 0 deletions
+9
View File
@@ -27,7 +27,9 @@ pub enum TextFamily {
pub struct TextStyle {
// 目标坐标空间中的字体像素尺寸;scaled 同时缩放它与 line_height,以保持排版比例。
pub font_size: f32,
// 基线之间的布局高度,随同 font_size 缩放;空文本的测量也至少保留这一行高度。
pub line_height: f32,
// 字体发现策略或 register_font 返回的进程级 Custom ID,不是某个 VM 的托管字体对象身份。
pub family: TextFamily,
}
@@ -66,7 +68,9 @@ impl TextStyle {
#[derive(Clone, Copy, Debug)]
/// 整形后实际占用的逻辑文字尺寸。
pub struct TextSize {
// 整形各行实际宽度的最大值;无换行与给定换行宽度的结果来自不同缓存键。
pub width: f32,
// 至少一行高,并覆盖最下方布局行的底部;屏幕裁剪不会截短这个测量结果。
pub height: f32,
}
@@ -91,12 +95,15 @@ struct PreparedText {
/// 共享字体系统、字形缓存和整形缓存;调用通过全局锁串行访问。
struct TextEngine {
// 全进程共享的系统/自定义字体库;Mutex 同时串行保护发现、注册、整形与栅格缓存访问。
fonts: FontSystem,
// 已注册字体族名与内容哈希,数组下标就是 TextFamily::Custom ID,最多保留 32 个族。
custom: Vec<(String, u64)>,
// 启动时选中的等宽族名;None 时使用 FontSystem 的 Monospace 策略并保留字符回退。
code_family: Option<String>,
// 字形栅格缓存与整段 Buffer 缓存分开维护,draw_clipped 根据位图条数/字节量整批清理。
swash: SwashCache,
// 文本、浮点样式和换行宽度完整匹配才复用 Buffer;整批清理后不保留逐 VM 的历史缓存。
buffers: HashMap<TextKey, PreparedText>,
// 累计缓存文本的 UTF-8 字节数,只衡量源文本预算,并非 Buffer/字形的总内存。
source_bytes: usize,
@@ -280,6 +287,7 @@ pub fn draw_clipped(
return;
}
// 超大字号按比例降到最高 512 再栅格化;普通字号保持 1。
// LOD 限制的是中间字形位图分辨率;输出坐标仍按请求尺寸采样,既不是把页面缩小,也不改变调用方布局盒的尺寸。
// 字体、行高和换行宽度一起缩小,后续用 1/lod 恢复目标几何比例。
let lod = (512. / style.font_size).min(1.);
let mut engine = engine().lock().expect("text engine lock");
@@ -447,6 +455,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
/// 注册显式字体族并返回稳定 ID;同名但内容哈希不同,或超过族数量预算时拒绝注册。
// graphics 的字体资源 API 读取有限字体数据后调用,返回可放入绘制样式的稳定族 ID。
pub fn register_font(bytes: Vec<u8>, family: &str) -> anyhow::Result<TextFamily> {
// 引擎和 32 族配额属于整个进程,关闭或替换某个 VM 不会清此注册表;资源句柄只保存返回的 Custom ID。
use std::hash::{Hash, Hasher};
// 内容哈希与族名用于重复注册检查,哈希留在内存中,不替代文件路径或字体族名。
let mut hash = std::collections::hash_map::DefaultHasher::new();