docs: explain intrinsic visual paths and shared font cache lifetimes
This commit is contained in:
@@ -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::<Result<Vec<_>, _>>()?
|
||||
};
|
||||
// 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 }) {
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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<usize> {
|
||||
// 索引总数与当前帧不一致时,下标集合不再可靠;直接返回整帧逆序候选。
|
||||
// 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))) {
|
||||
|
||||
Reference in New Issue
Block a user