diff --git a/src/model/document.rs b/src/model/document.rs index 277d571..031221b 100644 --- a/src/model/document.rs +++ b/src/model/document.rs @@ -706,7 +706,7 @@ pub enum RenderCommand { angle: f32, // 整体混合透明度,发布验证要求位于 [0,1]。 opacity: f32, - // 可选颜色调制;None 使用图像本来的颜色,区别于全透明调制色。 + // 可选遮罩着色;渲染器用 tint 替换采样 RGB,保留图像采样的 alpha,不使用 tint.alpha;None 保留原图颜色。 tint: Option, // 原生像素由 Arc 独立保活;GUI 绘制无需用源对象 ID 查 VM 堆。 image: Arc, diff --git a/src/render/box_model.rs b/src/render/box_model.rs index be267b9..bd46600 100644 --- a/src/render/box_model.rs +++ b/src/render/box_model.rs @@ -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 { /// 针对单个尺寸轴应用约束与边界规则,供双轴尺寸求解复用。 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];输入的最小约束不在此额外强加。 diff --git a/src/render/geometry.rs b/src/render/geometry.rs index 5713274..065aa7f 100644 --- a/src/render/geometry.rs +++ b/src/render/geometry.rs @@ -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 diff --git a/src/render/image.rs b/src/render/image.rs index c6c9b05..fac7920 100644 --- a/src/render/image.rs +++ b/src/render/image.rs @@ -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, 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 { + // png 构造后只算一次;返回以源像素为单位的保守凸包,graphics::ImageExclusion 再按 Sprite 尺寸/偏移/角度变换。 use crate::geometry::Point; // 先收集各有效行左右端像素的四角点,后面求整体凸包,而非逐像素精确边界。 let mut points = Vec::new(); diff --git a/src/render/page.rs b/src/render/page.rs index 57bb09a..dbf5fce 100644 --- a/src/render/page.rs +++ b/src/render/page.rs @@ -54,6 +54,7 @@ impl Mode { /// 为旧页面模式生成有限轴和可延伸轴的根约束。 pub fn constraints(self, viewport: Option) -> [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) -> 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 { diff --git a/src/render/text_flow.rs b/src/render/text_flow.rs index 9ef535c..82ff368 100644 --- a/src/render/text_flow.rs +++ b/src/render/text_flow.rs @@ -31,17 +31,20 @@ pub struct Word { #[derive(Debug)] /// 与列宽无关的预排资源;graphics 的 TextResource 持有 Arc,每次 Flow 单独创建游标。 pub struct Prepared { + // 按 Unicode 换行机会分段的有序资源;行带不足时 Cursor 停在未消费段,资源本身不保存跨调用消费状态。 pub words: Vec, } #[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, @@ -121,6 +124,7 @@ impl Prepared { out: &mut Vec, ) { // 同一游标穿过一行所有碎片,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 下标。