Plan new editor viewport render host migration
This commit is contained in:
333
docs/plan/NewEditor_3D渲染主链正式接入计划_2026-04-12.md
Normal file
333
docs/plan/NewEditor_3D渲染主链正式接入计划_2026-04-12.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# NewEditor 3D渲染主链正式接入计划
|
||||
|
||||
日期: `2026-04-12`
|
||||
|
||||
## 1. 文档定位
|
||||
|
||||
这份计划替代此前那份偏宽泛的《NewEditor 对标旧 Editor 迁移重建计划》。
|
||||
|
||||
当前主线已经很明确:
|
||||
|
||||
- `new_editor` 的 UI 基础壳已经足够继续往上承接。
|
||||
- 真正卡住后续重建编辑器的，不再是普通面板样式或 tab/dock 行为。
|
||||
- 当前最大的主阻塞，是 `Scene / Game` 还没有接上旧 `editor` 里已经跑通的真实 3D 渲染主链。
|
||||
|
||||
因此，接下来要先做的不是继续铺业务面板，而是:
|
||||
|
||||
1. 先把 `new_editor` 的宿主渲染链补齐。
|
||||
2. 再把旧 `editor` 的 viewport/rendering 主链正式迁入 `new_editor`。
|
||||
3. 等 `Scene / Game` 真正稳定输出真实 3D 画面后，再继续后续编辑器业务迁移。
|
||||
|
||||
## 2. 当前事实与根因判断
|
||||
|
||||
### 2.1 旧 editor 当前的真实可用主链
|
||||
|
||||
旧 `editor` 的 Scene/Game viewport 不是面板里临时拼的，它已经形成了明确主链:
|
||||
|
||||
`Application -> D3D12WindowRenderer -> ViewportHostService -> SceneRenderer -> ViewportRenderTargets -> ImGui texture presentation`
|
||||
|
||||
当前关键代码入口:
|
||||
|
||||
- `editor/src/Application.cpp`
|
||||
- `editor/src/Platform/D3D12WindowRenderer.h`
|
||||
- `editor/src/Viewport/ViewportHostService.h`
|
||||
- `editor/src/panels/SceneViewPanel.cpp`
|
||||
- `editor/src/panels/GameViewPanel.cpp`
|
||||
|
||||
### 2.2 new_editor 当前的真实状态
|
||||
|
||||
`new_editor` 现在已经有:
|
||||
|
||||
- `XCEditor` UI 基础层
|
||||
- Win32 + `NativeRenderer` 宿主层
|
||||
- `Hierarchy / Inspector / Console / Project` 这些 hosted content 面板外壳
|
||||
|
||||
但 `Scene / Game` 这条线并没有真正接上旧 editor 的 render path。
|
||||
|
||||
当前缺口是结构性的:
|
||||
|
||||
1. `new_editor/app/Shell/ProductShellAsset.cpp` 里，`scene` 和 `game` 仍然只是 `HostedContent`，还没有切到正式的 `ViewportShell` 主线。
|
||||
2. `new_editor/app/Workspace/ProductEditorWorkspace.cpp` 里，没有真正的 viewport service owner，也没有 scene/game render request 生命周期。
|
||||
3. `new_editor/Host/NativeRenderer.h/.cpp` 当前是 Direct2D/DirectWrite 宿主，只支持它自己的位图纹理路径。
|
||||
4. `engine/include/XCEngine/UI/Types.h` 虽然已经有 `UITextureHandleKind::ShaderResourceView`，但 `NativeRenderer` 目前并没有真正消费这类引擎 render target。
|
||||
|
||||
### 2.3 根因结论
|
||||
|
||||
当前问题的根因不是“Scene 面板还没抄过来”，而是:
|
||||
|
||||
- `new_editor` 宿主层还没有与引擎 `Rendering + RHI` 建立正式的 viewport 纹理桥接。
|
||||
- `XCEditor` 的 viewport 壳层虽然已经存在，但 `new_editor` 还没把它真正接到 GPU viewport frame 上。
|
||||
|
||||
所以这件事必须从宿主渲染架构开始修，不能从面板层糊。
|
||||
|
||||
## 3. 不可违背的执行原则
|
||||
|
||||
### 3.1 根因优先
|
||||
|
||||
- 禁止 CPU 截图回读后再贴回 UI。
|
||||
- 禁止用 PNG/中间 bitmap/调试贴图冒充正式 viewport 输出。
|
||||
- 禁止在 `Scene` 或 `Game` 面板内部偷偷持有一套临时渲染路径。
|
||||
|
||||
### 3.2 旧 editor 只作为基线，不照搬 ImGui 壳
|
||||
|
||||
- 要复用旧 editor 已经验证过的 render host、viewport service、render target、object id、overlay 这些真实主链能力。
|
||||
- 但不要把 `ImGui panel` 那一层硬抄到 `new_editor`。
|
||||
- 迁移时要抽出“引擎桥接能力”，接回 `XCEditor` 的 viewport shell。
|
||||
|
||||
### 3.3 Scene/Game 必须统一走正式 viewport 子系统
|
||||
|
||||
- `Scene` 和 `Game` 不能继续当普通 hosted content 面板处理。
|
||||
- 它们必须切到同一套 `ViewportShell -> ViewportService -> RenderTargets -> RenderFrame` 路径。
|
||||
- Scene/Game 的差异只能体现在 camera / overlay / input policy，不应该体现在宿主渲染基础设施层。
|
||||
|
||||
### 3.4 每阶段都能独立验证
|
||||
|
||||
每一阶段结束都必须满足:
|
||||
|
||||
- 能编译 `XCUIEditorApp`
|
||||
- 能运行 exe
|
||||
- 能给出明确的人工检查点
|
||||
|
||||
## 4. 目标架构
|
||||
|
||||
## 4.1 new_editor 最终应形成的 viewport 主链
|
||||
|
||||
目标主链:
|
||||
|
||||
`Win32 Application -> Host Window Renderer -> XCEditor ViewportShell -> ProductViewportHostService -> SceneRenderer -> RHI RenderTargets -> Viewport Texture Bridge -> XCEditor Compose -> Window Present`
|
||||
|
||||
分层责任:
|
||||
|
||||
- `Host`
|
||||
- 管窗口、swapchain、command queue、command list、descriptor heap、present
|
||||
- `XCEditor`
|
||||
- 管 viewport 壳层布局、top bar、bottom bar、input bridge、状态显示
|
||||
- `new_editor/app/Viewport`
|
||||
- 管 Scene/Game viewport 请求、render target 生命周期、editor scene camera、input 解释、selection/picking/overlay
|
||||
- `Rendering + RHI`
|
||||
- 管真正的 scene render requests 和 GPU 输出
|
||||
|
||||
## 4.2 宿主层方向
|
||||
|
||||
`NativeRenderer` 当前的 D2D-only `HwndRenderTarget` 不能作为长期正式宿主。
|
||||
|
||||
新的宿主方向应当是:
|
||||
|
||||
- 以 D3D12/RHI swapchain 作为主呈现链
|
||||
- 在这个主呈现链上承接 `XCEditor` UI 组合与 engine viewport 纹理
|
||||
|
||||
关于 2D UI 绘制策略，允许按实际情况调整实现，但边界必须固定:
|
||||
|
||||
- 可以保留 D2D/DWrite 作为 2D 绘制后端，但它只能作为从属 UI compositor，不能继续做整个窗口的唯一主呈现链
|
||||
- 如果 D2D 与 D3D12 的互操作复杂度失控，就切换为更直接的 GPU UI compositor
|
||||
- 无论选择哪条实现路径，都不能回退到 CPU 回读/贴图绕路
|
||||
|
||||
## 5. 执行阶段
|
||||
|
||||
## 阶段 A: 宿主渲染基础设施对齐
|
||||
|
||||
目标:
|
||||
|
||||
- 先把 `new_editor` 宿主从“D2D-only 窗口绘制器”升级为“真正的窗口 render host”
|
||||
|
||||
主要工作:
|
||||
|
||||
1. 在 `new_editor/Host` 下建立正式的 window renderer
|
||||
2. 对齐旧 `editor/src/Platform/D3D12WindowRenderer.h` 的能力边界
|
||||
3. 让 `Application` 能拿到:
|
||||
- `RHIDevice`
|
||||
- `RHICommandQueue`
|
||||
- `RHICommandList`
|
||||
- swapchain backbuffer surface
|
||||
- shader-visible descriptor heap
|
||||
- 每帧 begin/present 生命周期
|
||||
4. 保留并接回现有 DPI / resize / cursor / screenshot 生命周期
|
||||
|
||||
验收:
|
||||
|
||||
- `XCUIEditor.exe` 能用新宿主稳定打开
|
||||
- 调整窗口尺寸时不会再出现位图式整体拉伸
|
||||
- 空窗口 clear/present 稳定，无闪烁、无明显 resize 延迟
|
||||
|
||||
## 阶段 B: Viewport 纹理桥接正式化
|
||||
|
||||
目标:
|
||||
|
||||
- 让 `XCEditor` viewport slot 真正能展示来自引擎 RHI 的 render target
|
||||
|
||||
主要工作:
|
||||
|
||||
1. 明确 `UITextureHandle` 在 `new_editor` 中的正式 viewport 语义
|
||||
2. 补齐 `ShaderResourceView` 路径，而不是继续只支持文件位图
|
||||
3. 建立 render target -> UI texture handle 的生命周期管理
|
||||
4. 处理 descriptor/state/resize/recreate 规则
|
||||
|
||||
建议测试:
|
||||
|
||||
- 在 `tests/UI/Editor/integration` 下新增专门的 viewport GPU 纹理验证用例
|
||||
- 先用一个最小 GPU clear/checkerboard 纹理跑通 `ViewportShell`
|
||||
|
||||
验收:
|
||||
|
||||
- `ViewportShell` 可显示真实 GPU render target
|
||||
- viewport 尺寸变化时，纹理尺寸和显示内容立即同步
|
||||
- 整个链路不含 readback / screenshot / 中间文件
|
||||
|
||||
## 阶段 C: Scene/Game 从 HostedContent 切到 ViewportShell
|
||||
|
||||
目标:
|
||||
|
||||
- 让 `scene` 和 `game` 不再是伪面板，而是正式 viewport panel
|
||||
|
||||
主要工作:
|
||||
|
||||
1. 修改 `ProductShellAsset` 中 `scene/game` 的 presentation 模型
|
||||
2. 在 `new_editor/app` 建立正式的 viewport panel 装配点
|
||||
3. 建立 viewport request/response 数据模型:
|
||||
- requested size
|
||||
- presented frame
|
||||
- status text
|
||||
- capture/focus/input state
|
||||
|
||||
验收:
|
||||
|
||||
- `Scene` 和 `Game` 面板进入统一 viewport 壳层
|
||||
- 可以显示“真实 viewport frame”，不再是纯 placeholder/调试文案
|
||||
|
||||
## 阶段 D: Scene 真实渲染最小闭环
|
||||
|
||||
目标:
|
||||
|
||||
- 先让 `Scene` 面板输出旧 editor 那条真实 3D 场景渲染
|
||||
|
||||
主要工作:
|
||||
|
||||
1. 在 `new_editor/app/Viewport` 下建立 `ProductViewportHostService`
|
||||
2. 先迁移旧 `ViewportHostService` 的最小 spine:
|
||||
- scene editor camera state
|
||||
- scene viewport render targets
|
||||
- `SceneRenderer` 调用
|
||||
- status/failure policy
|
||||
3. 只先做“能稳定渲染”的最小闭环
|
||||
4. 暂时不带 gizmo，不带复杂 overlay，不带过多面板业务联动
|
||||
|
||||
验收:
|
||||
|
||||
- `Scene` 面板显示真实 3D 场景
|
||||
- resize 时 render target 立即更新
|
||||
- 画面不是占位实现，不是 2D 假画面
|
||||
|
||||
## 阶段 E: Game 真实渲染闭环
|
||||
|
||||
目标:
|
||||
|
||||
- 接上 `Game` 面板的真实 camera render path
|
||||
|
||||
主要工作:
|
||||
|
||||
1. 对齐旧 editor 的 game viewport 请求方式
|
||||
2. 使用 active scene camera 或旧 editor 当前约定的 camera 选择规则
|
||||
3. 接上 game viewport 状态显示和 resize 规则
|
||||
|
||||
验收:
|
||||
|
||||
- `Game` 面板显示真实场景相机输出
|
||||
- 与 `Scene` 共享宿主基础设施，但 camera 语义独立
|
||||
|
||||
## 阶段 F: Scene 输入、导航、拾取
|
||||
|
||||
目标:
|
||||
|
||||
- 在真实 3D 画面已经稳定的前提下，补回 Scene 交互
|
||||
|
||||
主要工作:
|
||||
|
||||
1. 迁移 scene camera navigation
|
||||
2. 迁移 focus selection
|
||||
3. 迁移 object id picking
|
||||
4. 接回 selection 路由
|
||||
|
||||
验收:
|
||||
|
||||
- 右键看、平移、缩放、聚焦等基础导航恢复
|
||||
- 点击对象能正确选中
|
||||
|
||||
## 阶段 G: Overlay / Gizmo / Editor 辅助渲染
|
||||
|
||||
目标:
|
||||
|
||||
- 继续对齐旧 editor 的 editor-only viewport 叠加能力
|
||||
|
||||
主要工作:
|
||||
|
||||
1. overlay frame cache
|
||||
2. overlay builder
|
||||
3. selection outline / orientation / transform gizmo
|
||||
4. Scene/Game 差异化 overlay policy
|
||||
|
||||
验收:
|
||||
|
||||
- Scene overlay 与 gizmo 基本达到旧 editor 可用水平
|
||||
- 不因 overlay 引入新的渲染路径分叉
|
||||
|
||||
## 6. 并行切分策略
|
||||
|
||||
这条主线不是完全串行，但前两阶段有明显关键路径。
|
||||
|
||||
### 必须串行的部分
|
||||
|
||||
1. 阶段 A 宿主 render host
|
||||
2. 阶段 B viewport 纹理桥接
|
||||
|
||||
这两步没完成，后面的 Scene/Game 真渲染都只能是假接入。
|
||||
|
||||
### 可以并行的部分
|
||||
|
||||
在 A/B 基本定型后，可并行拆为 3 组:
|
||||
|
||||
1. `Host`
|
||||
- window renderer
|
||||
- present/frame lifecycle
|
||||
- viewport texture bridge
|
||||
2. `app/Viewport`
|
||||
- render targets
|
||||
- scene/game render request owner
|
||||
- status/failure policy
|
||||
3. `XCEditor` / `app/Shell`
|
||||
- scene/game 切换到 `ViewportShell`
|
||||
- viewport 状态展示
|
||||
- 相关 integration tests
|
||||
|
||||
## 7. 明确不做的事
|
||||
|
||||
这份计划期间，不做以下偏移主线的工作:
|
||||
|
||||
- 不继续优先铺新的业务面板细节
|
||||
- 不先做 inspector/component editor 的深层业务联动
|
||||
- 不把 runtime UI 主题资源机制重新塞回 editor UI
|
||||
- 不用临时截图/静态贴图假装 viewport
|
||||
|
||||
## 8. 收口标准
|
||||
|
||||
满足以下条件，才算 `new_editor` 的 3D 渲染基础层正式收口:
|
||||
|
||||
1. `Scene` 和 `Game` 都显示真实 3D GPU 输出
|
||||
2. resize、DPI、focus、capture 行为稳定
|
||||
3. viewport 纹理链路不依赖 ImGui
|
||||
4. Scene 基础导航和 picking 恢复
|
||||
5. 后续继续重建 `new_editor` 时，不需要再回头推倒宿主渲染基础层
|
||||
|
||||
## 9. 旧计划归档说明
|
||||
|
||||
本轮归档:
|
||||
|
||||
- `docs/plan/used/NewEditor对标旧Editor迁移重建计划_2026-04-12.md`
|
||||
|
||||
保留为参考文档，不归档:
|
||||
|
||||
- `docs/plan/Editor架构说明.md`
|
||||
|
||||
原因:
|
||||
|
||||
- 它仍然是旧 editor 分层与边界的有效参考
|
||||
- 但当前主线已经从“泛迁移计划”切换为“viewport / rendering 主链正式接入计划”
|
||||
Reference in New Issue
Block a user