docs: explain scene composition and 3D panel coordinate flows
This commit is contained in:
@@ -12,10 +12,13 @@ use crate::{
|
||||
#[derive(Clone, Debug, Default)]
|
||||
/// 宿主管理区域的几何布局,供窗口事件分辨页面与工具命中。
|
||||
pub struct SceneLayout {
|
||||
// 开发工具的逻辑坐标布局;页面业务对象的命中几何仍由 RenderDocument 管理。
|
||||
pub developer_tools: DeveloperToolsLayout,
|
||||
}
|
||||
|
||||
/// 组合页面、开发工具和侧栏的设备像素显示列表,同时返回供命中使用的宿主布局。
|
||||
/// shell/app 的窗口绘制路径调用此入口;width/height 是整窗设备像素,scale 将逻辑坐标换成设备坐标。
|
||||
/// 返回的显示列表交给窗口渲染,layout 则保留同帧开发工具命中区域,避免输入使用另一帧的几何。
|
||||
pub fn build_scene(
|
||||
width: u32,
|
||||
height: u32,
|
||||
@@ -32,8 +35,10 @@ pub fn build_scene(
|
||||
.iter()
|
||||
.find(|tab| tab.active)
|
||||
.and_then(|tab| tab.developer_tool.as_deref());
|
||||
// 先切换当前工具,再通知文档变化;工具绘制由此读取与活动标签一致的状态。
|
||||
developer_tools_state.select(tool);
|
||||
developer_tools_state.document_updated(document);
|
||||
// left 是侧栏占用的逻辑宽度,surface 保存业务页面的 pan/zoom;二者属于不同坐标层。
|
||||
let left = sidebar.left();
|
||||
let surface = &document.frame.surface;
|
||||
// width/height 为设备像素,sidebar.left 为逻辑单位,先乘 scale 得到页面可用裁剪区域。
|
||||
@@ -56,6 +61,7 @@ pub fn build_scene(
|
||||
(left - surface.pan.x * zoom) * scale,
|
||||
-surface.pan.y * zoom * scale,
|
||||
));
|
||||
// 从空列表开始按背景、页面、工具、侧栏的顺序叠加;后加入的命令绘制在前面内容之上。
|
||||
let mut display_list = DisplayList::default();
|
||||
// 全窗只做一次 Clear,后续跳过页面列表自身 Clear,防止其覆盖侧栏或突破页面裁剪。
|
||||
display_list.push(DrawCommand::Clear(
|
||||
@@ -63,12 +69,15 @@ pub fn build_scene(
|
||||
.unwrap_or(crate::system_ui::theme::BG),
|
||||
));
|
||||
display_list.push(DrawCommand::PushClip(content));
|
||||
// 按页面原有顺序复制命令;页面自身的嵌套裁剪仍处于 content 这个外层裁剪之内。
|
||||
for command in page.commands() {
|
||||
// Clear 是整目标缓冲清屏操作,只有非 Clear 命令可以并入已建立背景的窗口列表。
|
||||
if !matches!(command, DrawCommand::Clear(_)) {
|
||||
display_list.push(command.clone());
|
||||
}
|
||||
}
|
||||
display_list.push(DrawCommand::PopClip);
|
||||
// 工具先在扣除侧栏的独立画布内构建,宽度用饱和减法防止窄窗口发生无符号下溢。
|
||||
let (mut developer_list, mut developer_layout) = developer_tools::build(
|
||||
width.saturating_sub((left * scale) as u32),
|
||||
height,
|
||||
@@ -89,6 +98,7 @@ pub fn build_scene(
|
||||
);
|
||||
chrome.scale(scale);
|
||||
display_list.extend(chrome);
|
||||
// 把绘制输出与这次构建产生的交互布局绑定返回,调用方无需重新计算工具位置。
|
||||
DisplayScene {
|
||||
display_list,
|
||||
layout: SceneLayout {
|
||||
@@ -99,6 +109,8 @@ pub fn build_scene(
|
||||
|
||||
/// 整窗合成结果:显示列表与同帧管理交互几何一起返回。
|
||||
pub struct DisplayScene {
|
||||
// 已完成缩放与平移的整窗绘制命令,供 shell 的渲染路径消费。
|
||||
pub display_list: DisplayList,
|
||||
// 保留逻辑坐标供宿主输入路由使用,不能直接当成设备像素命中区域。
|
||||
pub layout: SceneLayout,
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user