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 一样按网格数量决定是否使用已有索引;内容改变须由快照层重建,数量匹配不等于内容匹配。
+7
View File
@@ -112,6 +112,7 @@ impl Mapping {
/// 把当前面板的 UI 像素正向投影到外层页面空间,供坐标查询和交互测试使用。
// model/mount 的坐标查询使用此正投影,将面板内布局位置还原到外层页面供调用者定位。
pub fn project_point(&self, point: Point) -> Option<Point> {
// Mount.toView 只请求几何位置,不能用这个成功结果推断目标当前可点击;遮挡和 clip 要由 texture_point(clipped=true) 另检。
let mesh = self.view.scene.meshes.iter().find(|mesh| {
mesh.panel
.as_ref()
@@ -157,9 +158,13 @@ impl Mapping {
#[derive(Clone)]
/// 归属明确的一条内部 UI 绘制命令,装配时还保留裁剪、变换和 owner。
struct Entry {
// 本出现生成的完整逻辑命令;递归 assemble 可仅替换其中 Scene3D 的不可变视图。
command: crate::document::RenderCommand,
// 所属二维/纹理空间裁剪,与 command 的位置投影分开保存。
clip: Option<[f32; 4]>,
// 命令的累计二维视图;装入 UiSurface 后仍与原命令保持同索引。
view: Option<Transform>,
// 原绘制出现的 Mount ID,用于分组、嵌套环检查,不是场景 mesh 下标。
owner: u64,
}
@@ -168,6 +173,7 @@ struct Entry {
/// 按面板所属视口和稳定 key 分组绘制命令,递归将内部 UI 装配进 3D 面板表面。
/// source_paint 在生成各 Mount 命令后调用;输入的 command_clips、command_views、command_mounts 必须与 commands 对齐,归属 ID 必须能查到 Mount。
pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
// 输入由 source_paint::finish 建立四张平行表并校验归属;本函数直接索引,不把任意未经检查的外部 Frame 当作可靠输入。
use crate::document::RenderCommand;
use std::collections::{HashMap, HashSet};
// 按 Mount ID 建立查找表,让每条命令直接取到所属面板映射,避免逐条扫描完整 Mount 列表。
@@ -289,6 +295,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
/// 为一个面板分配有限像素表面,并调用普通 UI 软件渲染;当前实现不会按面板内容独立缓存纹理。
/// 软件光栅化的面板纹理路径调用;本函数每次产生新像素数组,复用策略由外层调用方决定。
pub fn texture(panel: &super::Panel) -> Result<Vec<u32>, &'static str> {
// render_aspect 已通过 View.valid 验证面板分辨率和内部命令;这里复用普通软件合成,输出是不透明背景上的 RGB 纹理。
// 先向统一像素预算申请有限纹理面积,再分配背景缓冲;嵌套面板同样受该预算约束。
crate::software_renderer::reserve_pixels(panel.width as usize * panel.height as usize)?;
// u32 缓冲按纹理宽高铺满背景;没有 UiSurface 时直接返回这张纯背景纹理。
+2
View File
@@ -258,11 +258,13 @@ impl Index {
/// 检查索引覆盖的网格数量是否与场景相符;缺失缓存时允许重建。
// View 在查询前用它选择缓存或临时构建;不验证顶点或 world 变换,几何改变后须由快照层重建。
pub fn matches(&self, meshes: usize) -> bool {
// 仅为缺失/长度失配提供快速判断,不是网格内容指纹;相同数量下改 world/顶点仍须由不可变快照生产方重建。
self.bounds.len() == meshes
}
/// 用包围盒筛出射线候选;索引查询按进入距离排序,精确三角形求交在调用方完成。
// View::pick 消费排序候选,再逐三角形求交与裁剪;本函数不检查相机 near/far。
pub fn ray(&self, ray: Ray) -> Vec<(f32, usize)> {
// 此处遍历后一次性返回全部盒候选;View::pick 对排序结果做精确求交和距离提前停止,不是让 BVH 直接返回最近表面。
// 空树的栈为空;显式栈避免查询递归,先测分支包围盒,未命中时整棵子树跳过。
let mut stack: Vec<_> = self.root.into_iter().collect();
// 收集 (盒进入参数, 原实例下标),遍历结束后统一排序以支持 pick 的距离提前终止。