docs: explain 3D renderer panel and BVH ownership boundaries
This commit is contained in:
@@ -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 一样按网格数量决定是否使用已有索引;内容改变须由快照层重建,数量匹配不等于内容匹配。
|
||||
|
||||
@@ -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 时直接返回这张纯背景纹理。
|
||||
|
||||
@@ -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 的距离提前终止。
|
||||
|
||||
Reference in New Issue
Block a user