docs: clarify layout convergence and scene coordinate contracts
This commit is contained in:
@@ -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<Size> {
|
||||
// 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);
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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<Self> {
|
||||
// 这里按仿射矩阵处理:最后一行假设为 [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 {
|
||||
|
||||
Reference in New Issue
Block a user