From cd0f292b7885285bffbe47c476ed13942276ece0 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 20:46:56 +0800 Subject: [PATCH] docs: explain intrinsic visual paths and shared font cache lifetimes --- src/render/native_visual.rs | 4 ++++ src/render/text.rs | 9 +++++++++ src/render/viewport/spatial.rs | 3 +++ 3 files changed, 16 insertions(+) diff --git a/src/render/native_visual.rs b/src/render/native_visual.rs index 69d1bcf..acff200 100644 --- a/src/render/native_visual.rs +++ b/src/render/native_visual.rs @@ -60,6 +60,7 @@ pub(crate) fn value(value: f32) -> Value { Value::Number((value as f64).into()) } /// 新建指定名义类型的托管记录,并逐项设置字段,作为视觉协议的结果返回。 +/// 默认协议、graphics 和 Window 查询等原生入口共用;这里只附类型/写字段,结果几何与列表成员的语义仍由消费者解码验证。 pub(crate) fn record( cx: &mut NativeContext<'_>, desktop: ObjectRef, @@ -185,6 +186,7 @@ impl NativeCallable for Method { // 复制最后提交几何,只有非 staged 的命中/独立调用使用这份出现值。 let geometry = mount.geometry.clone(); // 布局阶段从临时 Context 取当前节点、孩子实测尺寸与首选尺寸;克隆派生数据后释放锁再进行计算。 + // 源覆盖显式调用 Block.measure/arrange 时也会进入这里,必须沿用本轮子测量,不能重新用默认算法覆盖源孩子的返回值。 let staged = mount .layout .as_ref() @@ -303,6 +305,7 @@ impl NativeCallable for Method { .collect::, _>>()? }; // preferred 保留弹性分配所需首选大小,与已受约束的实测 children 区分;无 staged 时两者相同。 + // 收敛循环可能反复改变 children 的分配,preferred 不随每轮分配累计变化,避免 flex 把上轮结果当新自然基准。 let preferred = staged .as_ref() .map_or(children.as_slice(), |(_, _, preferred)| { @@ -357,6 +360,7 @@ impl NativeCallable for Method { return Err(invalid("visual bounds exceed limits")); } // 本次 paint 的派生结果集合,不能包含运行时可变 VM 场景对象。 + // 普通原生 paint 可由 source_paint 快速路径直接保留默认命令;源覆盖调用基类 paint 时才需要这里反向编码为托管结果。 let mut commands = Vec::new(); // 将 Rust 默认绘制命令反向编码成源 PaintCommand,允许源覆盖方法调用基类 paint 后继续组合。 for command in layout::paint_commands(&node, x, y, Size { width, height }) { diff --git a/src/render/text.rs b/src/render/text.rs index 2fe5bf5..d8a1eb8 100644 --- a/src/render/text.rs +++ b/src/render/text.rs @@ -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, // 字形栅格缓存与整段 Buffer 缓存分开维护,draw_clipped 根据位图条数/字节量整批清理。 swash: SwashCache, + // 文本、浮点样式和换行宽度完整匹配才复用 Buffer;整批清理后不保留逐 VM 的历史缓存。 buffers: HashMap, // 累计缓存文本的 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, family: &str) -> anyhow::Result { + // 引擎和 32 族配额属于整个进程,关闭或替换某个 VM 不会清此注册表;资源句柄只保存返回的 Custom ID。 use std::hash::{Hash, Hasher}; // 内容哈希与族名用于重复注册检查,哈希留在内存中,不替代文件路径或字体族名。 let mut hash = std::collections::hash_map::DefaultHasher::new(); diff --git a/src/render/viewport/spatial.rs b/src/render/viewport/spatial.rs index 49a48f5..c1a314f 100644 --- a/src/render/viewport/spatial.rs +++ b/src/render/viewport/spatial.rs @@ -1,5 +1,6 @@ //! 有界屏幕网格,用来减少普通二维命中和相机目标查询的候选。 //! 巨大对象和 3D 面板进入后备集合,再由精确命中判断;索引预算不足不能导致遗漏目标。反序列化或索引长度不匹配时可退回完整候选。 +//! 此处“屏幕”指已应用 Mount.view 的页面内部坐标,不含旧 Page Surface、设备 DPI 和宿主侧栏偏移;外层输入先撤销这些变换再查询。 //! //! Bounded screen-space broad phase. Projective world UI uses the precise //! ray-based narrow phase rather than an unsafe screen rectangle approximation. @@ -93,10 +94,12 @@ impl Index { // Frame 的 hit_test/camera_at 查询调用;返回的是保守下标集,调用方仍需检查实际几何、裁剪和资格。 pub fn candidates(&self, point: Point, count: usize) -> Vec { // 索引总数与当前帧不一致时,下标集合不再可靠;直接返回整帧逆序候选。 + // count 只能发现数量变化;若调用方原地移动同数量的 Mount,也必须重建索引,不能依赖这项检查自动识别陈旧几何。 if self.count != count { return (0..count).rev().collect(); } // 每次先复制全部后备下标,3D 面板必须保留给射线精确阶段,不能用二维格子筛掉。 + // 返回顺序必须与索引建立时的 mounts 数组一致;这里只交还下标,不持有也不复制 MountGeometry。 let mut output = self.fallback.clone(); // 常规候选只来自指针当前格,未命中格子不影响后备集合继续参与。 if let Some(items) = self.cells.get(&(cell(point.x), cell(point.y))) {