docs: explain Tessera modules and execution flows in Chinese

src/render/scene3d/spatial.rs

@@ -1,3 +1,6 @@
+//! 不可变世界空间 BVH。用网格变换后的包围盒快速筛选视锥与射线候选。
+//! 空间索引只做宽阶段筛选；最终拾取仍检查真实三角形。相机变化可复用索引，几何或变换变化需要新索引。
+//!
 //! Immutable world-space BVH. Camera changes reuse it; it contains no VM data.
 use super::{
     Mesh,
@@ -5,11 +8,13 @@ use super::{
 };
 
 #[derive(Debug, Clone, Copy)]
+/// 变换后网格的世界空间 AABB，做保守筛选而不是精确表面描述。
 pub struct Bounds {
     pub min: Vec3,
     pub max: Vec3,
 }
 impl Bounds {
+    /// 变换网格顶点并求世界 AABB，作为空间索引的保守外包围。
     fn mesh(mesh: &Mesh) -> Option<Self> {
         let mut points = mesh
             .geometry
@@ -36,6 +41,7 @@ impl Bounds {
             },
         ))
     }
+    /// 求两个包围盒的最小共同外包围，供 BVH 父节点使用。
     fn union(self, other: Self) -> Self {
         Self {
             min: Vec3::new(
@@ -50,11 +56,13 @@ impl Bounds {
             ),
         }
     }
+    /// 取指定轴中心位置，供最长轴排序和分割使用。
     fn center(self, axis: usize) -> f32 {
         let min = [self.min.x, self.min.y, self.min.z];
         let max = [self.max.x, self.max.y, self.max.z];
         (min[axis] + max[axis]) / 2.
     }
+    /// 用包围盒筛出射线候选；索引查询按进入距离排序，精确三角形求交在调用方完成。
     fn ray(self, ray: Ray) -> Option<f32> {
         let mut near = 0f32;
         let mut far = f32::INFINITY;
@@ -79,6 +87,7 @@ impl Bounds {
         }
         Some(near)
     }
+    /// 用相机六平面保守判断包围盒可见性，返回保持原场景顺序的候选。
     fn visible(self, camera: Camera, basis: Basis, planes: &[[f32; 4]; 6]) -> bool {
         let corners: [Vec3; 8] = std::array::from_fn(|index| {
             camera.view(
@@ -110,6 +119,7 @@ impl Bounds {
     }
 }
 #[derive(Debug)]
+/// BVH 叶或分支；叶保存实例索引，分支保存两个子节点索引。
 enum Node {
     Leaf {
         bounds: Bounds,
@@ -122,6 +132,7 @@ enum Node {
     },
 }
 impl Node {
+    /// 读取叶/分支统一的包围盒，隐藏节点种类差异。
     fn bounds(&self) -> Bounds {
         match self {
             Self::Leaf { bounds, .. } | Self::Branch { bounds, .. } => *bounds,
@@ -130,12 +141,14 @@ impl Node {
 }
 
 #[derive(Debug, Default)]
+/// 由不可变场景建立的包围盒树，供相机视锥和射线查询复用。
 pub struct Index {
     bounds: Vec<Option<Bounds>>,
     nodes: Vec<Node>,
     root: Option<usize>,
 }
 impl Index {
+    /// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
     pub fn build(meshes: &[Mesh]) -> Self {
         let bounds: Vec<_> = meshes.iter().map(Bounds::mesh).collect();
         let mut items: Vec<_> = bounds
@@ -153,6 +166,7 @@ impl Index {
         }
         index
     }
+    /// 按包围盒最长轴的中心排序并递归二分，叶节点保留少量网格候选。
     fn split(&mut self, items: &mut [usize]) -> usize {
         let bounds = items
             .iter()
@@ -196,9 +210,11 @@ impl Index {
         }
         index
     }
+    /// 检查索引覆盖的网格数量是否与场景相符；缺失缓存时允许重建。
     pub fn matches(&self, meshes: usize) -> bool {
         self.bounds.len() == meshes
     }
+    /// 用包围盒筛出射线候选；索引查询按进入距离排序，精确三角形求交在调用方完成。
     pub fn ray(&self, ray: Ray) -> Vec<(f32, usize)> {
         let mut stack: Vec<_> = self.root.into_iter().collect();
         let mut output = Vec::new();
@@ -223,6 +239,7 @@ impl Index {
         output.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1)));
         output
     }
+    /// 用相机六平面保守判断包围盒可见性，返回保持原场景顺序的候选。
     pub fn visible(&self, camera: Camera, aspect: f32) -> Vec<usize> {
         let Some(basis) = camera.basis() else {
             return Vec::new();