docs: explain text flow cursors and viewport hit indexing

This commit is contained in:
2026-11-12 19:07:30 +08:00
parent 9517053a75
commit c28c08a29a
2 changed files with 63 additions and 1 deletions
+45
View File
@@ -1,69 +1,100 @@
//! Width-independent word preparation and variable-width line filling. The
//! exclusion algorithm owns geometry; this module only consumes text in order.
//! graphics 的 Prepare 在这里生成可复用词/字素图像,Flow 每行提供避让后的区间,由 row 按文本顺序消费。
//! 字形资源不随列宽重新生成;Cursor 属于每次 Flow,放不下的内容留待后续区间或下一行。
use crate::{display_list::Color, geometry::Rect, render::image::Image, text::TextStyle};
use std::{collections::HashMap, sync::Arc};
use unicode_segmentation::UnicodeSegmentation;
#[derive(Debug)]
/// 一段文字的不可变墨迹资源;整词和单字素都用同一结构,graphics::flow 按 Placement 引用它生成图片命令。
pub struct Ink {
// Image::text 产生的 RGBA 图片;Arc 允许重复文本和多次 Flow 共享像素,不为每个摆放位置复制。
pub image: Arc<Image>,
// 图片相对文字原点的逻辑矩形,包含负方向字形留白;不能只按 advance 宽度当作图片框。
pub rect: Rect,
// 字体测量的逻辑 advance,排版推进使用它;图片像素宽度还包含 scale 与留白。
pub width: f32,
}
#[derive(Debug)]
/// Unicode 换行机会之间的文字段,不只代表英文词;同时保留整段墨迹和按字素拆分的后备墨迹。
pub struct Word {
// 能完整容纳时使用整段图像,保留整段整形的字距与连字效果。
pub ink: Arc<Ink>,
// 按扩展字素簇生成的资源,避免拆开组合音标或 emoji;拆分模式的宽度来自逐字素独立测量。
pub letters: Vec<Arc<Ink>>,
// 该段末尾空白的逻辑测量宽度,放完正文后推进 x;换行符不参与这份空白测量。
pub space: f32,
// 原段以换行符结尾,消费完该段就结束当前 row,即使本行还有其他可用区间。
pub newline: bool,
}
#[derive(Debug)]
/// 与列宽无关的预排资源;graphics 的 TextResource 持有 Arc<Prepared>,每次 Flow 单独创建游标。
pub struct Prepared {
pub words: Vec<Word>,
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
/// 下一个待消费段及段内字素位置;Default 从 (0,0) 开始,跨一行的多个区间和后续行持续推进。
pub struct Cursor {
pub word: usize,
// 为零表示尚未拆分/位于段首,非零表示前面字素已放置,不能再回头画整词。
pub letter: usize,
}
/// row 追加的纯几何结果,graphics::flow 随后转为 PaintCommand;不在排版循环内分配托管命令对象。
pub struct Placement {
pub word: usize,
// None 指整词墨迹,Some 指该词某一字素;不能把整词位置再当成已经拆分的单字素。
pub letter: Option<usize>,
// 本次 Flow 坐标空间中的文字逻辑原点;实际图片命令还会叠加 Ink.rect 的留白偏移。
pub x: f32,
pub y: f32,
}
impl Prepared {
/// graphics 的 Prepare 分支在校验文本长度、样式和设备比例后调用;这里再限制本份预排图片累计像素。
pub fn new(
value: &str,
style: TextStyle,
scale: f32,
color: Color,
) -> Result<Self, &'static str> {
// 缓存只在这一份 Prepared 构造期间存在,按文本复用整词/字素资源;同文样式固定,无需额外样式键。
let mut cache: HashMap<String, Arc<Ink>> = HashMap::new();
// 累计唯一墨迹图片面积,u64 乘法避免在统计前溢出;重复文本命中不重复计费。
let mut pixels = 0_u64;
// 整段和字素走同一图片构造闭包,共享资源检查与去重,不另外维护两套缓存。
let mut ink = |text: &str| -> Result<Arc<Ink>, &'static str> {
// 重复内容直接克隆 Arc;文本相同的段与字素也能共享同一张图。
if let Some(ink) = cache.get(text) {
return Ok(ink.clone());
}
// 先生成图像、逻辑留白框及 advance,再核算累计像素;单图自身预算由 Image::text 检查。
let (image, rect, width) = Image::text(text, style, scale, color)?;
pixels += u64::from(image.width) * u64::from(image.height);
// 超过本份预排的八百万级像素上限即返回错误,不发布部分 Prepared;本次生成图片也计入。
if pixels > 8_388_608 {
return Err("prepared text exceeds 8M pixel cache budget");
}
// 图片只封装一次,缓存和 Word 分别通过 Arc 保留;闭包的临时 HashMap 退出后资源仍由结果持有。
let ink = Arc::new(Ink { image, rect, width });
cache.insert(text.to_owned(), ink.clone());
Ok(ink)
};
let mut words = Vec::new();
// 保留段末换行符,使换行意图不会因分段丢失;空输入不产生任何 Word。
for para in value.split_inclusive('\n') {
// Unicode 换行迭代器给出字节结束位置,start 跟随推进以逐段切取 UTF-8 安全文本。
let mut start = 0;
// 使用每个换行机会作为可整段放置的单元;机会类型本身未参与判断,显式换行另由 newline 字段保留。
for (end, _) in unicode_linebreak::linebreaks(para) {
let part = &para[start..end];
// 把尾部空白与可见正文分开,正文生成墨迹,末尾空白只作为布局 advance。
let body = part.trim_end_matches(char::is_whitespace);
// 去除 CR/LF 后测尾部空白;没有把换行当成一行可绘制的空格宽度。
let space =
crate::text::measure(part[body.len()..].trim_matches(['\n', '\r']), style)
.width;
// 同时预生成整词和各字素;后续列宽或避让区间变化只改摆放,不再次调用字体栅格化。
words.push(Word {
ink: ink(body)?,
letters: body
@@ -81,6 +112,7 @@ impl Prepared {
/// The same cursor crosses left/right fragments. Narrow gaps never discard
/// a word; a word wider than every remaining fragment falls back to graphemes.
/// graphics::flow 对每条行带调用,ranges 由障碍几何计算并按从左到右给出;y 是整行文字原点纵坐标。
pub fn row(
&self,
cursor: &mut Cursor,
@@ -88,18 +120,25 @@ impl Prepared {
y: f32,
out: &mut Vec<Placement>,
) {
// 同一游标穿过一行所有碎片,ri 用于查看当前及后续区间原始宽度,防止过早拆词。
for (ri, &(left, right)) in ranges.iter().enumerate() {
// 进入新区间从左边界开始,上一碎片的横向剩余空间不累计到这里。
let mut x = left;
// 仍有未消费文本才尝试摆放;每个成功分支推进词或字素,放不下则 break 到下一区间。
while let Some(word) = self.words.get(cursor.word) {
// 空正文不生成 Placement,也不推进其 space;若是空白换行段则只消费它并结束当前行。
if word.letters.is_empty() {
cursor.word += 1;
cursor.letter = 0;
// 显式换行结束整个 row,不只是当前碎片;下次调用从下一个词继续。
if word.newline {
return;
}
continue;
}
// 取当前及后续区间的完整最大宽度,不是仅当前剩余 right-x;用来判断整词能否留给稍后碎片/行。
let remaining_max = ranges[ri..].iter().map(|(l, r)| r - l).fold(0., f32::max);
// 只有尚未拆分且当前余宽容得下整词才走整词模式,0.001 容差吸收浮点边界误差。
if cursor.letter == 0 && word.ink.width <= right - x + 0.001 {
out.push(Placement {
word: cursor.word,
@@ -107,15 +146,19 @@ impl Prepared {
x,
y,
});
// 推进正文宽度和尾空白,再跳到下一词;尾空白本身不会产生图片命令。
x += word.ink.width + word.space;
cursor.word += 1;
if word.newline {
return;
}
} else if cursor.letter == 0 && word.ink.width <= remaining_max + 0.001 {
// 整词有望放入某个完整剩余区间时先保留它,结束当前碎片尝试,不因当前余宽小就拆成字素。
break;
} else {
// 词过宽或已经拆分才逐字素继续;这个分支保留跨碎片/跨行的 letter 下标。
let letter = &word.letters[cursor.letter];
// 连一个完整字素也放不下时不丢字,转到后续区间;若所有行都放不下,由外层高度预算结束 Flow。
if letter.width > right - x + 0.001 {
break;
}
@@ -125,8 +168,10 @@ impl Prepared {
x,
y,
});
// 成功放置一个字素后才递增游标,同一段的后续字素从新 x 继续。
x += letter.width;
cursor.letter += 1;
// 最后字素放完才消费尾空白并推进词;复位 letter,让下一词仍有整词放置机会。
if cursor.letter == word.letters.len() {
cursor.word += 1;
cursor.letter = 0;
+18 -1
View File
@@ -18,12 +18,16 @@ pub struct Index {
}
impl Index {
/// 从帧几何构建 128 单位屏幕网格;大对象、投影面板和超预算项进入保守后备集合。
// viewport::project 完成所有出现的变换/裁剪后调用,Frame 保存此纯原生索引供命中和相机目标查询。
pub fn build(mounts: &[MountGeometry]) -> Self {
// 保存原 mounts 数量用于查询时的基本一致性检查,格子与 fallback 初始为空。
let mut result = Self {
count: mounts.len(),
..Self::default()
};
// 累计格子内的下标引用数,不是不同格子数,也不是有效 Mount 数。
let mut entries = 0;
// index 始终指原帧数组位置,跳过不可参与输入的节点也不压缩/重排其他下标。
for (index, mount) in mounts.iter().enumerate() {
// 只有可交互项、场景视口或滚动容器需要参与输入目标宽阶段,其余外观节点跳过。
if !mount.interactive
@@ -63,6 +67,7 @@ impl Index {
result.fallback.push(index);
continue;
}
// 将裁剪后的屏幕界转换为格子边界,右下边界也包含以保守覆盖几何边缘。
let (left, top, right, bottom) = (cell(x0), cell(y0), cell(x1), cell(y1));
// 用 i64 计算格子跨度和饱和乘积,避免极大矩形在预算检查前发生算术溢出。
let cells = (i64::from(right) - i64::from(left) + 1)
@@ -72,8 +77,11 @@ impl Index {
result.fallback.push(index);
continue;
}
// 只有真正入网的项计入引用预算,fallback 不展开格子,因此不会被巨大矩形撑大索引。
entries += cells;
// 二维范围最多展开 256 格,同一出现可进入多格,每格内仍按原帧顺序追加。
for x in left..=right {
// 把当前原帧下标登记到每个覆盖格,查询点随后只需读取一格加 fallback。
for y in top..=bottom {
result.cells.entry((x, y)).or_default().push(index);
}
@@ -82,22 +90,26 @@ impl Index {
result
}
/// 返回当前网格格子与后备集合中的候选,去重并恢复逆绘制顺序。
// Frame 的 hit_test/camera_at 查询调用;返回的是保守下标集,调用方仍需检查实际几何、裁剪和资格。
pub fn candidates(&self, point: Point, count: usize) -> Vec<usize> {
// 索引总数与当前帧不一致时,下标集合不再可靠;直接返回整帧逆序候选。
if self.count != count {
return (0..count).rev().collect();
}
// 每次先复制全部后备下标,3D 面板必须保留给射线精确阶段,不能用二维格子筛掉。
let mut output = self.fallback.clone();
// 常规候选只来自指针当前格,未命中格子不影响后备集合继续参与。
if let Some(items) = self.cells.get(&(cell(point.x), cell(point.y))) {
output.extend(items);
}
// 按下标降序还原从前景到背景的绘制顺序;去重确保同一出现不会重复执行 hitTest。
// 按下标降序还原从前景到背景的绘制顺序;去重避免同一出现被调用方重复精确检查。
output.sort_unstable_by(|a, b| b.cmp(a));
output.dedup();
output
}
}
/// 把屏幕坐标映射到有界整数网格坐标,处理负方向与极端数值。
// build 转换矩形边界与 candidates 转换查询点共用,保证负坐标和格子边界使用相同规则。
fn cell(value: f32) -> i32 {
// 每格 128 个屏幕单位;floor 让 -1 属于负格而不是零格,再限制到整数表示范围。
(value / 128.)
@@ -111,6 +123,7 @@ mod tests {
#[test]
/// 200个分散节点只返回局部网格候选;覆盖海量格的巨大前景节点进入后备集合后仍按前景顺序参与精确命中。
fn screen_grid_limits_candidates_and_keeps_huge_rectangles_hittable() {
// 借真实 ReplSession 生成交互 Mount 模板,确保测试几何包含生产路径所需字段,而非手写近似结构。
let (_, document) = crate::endor_host::ReplSession::load(
"page=Page()\npage.render(Button(\"hit\"))",
"app.main",
@@ -118,13 +131,16 @@ mod tests {
930,
)
.unwrap();
// 从真实文档挑一个可交互出现,随后只替换矩形、变换和裁剪以隔离网格筛选行为。
let template = document
.frame
.mounts
.iter()
.find(|mount| mount.interactive)
.unwrap();
// 保留原帧下标 0..199,每项横向间隔 400,大于 128 格宽,让原点只查到局部候选。
let mut mounts = Vec::new();
// 所有模板都清除视图与 clip,避免旧页面投影影响这组人工屏幕坐标。
for index in 0..200 {
let mut mount = template.clone();
mount.x = index as f32 * 400.;
@@ -135,6 +151,7 @@ mod tests {
mount.clip = None;
mounts.push(mount);
}
// 首次构建检查普通项的局部筛选,随后扩大最后一个出现并重建,验证超预算降级不漏目标。
let index = Index::build(&mounts);
assert_eq!(index.candidates(Point::new(5., 5.), mounts.len()), vec![0]);
// 把最前景节点扩大到覆盖海量格子,验证其进入后备集合后仍排在普通候选之前且可精确命中。