From 3db8b1376850a378a3d898dc94c910d6991a0923 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 20:49:23 +0800 Subject: [PATCH] docs: clarify layout convergence and scene coordinate contracts --- src/render/layout.rs | 7 ++++++- src/render/scene.rs | 3 +++ src/render/scene3d/math.rs | 9 +++++++++ 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/src/render/layout.rs b/src/render/layout.rs index f33b1a7..3fc70e1 100644 --- a/src/render/layout.rs +++ b/src/render/layout.rs @@ -356,6 +356,7 @@ pub fn occurrence_constraints( child_index: usize, ) -> [f32; 4] { // 世界面板 UI 根必须精确按纹理分辨率布局,最小与最大相同,不让外层视口世界尺寸泄入纹理空间。 + // build 的初始展开、native_visual 的独立 arrange 与 source_layout 收敛都按同一 child_index 解释这些输入,不能按 Block ID 合并共享孩子。 if let UiKind::Viewport3D { panels, .. } = &parent.kind { // 面板 child_index 与 panels/children 保持同序,该 UI 根按自己的纹理尺寸精确布局。 let size = panels[child_index]; @@ -758,6 +759,8 @@ fn main_limits(child: &UiNode, row: bool) -> (f32, f32) { /// 按权重分配主轴剩余空间,尊重每项 min/max;达到上限的项退出后重新分配剩余量。 pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[Size]) -> Vec { + // native_visual::Arrange 与本模块 build 共用;所有输入数组须与 node.children 同序同长度,本函数不替调用方验证平行表。 + // 返回分配尺寸不等于重新测量后的自然尺寸,文字换行等反馈由 source_layout 的后续收敛轮处理。 // Overlay 各孩子独立填内容盒,不共享主轴剩余量;普通线性容器才做下方加权增长/收缩。 if matches!(node.kind, UiKind::Overlay { .. }) { // Overlay 各项独享同一有限内容区,不把空间按兄弟总权重分割。 @@ -1033,7 +1036,7 @@ pub fn arrange_native( .zip(node.children()) .map(|(child, node)| { // 根据父方向取宽+左右 margin 或高+上下 margin,交叉尺寸不进入主轴占用。 - // 父交叉轴内容尺寸先扣该方向的 inset:Row 用高,纵向父用宽。 + // 这里 child 是实测 Size,node 是对应孩子样式;父自身 inset 在后面的 spare 计算中另扣。 if row { child.width + node.margin.horizontal() } else { @@ -1156,6 +1159,7 @@ impl LayoutRuntime { // 缓存、ID 分配和统计都先在副本上变更,build 失败不污染当前运行时。 let mut next = self.clone(); // 完整原生构建成功才提交副本;返回 Frame 仍由桥接添加投影/发布上下文。 + // build 尚未建立命令 owner/clip/view 与命中索引;正常桥接随后经 scroll::project、viewport::project 重建这些表,不能直接视为可交互发布结果。 let frame = next.build(root, false)?; *self = next; Ok(frame) @@ -1341,6 +1345,7 @@ impl LayoutRuntime { continue; } // 收集此父孩子当前尺寸作为单次纯原生分配的输入,源协议多轮 remeasure 在外层完成。 + // 本路径不会在 flex 改宽后回头重测子树;source_layout 已把需要弹性/拉伸反馈的树排除在小原生直接路径之外。 let child_sizes: Vec<_> = item.children.iter().map(|child| sizes[*child]).collect(); // 自顶向下用父实际尺寸更新孩子分配后再求原点;更复杂的源协议反复求解由 source_layout 驱动。 let child_sizes = flex_sizes(item.node, size, &child_sizes, &child_sizes); diff --git a/src/render/scene.rs b/src/render/scene.rs index b5e5bb5..a45dd33 100644 --- a/src/render/scene.rs +++ b/src/render/scene.rs @@ -1,5 +1,6 @@ //! 合成整个原生窗口的显示列表:页面画面、宿主侧栏和开发工具绘制。 //! 窗口逻辑尺寸与设备像素比例在这里衔接。页面内容先应用其视角并裁剪,宿主控件的区域和命中布局另外返回。 +//! shell/app 为每个 OS 窗口用各自已发布文档调用 build_scene;本模块只组装设备命令,不进入 VM 或刷新源协议。 //! use crate::{ activity::Activity, @@ -49,6 +50,7 @@ pub fn build_scene( height as f32, ); // 管理页使用单位页面缩放,避免业务 Page 相机改变宿主工具字号;普通页叠加旧 Surface zoom。 + // Mount/逐命令相机投影已在文档内,Surface 是外层旧 Page 视角,设备 scale 则属于整个 OS 窗口,三者不能重复应用。 let zoom = if tool.is_some() { 1.0 } else { surface.zoom }; // 显示列表转换失败时降级为空默认文档;这只保护原生绘制,不把无效命令伪装成成功执行。 let mut page = document.display_list(scale * zoom).unwrap_or_else(|_| { @@ -87,6 +89,7 @@ pub fn build_scene( activity, ); // 工具命令在设备空间平移,交互布局在逻辑空间平移,两者比例不同但实际对齐同一页面起点。 + // 输入路由保留的 developer_layout 不能再乘 scale;shell 的 pointer 已转换为逻辑单位,只有像素绘制列表使用设备比例。 developer_list.translate(Point::new(left * scale, 0.0)); developer_layout.translate(left, 0.0); display_list.extend(developer_list); diff --git a/src/render/scene3d/math.rs b/src/render/scene3d/math.rs index aa8cbbf..f6abbf6 100644 --- a/src/render/scene3d/math.rs +++ b/src/render/scene3d/math.rs @@ -8,6 +8,7 @@ use std::ops::{Add, Mul, Sub}; /// 三维数学向量;构造不校验分量,需在输入边界显式调用 valid,不是托管 Vec3 对象。 // model/scene3d 用它读取场景变换,原生光栅化、网格拾取和 panel 坐标映射共同复用此类型。 pub struct Vec3 { + // 三轴原始分量;表示位置、方向或重心权重取决于调用方,不在类型中隐式携带坐标空间。 pub x: f32, pub y: f32, pub z: f32, @@ -85,6 +86,7 @@ impl Matrix { /// 求仿射世界矩阵的逆;退化或不可逆时返回空值。 pub fn inverse(self) -> Option { // 这里按仿射矩阵处理:最后一行假设为 [0,0,0,1],只逆左上 3×3,不实现一般透视矩阵求逆。 + // panel::Mapping 用它把世界射线交点还原到面板局部平面;零缩放等退化情况返回 None,由调用方停止映射。 let m = self.0; let determinant = m[0] * (m[5] * m[10] - m[6] * m[9]) - m[1] * (m[4] * m[10] - m[6] * m[8]) + m[2] * (m[4] * m[9] - m[5] * m[8]); @@ -192,7 +194,9 @@ pub struct Camera { pub up: Vec3, // 近远面按相机正向深度裁剪;valid 要求 0 < near < far。 pub near: f32, + // 最远可见正向深度;射线距离与此深度不是同一数值,斜向透视射线的命中要先换到观察基再裁剪。 pub far: f32, + // 透视角度或正交高度;相机本身不保存视口宽高比,render/pick 每次按具体出现传入 aspect。 pub projection: Projection, } impl Default for Camera { @@ -211,8 +215,11 @@ impl Default for Camera { #[derive(Debug, Clone, Copy)] /// 摄像机的右、上、前单位基向量。 pub struct Basis { + // 观察平面的横向单位轴,来自 forward×up,不直接使用世界 X 轴。 pub right: Vec3, + // 与 right/forward 正交的上轴,可能不同于源相机未归一化的 up 参考向量。 pub up: Vec3, + // 从相机指向 target 的单位前向,view 以此方向为正深度。 pub forward: Vec3, } impl Camera { @@ -285,7 +292,9 @@ impl Camera { #[derive(Debug, Clone, Copy)] /// 世界坐标中的射线原点与方向,供网格和面板求交。 pub struct Ray { + // 世界空间起点;透视使用相机 position,正交则按视口点在相机平面上平移起点。 pub origin: Vec3, + // Camera::ray 返回单位方向;手工构造 Ray 不会自动归一化,triangle 返回的参数此时不保证等于欧氏距离。 pub direction: Vec3, } impl Ray {