diff --git a/src/render/scene3d.rs b/src/render/scene3d.rs index ae4ad07..097dda7 100644 --- a/src/render/scene3d.rs +++ b/src/render/scene3d.rs @@ -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, + // 每条命令在所属面板纹理空间的裁剪,None 表示不额外裁剪;长度必须与 commands 相同。 pub clips: Vec>, + // 同索引二维投影,转换命令时先缩放再平移;不是外层世界平面的相机变换。 pub views: Vec>, } #[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, + // 本视图复制的相机参数,更新业务相机后应生成新 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, &'static str> { // 全局缓存以 View Arc 身份+输出尺寸+aspect 为键;值相等但不同 Arc 的视图不会自动命中。 + // 缓存跨 VM 存续但只持原生快照/像素;关闭源域不要求旧条目立刻清空,也不会因该缓存保活托管业务对象。 static CACHE: std::sync::OnceLock> = 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 一样按网格数量决定是否使用已有索引;内容改变须由快照层重建,数量匹配不等于内容匹配。 diff --git a/src/render/scene3d/panel.rs b/src/render/scene3d/panel.rs index 9f88795..6727c9e 100644 --- a/src/render/scene3d/panel.rs +++ b/src/render/scene3d/panel.rs @@ -112,6 +112,7 @@ impl Mapping { /// 把当前面板的 UI 像素正向投影到外层页面空间,供坐标查询和交互测试使用。 // model/mount 的坐标查询使用此正投影,将面板内布局位置还原到外层页面供调用者定位。 pub fn project_point(&self, point: Point) -> Option { + // 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, + // 原绘制出现的 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, &'static str> { + // render_aspect 已通过 View.valid 验证面板分辨率和内部命令;这里复用普通软件合成,输出是不透明背景上的 RGB 纹理。 // 先向统一像素预算申请有限纹理面积,再分配背景缓冲;嵌套面板同样受该预算约束。 crate::software_renderer::reserve_pixels(panel.width as usize * panel.height as usize)?; // u32 缓冲按纹理宽高铺满背景;没有 UiSurface 时直接返回这张纯背景纹理。 diff --git a/src/render/scene3d/spatial.rs b/src/render/scene3d/spatial.rs index 9774350..30e1e2c 100644 --- a/src/render/scene3d/spatial.rs +++ b/src/render/scene3d/spatial.rs @@ -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 的距离提前终止。