docs: clarify layout bounds and retained image text flow

This commit is contained in:
2026-11-12 20:41:16 +08:00
parent 0c4bd06231
commit 45b0b53d4f
6 changed files with 21 additions and 2 deletions
+4
View File
@@ -95,6 +95,8 @@ impl Sizing {
/// 将 [最小宽, 最小高, 最大宽, 最大高] 收窄,供子内容测量和文本换行使用。
/// 固定尺寸限制最大可用空间;最后缩小最小约束以保持 min <= max。这里不直接计算最终盒子。
pub fn available(self, mut constraints: [f32; 4]) -> [f32; 4] {
// layout::shape/child_constraints 先调用这里;返回仍是边框盒约束,border/padding 由布局调用方随后扣除。
// Auto 的自身 min 不在这里抬高父最小值;最终 resolve 再应用自身 min/max,避免提前把内容测量冻结成分配尺寸。
// 先套自身 max,再应用 Fixed;Auto/Fill 在测量阶段保留父级允许的空间。
constraints[2] = constraints[2].min(self.max_width);
constraints[3] = constraints[3].min(self.max_height);
@@ -112,6 +114,7 @@ impl Sizing {
}
/// 结合内容期望尺寸、轴策略和父级约束求最终盒子尺寸;无界轴不能解析 fill。
/// layout::measure_shape 的 Shape::Sized 路径调用;intrinsic 已包含该形状的有效内缩量,不在这里重复加 padding/border。
pub fn resolve(self, intrinsic: Size, constraints: [f32; 4]) -> Result<Size> {
/// 针对单个尺寸轴应用约束与边界规则,供双轴尺寸求解复用。
fn axis(
@@ -137,6 +140,7 @@ impl Sizing {
}
};
// 先满足自身 min/max,再服从父级上限;父级空间比 min 小时,父级上限优先。
// min/max 的合法性由模型预检;这个数值助手不修复反向上下限,不能把任意未校验 Sizing 直接送进 clamp。
Ok(value.clamp(min, max).min(available))
}
// 横纵轴分别求解,只取父最大分配 constraints[2/3];输入的最小约束不在此额外强加。
+2
View File
@@ -45,6 +45,8 @@ impl Rect {
/// 用闭区间比较判断点是否命中,左右上下边缘都计入;调用前需将点转换到矩形所在空间。
pub fn contains(self, point: Point) -> bool {
// 闭区间四边比较;自身不处理裁剪叠加、圆角或世界面板遮挡,这些属于更上层命中流程。
// 相邻矩形共享边缘时两者都可命中,Frame/工具命中调用方按绘制顺序选目标;这里不负责消除重叠。
// 零宽/零高矩形也可能命中其线段/端点;要求正面积的裁剪或视口调用方必须另外判断尺寸。
point.x >= self.x
&& point.x <= self.x + self.width
&& point.y >= self.y
+5 -1
View File
@@ -62,8 +62,8 @@ impl Image {
// 灰度复制到 RGB,缺 alpha 填 255;若 Indexed 未展开则报错,不能把索引当颜色通道。
let rgba = match info.color_type {
// 原生四通道直接复制,保留源 alpha。
// 三通道图片默认全不透明,不从相邻像素误读 alpha。
png::ColorType::Rgba => [chunk[0], chunk[1], chunk[2], chunk[3]],
// 三通道图片默认全不透明,不从相邻像素误读 alpha。
png::ColorType::Rgb => [chunk[0], chunk[1], chunk[2], 255],
// 单灰度通道复制到三色,完全不透明。
png::ColorType::Grayscale => [chunk[0], chunk[0], chunk[0], 255],
@@ -95,6 +95,7 @@ impl Image {
color: Color,
) -> Result<(Arc<Self>, Rect, f32), &'static str> {
// 用逻辑 TextStyle 测量自然字形 advance/行高;返回 advance 不随设备 DPI 改变。
// 调用链 graphics::Prepare 已检查 scale/字号,Prepared::new 把同一份样式传入;此助手只另查单图像素预算。
let size = text::measure(value, style);
// 按字号预留约 30% 整数逻辑边距,容纳斜体/衬线伸出而不裁掉字形。
let pad = (style.font_size * 0.3).ceil();
@@ -127,6 +128,7 @@ impl Image {
// 行优先像素索引乘四得到 RGBA 字节起点,先通过上面坐标范围检查。
let i = (y as usize * width as usize + x as usize) * 4;
// All glyphs have the same ink color; alpha-over preserves overlaps.
// 相同墨色只覆盖 RGB,alpha 按新覆盖率 over 旧覆盖率合成,保留字形重叠处的覆盖,避免后画的抗锯齿边抹淡旧墨迹。
pixels[i..i + 3].copy_from_slice(&[c.red, c.green, c.blue]);
pixels[i + 3] = (u16::from(c.alpha)
+ u16::from(pixels[i + 3]) * (255 - u16::from(c.alpha)) / 255)
@@ -149,6 +151,7 @@ impl Image {
// 软件渲染器传入逆映射的归一化纹理点和已夹取 opacity;预乘 alpha 双线性插值后返回 straight RGBA。
pub fn sample(&self, u: f32, v: f32, opacity: f32) -> Color {
// draw_image 在目标局部矩形内算 u/v 后调用;本方法夹取采样邻居而非定义图像外透明区,不能代替目标覆盖范围检查。
// 归一化 u 映射到像素中心索引,减 0.5 使 texel 中心落在整数坐标。
let x = u * self.width as f32 - 0.5;
// v 使用同样中心约定,不把资源边缘当作像素中心。
@@ -197,6 +200,7 @@ impl Image {
/// Conservative convex silhouette from opaque row endpoints. Unlike an image's
/// rectangle, this excludes empty transparent margins. Generated once per PNG.
fn alpha_hull(pixels: &[u8], width: u32, height: u32) -> Vec<crate::geometry::Point> {
// png 构造后只算一次;返回以源像素为单位的保守凸包,graphics::ImageExclusion 再按 Sprite 尺寸/偏移/角度变换。
use crate::geometry::Point;
// 先收集各有效行左右端像素的四角点,后面求整体凸包,而非逐像素精确边界。
let mut points = Vec::new();
+4
View File
@@ -54,6 +54,7 @@ impl Mode {
/// 为旧页面模式生成有限轴和可延伸轴的根约束。
pub fn constraints(self, viewport: Option<Size>) -> [f32; 4] {
// LayoutRuntime::root_constraints 用于页面根测量;这里的可延伸轴仍有数值上限,不会向布局传 f32::INFINITY。
// 未收到原生视口尺寸时采用布局默认根约束;不能凭空建立固定宽高。
let Some(size) = viewport else {
return crate::layout::root_constraints(None);
@@ -118,6 +119,7 @@ impl Surface {
/// 把页面视图坐标反算为旧 Page 相机下的世界坐标。
// 输入在视图空间,先除缩放再加世界偏移;调用方需保证 zoom 有限且大于零。
pub fn to_world(&self, point: Point) -> Point {
// shell 先去除侧栏/设备比例等宿主偏移,再调用本逆变换;不在这里处理 Mount.view 或三维面板的第二层映射。
Point::new(
point.x / self.zoom + self.pan.x,
point.y / self.zoom + self.pan.y,
@@ -135,6 +137,7 @@ impl Surface {
/// 判断给定点是否位于目标范围;需要相机转换的类型会先转换再判断。
pub fn contains(&self, point: [f32; 2], viewport: Option<Size>) -> bool {
// UiBridge 在点击/滚动前用它排除页面外输入;point 必须已经是页面世界点,不能把原始设备像素传进来。
// 传入的数组是世界坐标。转换后使用左/上包含、右/下排除的视口边界;
// 未知视口时仍排除负坐标,但不限制右/下界。
// 传入世界坐标先投影到视图空间,再按视口半开边界检查,不能与 Rect.contains 的闭边界混淆。
@@ -146,6 +149,7 @@ impl Surface {
/// 只对有限页面按实际内容范围钳制偏移;自由画布不按内容边缘停止导航。
pub fn clamp(&mut self, viewport: Size) {
// UiBridge 布局完成后和 page_input 导航后调用;只修改这个 Surface 数值副本,写回 Page 属性或发布 Frame 由调用方完成。
// Window 重置所有导航;单轴模式清除另一轴并恢复单位缩放。
// 内容小于视口时 max(0) 令可滚动范围归零,避免 clamp 出现反向上下限。
match self.mode {
+5
View File
@@ -31,17 +31,20 @@ pub struct Word {
#[derive(Debug)]
/// 与列宽无关的预排资源;graphics 的 TextResource 持有 Arc<Prepared>,每次 Flow 单独创建游标。
pub struct Prepared {
// 按 Unicode 换行机会分段的有序资源;行带不足时 Cursor 停在未消费段,资源本身不保存跨调用消费状态。
pub words: Vec<Word>,
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
/// 下一个待消费段及段内字素位置;Default 从 (0,0) 开始,跨一行的多个区间和后续行持续推进。
pub struct Cursor {
// 下一段在 Prepared.words 中的下标;等于 words.len() 表示文本已消费完毕。
pub word: usize,
// 为零表示尚未拆分/位于段首,非零表示前面字素已放置,不能再回头画整词。
pub letter: usize,
}
/// row 追加的纯几何结果,graphics::flow 随后转为 PaintCommand;不在排版循环内分配托管命令对象。
pub struct Placement {
// 指回 Prepared.words 的资源索引,不是图像像素下标;Flow 据此选择整段或字素 Ink。
pub word: usize,
// None 指整词墨迹,Some 指该词某一字素;不能把整词位置再当成已经拆分的单字素。
pub letter: Option<usize>,
@@ -121,6 +124,7 @@ impl Prepared {
out: &mut Vec<Placement>,
) {
// 同一游标穿过一行所有碎片,ri 用于查看当前及后续区间原始宽度,防止过早拆词。
// ranges 的排序/有限性/最小宽度和跨行高度预算由 graphics::flow/ranges 保证;这里不搜索障碍,也不自行创建下一行。
for (ri, &(left, right)) in ranges.iter().enumerate() {
// 进入新区间从左边界开始,上一碎片的横向剩余空间不累计到这里。
let mut x = left;
@@ -154,6 +158,7 @@ impl Prepared {
}
} else if cursor.letter == 0 && word.ink.width <= remaining_max + 0.001 {
// 整词有望放入某个完整剩余区间时先保留它,结束当前碎片尝试,不因当前余宽小就拆成字素。
// remaining_max 包括当前碎片的完整宽度;即使只剩当前碎片,也会保留整词到下一行,而不是塞进本行剩余窄缝。
break;
} else {
// 词过宽或已经拆分才逐字素继续;这个分支保留跨碎片/跨行的 letter 下标。