188 lines
10 KiB
Rust
188 lines
10 KiB
Rust
//! 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 = ¶[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
|
|
.graphemes(true)
|
|
.map(&mut ink)
|
|
.collect::<Result<Vec<_>, _>>()?,
|
|
space,
|
|
newline: part.ends_with('\n'),
|
|
});
|
|
start = end;
|
|
}
|
|
}
|
|
Ok(Self { words })
|
|
}
|
|
|
|
/// 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,
|
|
ranges: &[(f32, f32)],
|
|
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,
|
|
letter: None,
|
|
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;
|
|
}
|
|
out.push(Placement {
|
|
word: cursor.word,
|
|
letter: Some(cursor.letter),
|
|
x,
|
|
y,
|
|
});
|
|
// 成功放置一个字素后才递增游标，同一段的后续字素从新 x 继续。
|
|
x += letter.width;
|
|
cursor.letter += 1;
|
|
// 最后字素放完才消费尾空白并推进词；复位 letter，让下一词仍有整词放置机会。
|
|
if cursor.letter == word.letters.len() {
|
|
cursor.word += 1;
|
|
cursor.letter = 0;
|
|
x += word.space;
|
|
if word.newline {
|
|
return;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|