docs: clarify layout convergence and scene coordinate contracts

This commit is contained in:
2026-11-12 20:49:23 +08:00
parent cd0f292b78
commit 3db8b13768
3 changed files with 18 additions and 1 deletions
+9
View File
@@ -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 {