docs: explain 3D renderer panel and BVH ownership boundaries

This commit is contained in:
2026-11-12 20:51:29 +08:00
parent 3db8b13768
commit f0bfbc9fc1
3 changed files with 21 additions and 0 deletions
+12
View File
@@ -1,6 +1,8 @@
//! 有界 CPU 3D 渲染器。使用相同摄像机与世界变换进行视锥裁剪、深度测试、纹理采样和射线拾取。
//! 不可变 View 可以缓存光栅结果;相机变化会产生新视图。当前不是 GPU 后端,像素和光栅工作预算用于限制分配与循环工作量。
//! 面板 UI 先渲染为有限纹理,再以透视校正 UV 映射进世界。与相机相关的投影宽高比由具体视口提供。
//! model::scene3d 提供不可变 Scene/View;source_paint 经 panel::compose 装配面板内容,SoftwareRenderer 再调用 surface 取得像素。
//! View::pick 只返回原生 Hit,关联回托管 Mesh 和构造 Event/RayHit3D 仍由模型/桥接层负责。
//!
//! Software 3D surfaces share the application's existing CPU compositor. Mesh
//! visibility and picking use the same camera and transformed world triangles.
@@ -98,7 +100,9 @@ pub struct Mesh {
pub struct UiSurface {
// panel::compose 把所属 Mount 的命令装入这里;clips/views 按命令索引一一对应。
pub commands: Vec<crate::document::RenderCommand>,
// 每条命令在所属面板纹理空间的裁剪,None 表示不额外裁剪;长度必须与 commands 相同。
pub clips: Vec<Option<[f32; 4]>>,
// 同索引二维投影,转换命令时先缩放再平移;不是外层世界平面的相机变换。
pub views: Vec<Option<crate::viewport::Transform>>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
@@ -146,7 +150,9 @@ impl PartialEq for Scene {
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
/// 显式相机与共享世界的组合,一个 Scene 可由多个独立 View 观察。
pub struct View {
// 世界网格、光照和可复用 BVH;多个相机 View 可共享同一个世界快照。
pub scene: Arc<Scene>,
// 本视图复制的相机参数,更新业务相机后应生成新 View,不能修改已经交给渲染线程的旧快照。
pub camera: Camera,
}
#[derive(Debug)]
@@ -168,9 +174,13 @@ impl endor_core::ObjectPayload for PaintView {
pub struct Hit {
// 命中的 Scene.meshes 下标,用于面板遮挡判断;identity 则供 model 重新关联业务 Mesh。
pub instance: usize,
// 命中实例对应的业务身份文本;同一 Mesh 可多次出现,具体出现仍需 instance 区分。
pub identity: String,
// 单位射线按 distance 步进得到的世界交点,不是视口像素或面板局部坐标。
pub point: Vec3,
// 变换后三角形边叉积的世界单位法线,非均匀缩放后也按真实世界面求解。
pub normal: Vec3,
// 沿单位射线的世界距离;near/far 校验另用相机前向深度,二者不能混用。
pub distance: f32,
// 原几何中的三角形下标,barycentric 依次对应该面三个顶点的权重。
pub triangle: usize,
@@ -392,6 +402,7 @@ pub fn surface(
aspect: f32,
) -> Result<Arc<[u32]>, &'static str> {
// 全局缓存以 View Arc 身份+输出尺寸+aspect 为键;值相等但不同 Arc 的视图不会自动命中。
// 缓存跨 VM 存续但只持原生快照/像素;关闭源域不要求旧条目立刻清空,也不会因该缓存保活托管业务对象。
static CACHE: std::sync::OnceLock<std::sync::Mutex<SurfaceCache>> = std::sync::OnceLock::new();
// 进程内惰性初始化共享缓存;锁中毒按错误返回,不绕过锁继续使用状态。
let cache = CACHE.get_or_init(Default::default);
@@ -567,6 +578,7 @@ fn render_aspect(
)
};
// 累计所有三角形屏幕包围矩形的扫描面积,遮挡后未写像素的工作也计入。
// 这是本次表面的光栅工作量;递归面板的颜色/深度分配由上方 RenderScope 的共享像素额度另行累计,不能用缓存大小替代。
let mut work = 0usize;
let temporary;
// 与 pick 一样按网格数量决定是否使用已有索引;内容改变须由快照层重建,数量匹配不等于内容匹配。