docs: explain scene composition and 3D panel coordinate flows
This commit is contained in:
@@ -6,6 +6,7 @@ use std::ops::{Add, Mul, Sub};
|
||||
|
||||
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
|
||||
/// 三维数学向量;构造不校验分量,需在输入边界显式调用 valid,不是托管 Vec3 对象。
|
||||
// model/scene3d 用它读取场景变换,原生光栅化、网格拾取和 panel 坐标映射共同复用此类型。
|
||||
pub struct Vec3 {
|
||||
pub x: f32,
|
||||
pub y: f32,
|
||||
@@ -48,21 +49,21 @@ impl Vec3 {
|
||||
}
|
||||
impl Add for Vec3 {
|
||||
type Output = Self;
|
||||
/// 按分量执行向量加减或标量乘法,保持数学运算不依赖 VM 状态。
|
||||
/// 按分量相加;摄像机射线用它叠加前向与视平面偏移。
|
||||
fn add(self, b: Self) -> Self {
|
||||
Self::new(self.x + b.x, self.y + b.y, self.z + b.z)
|
||||
}
|
||||
}
|
||||
impl Sub for Vec3 {
|
||||
type Output = Self;
|
||||
/// 按分量执行向量加减或标量乘法,保持数学运算不依赖 VM 状态。
|
||||
/// 按分量相减;观察基与三角形求交用它得到相对位置和边向量。
|
||||
fn sub(self, b: Self) -> Self {
|
||||
Self::new(self.x - b.x, self.y - b.y, self.z - b.z)
|
||||
}
|
||||
}
|
||||
impl Mul<f32> for Vec3 {
|
||||
type Output = Self;
|
||||
/// 按分量执行向量加减或标量乘法,保持数学运算不依赖 VM 状态。
|
||||
/// 每个分量乘同一个标量;归一化、射线步进和光照计算用它调整向量长度。
|
||||
fn mul(self, b: f32) -> Self {
|
||||
Self::new(self.x * b, self.y * b, self.z * b)
|
||||
}
|
||||
@@ -70,9 +71,10 @@ impl Mul<f32> for Vec3 {
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
|
||||
/// 仿射 4×4 变换矩阵,支持局部到世界的组合与求逆。
|
||||
// model/scene3d 从 TRS 构造并组合世界矩阵;panel 使用其逆矩阵将射线交点还原为局部 UI 位置。
|
||||
pub struct Matrix(pub [f32; 16]);
|
||||
impl Default for Matrix {
|
||||
/// 建立类型约定的初始值,供尚未发布或尚未交互的状态使用。
|
||||
/// 返回单位矩阵,供场景遍历的根变换使用;与局部矩阵组合时保持原变换。
|
||||
fn default() -> Self {
|
||||
Self([
|
||||
1., 0., 0., 0., 0., 1., 0., 0., 0., 0., 1., 0., 0., 0., 0., 1.,
|
||||
@@ -121,7 +123,9 @@ impl Matrix {
|
||||
pub fn compose(self, local: Self) -> Self {
|
||||
// 行主序存储,点视作列向量;self.compose(local) = self × local,即先应用 local 再应用 self。
|
||||
let mut out = [0.; 16];
|
||||
// 逐行逐列计算输出的 16 个元素;k 遍历 self 的行与 local 的列,累加四项点积。
|
||||
for row in 0..4 {
|
||||
// row/col 都属于输出矩阵;不能交换两个乘数,否则父子变换顺序会反转。
|
||||
for col in 0..4 {
|
||||
out[row * 4 + col] = (0..4)
|
||||
.map(|k| self.0[row * 4 + k] * local.0[k * 4 + col])
|
||||
@@ -141,10 +145,11 @@ impl Matrix {
|
||||
/// 由平移、角度旋转和缩放构造局部仿射矩阵。
|
||||
pub fn trs(position: Vec3, rotation: Vec3, scale: Vec3) -> Self {
|
||||
// 输入欧拉角单位为度,先转换为弧度。组合为 T × Rz × Ry × Rx × S,列分别乘对应缩放轴。
|
||||
// 分别缓存三个轴的正弦和余弦,后面的矩阵展开式复用这些值。
|
||||
let (sx, cx) = rotation.x.to_radians().sin_cos();
|
||||
let (sy, cy) = rotation.y.to_radians().sin_cos();
|
||||
let (sz, cz) = rotation.z.to_radians().sin_cos();
|
||||
// Local X, then Y, then Z rotation; scale first, translation last.
|
||||
// 点先缩放,再依次绕局部 X、Y、Z 旋转,最后加平移;这里直接展开组合矩阵以避免临时矩阵。
|
||||
Self([
|
||||
cz * cy * scale.x,
|
||||
(cz * sy * sx - sz * cx) * scale.y,
|
||||
@@ -177,16 +182,21 @@ pub enum Projection {
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
|
||||
/// 原生摄像机描述,包括观察基、近远面和投影参数;宽高比由视口提供。
|
||||
// 场景发布时由 model 验证参数;View 渲染/拾取与 panel 映射随后使用同一份相机描述。
|
||||
pub struct Camera {
|
||||
// 世界空间眼睛位置;透视投影的全部拾取射线从这里出发。
|
||||
pub position: Vec3,
|
||||
// 世界空间观察目标,用 target-position 确定前向,而不是直接保存欧拉角。
|
||||
pub target: Vec3,
|
||||
// 提供上方向参考,basis 会重新正交化;与前向平行时无法形成观察基。
|
||||
pub up: Vec3,
|
||||
// 近远面按相机正向深度裁剪;valid 要求 0 < near < far。
|
||||
pub near: f32,
|
||||
pub far: f32,
|
||||
pub projection: Projection,
|
||||
}
|
||||
impl Default for Camera {
|
||||
/// 建立类型约定的初始值,供尚未发布或尚未交互的状态使用。
|
||||
/// 返回从世界 z=5 观察原点的透视相机,供缺省场景与原生测试构造使用。
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
position: Vec3::new(0., 0., 5.),
|
||||
@@ -211,7 +221,9 @@ impl Camera {
|
||||
// forward 指向观察目标;up 输入只提供大致上方向,叉积后重新正交化。
|
||||
// 位置等于目标、up 为零或与前向平行时,normalized 返回 None。
|
||||
let forward = (self.target - self.position).normalized()?;
|
||||
// 前向叉上方向产生右向;再次归一化,消除输入 up 长度对后续投影的影响。
|
||||
let right = forward.cross(self.up).normalized()?;
|
||||
// 用已确定的右向和前向重建垂直上向,让三个基向量彼此正交。
|
||||
let up = right.cross(forward).normalized()?;
|
||||
Some(Basis { right, up, forward })
|
||||
}
|
||||
@@ -227,6 +239,7 @@ impl Camera {
|
||||
&& self.near > 0.
|
||||
&& self.far > self.near
|
||||
&& self.far <= 1_000_000.
|
||||
// 投影类型决定最后的合法性条件;透视角度受限以避免极端 tan,正交高度必须为正。
|
||||
&& match self.projection {
|
||||
Projection::Perspective { fov } => fov.is_finite() && (1.0..=175.0).contains(&fov),
|
||||
Projection::Orthographic { height } => {
|
||||
@@ -242,6 +255,7 @@ impl Camera {
|
||||
}
|
||||
/// 从视口归一化坐标生成透视或正交射线;宽高比由具体视口提供。
|
||||
pub fn ray(self, u: f32, v: f32, aspect: f32) -> Option<Ray> {
|
||||
// View::pick 和 panel::Mapping 的逆投影都从这里生成射线;退化观察基直接向上传播 None。
|
||||
let basis = self.basis()?;
|
||||
// u/v 通常是视口内 [0,1],映射到 [-1,1] 并翻转屏幕 y。
|
||||
// 此函数不钳制输入,捕获拖动可以从视口外继续生成射线;aspect 由调用方保证有效。
|
||||
@@ -276,6 +290,7 @@ pub struct Ray {
|
||||
}
|
||||
impl Ray {
|
||||
/// 求射线与三角形相交距离和重心坐标,拒绝退化三角形及射线起点后方的交点。
|
||||
// View::pick 遍历网格三角形时调用,使用返回的射线参数选最近命中,重心权重还可插值纹理坐标。
|
||||
pub fn triangle(self, a: Vec3, b: Vec3, c: Vec3) -> Option<(f32, [f32; 3])> {
|
||||
// Möller–Trumbore 求交:使用两条三角形边与叉积解重心系数,不先构造平面方程。
|
||||
let ab = b - a;
|
||||
@@ -286,6 +301,7 @@ impl Ray {
|
||||
if determinant.abs() < 1e-7 {
|
||||
return None;
|
||||
}
|
||||
// 复用行列式倒数以解重心系数;t 此处是从顶点 a 指向射线起点的向量。
|
||||
let inverse = 1.0 / determinant;
|
||||
let t = self.origin - a;
|
||||
// u 是顶点 b 的重心权重,必须位于 [0,1];v 是 c 的权重,a 的权重由 1-u-v 得到。
|
||||
@@ -293,8 +309,10 @@ impl Ray {
|
||||
if !(0.0..=1.0).contains(&u) {
|
||||
return None;
|
||||
}
|
||||
// 第二次叉积用于同时求顶点 c 的权重和射线参数,避免另外求解完整线性方程组。
|
||||
let q = t.cross(ab);
|
||||
let v = self.direction.dot(q) * inverse;
|
||||
// v 为负或 b/c 权重和超过 1 都表示交点落在三角形外,即使它仍位于三角形所在平面。
|
||||
if v < 0. || u + v > 1. {
|
||||
return None;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user