XCEngine/docs/plan/NewEditor_宿主重构计划_2026-04-13.md

# NewEditor 宿主重构计划

## 目标

把 `new_editor` 当前的窗口宿主从“功能可运行的过渡方案”收敛成可长期演进的 Editor 宿主架构，核心目标如下：

1. 主显示链最终统一到纯 D3D12。
2. 窗口线程只负责消息和状态，不承担 GPU 重活。
3. live resize 必须真实更新，但不能再走同步阻塞窗口线程的路径。
4. Editor shell 和 Scene/Game viewport 统一纳入宿主合成层。
5. 当前 `D3D11On12 + D2D` 只允许作为过渡路径，不能继续加深耦合。

## 当前问题

### 1. 宿主职责混在 `Application`

当前 `Application` 同时承担：

- Win32 消息调度
- 宿主运行时状态
- resize / dpi / deferred render 调度
- editor 状态更新
- present 前后的宿主控制

这会导致宿主问题难以单独定位和演进。

### 2. 主显示链过厚

当前主路径仍然依赖：

- D3D12 viewport 渲染
- swapchain backbuffer
- D3D11On12 wrapped resource
- D2D 绘制 shell
- present

这条链在 live resize、frame pacing、backbuffer 生命周期上都偏重。

### 3. resize 热路径仍然偏保守

虽然已经把 `WM_SIZE` 从直接同步 resize 调整为 deferred render 触发，但 resize 热路径里仍存在：

- backbuffer interop target 重建
- swapchain resize
- 资源生命周期收束

这还不是最终架构。

## 重构阶段

## 阶段 1：宿主分层

### 目标

先把结构理顺，停止继续把宿主逻辑堆进 `Application`。

### 任务

1. 拆出宿主运行时状态对象。
2. 拆出窗口消息调度与 deferred render 调度。
3. 让 `Application` 只保留 editor 业务更新与高层协作职责。
4. 为后续 HostRenderer / HostCompositor 留清晰边界。

### 完成标准

1. resize / dpi / deferred render / interactive resize 状态不再散落在 `Application` 成员里。
2. `Application` 的宿主状态字段明显减少。
3. 现有功能与布局不回退。

## 阶段 2：建立 HostRenderer / HostCompositor 边界

### 目标

把宿主渲染拆成明确两层：

1. `HostRenderer`
   责任：device / queue / swapchain / backbuffer / fence / present
2. `HostCompositor`
   责任：把 shell draw data、viewport texture、icon/text 统一合成到 backbuffer

### 任务

1. 停止让 `NativeRenderer` 既像窗口绘制器又像过渡 compositor。
2. 把“主窗口显示”和“UI 绘制命令解释”职责显式拆开。
3. 为纯 D3D12 compositor 做接口准备。

### 完成标准

1. `HostRenderer` 不依赖 D2D 语义。
2. `HostCompositor` 成为唯一的宿主 UI 合成入口。
3. 现有 `NativeRenderer` 明确退化为过渡层或 fallback。

## 阶段 3：主显示链切换到纯 D3D12

### 目标

去掉 `D3D11On12 + D2D` 在主显示链中的核心地位。

### 任务

1. shell 矩形、线条、图像、文字统一进入 D3D12 UI compositor。
2. Scene/Game viewport 作为普通 SRV 输入参与同一条 compositor pass。
3. backbuffer 只通过 D3D12 呈现。

### 完成标准

1. 主窗口显示不再依赖 D2D。
2. resize 时不再重建 D3D11On12 backbuffer interop target。
3. `new_editor` 主显示链可在没有 D3D11On12 的条件下工作。

## 阶段 4：重写 resize 状态机

### 目标

做到真实 live resize，但不阻塞窗口线程。

### 任务

1. `WM_SIZE` 只更新最新目标尺寸。
2. render tick 只消费最新尺寸，不处理过期尺寸。
3. resize 不允许在消息处理里做 GPU 等待。
4. resize / present / viewport surface 生命周期统一到宿主状态机。

### 完成标准

1. 拖动窗口边界时不黑屏。
2. 不出现黑白垃圾区。
3. 窗口拖动体感明显优于当前实现。

## 阶段 5：去掉 resize 路径里的全队列等待

### 目标

去掉当前最重的同步点。

### 任务

1. 改成 per-backbuffer / per-frame 生命周期管理。
2. 只等待必须退休的资源代际。
3. 禁止 resize 路径里的整队列 idle 等待。

### 完成标准

1. resize 期间 CPU/GPU 同步明显减少。
2. live resize 手感继续改善。

## 阶段 6：viewport 生命周期收口

### 目标

让 Scene/Game viewport 与外层宿主真正解耦。

### 任务

1. viewport render target 长期存活，不跟着宿主链大拆大建。
2. 宿主 compositor 只采样 viewport 结果，不干预其内部资源生命周期。
3. Scene/Game 在 interactive resize 期间保持稳定。

### 完成标准

1. viewport 不再因宿主 resize 逻辑出现黑屏或闪烁。
2. 宿主和 viewport 各自职责明确。

## 执行顺序

1. 先完成阶段 1。
2. 然后搭好阶段 2 的 HostRenderer / HostCompositor 边界。
3. 再推进阶段 3，切主显示链到纯 D3D12。
4. 最后做阶段 4、5、6 的性能与生命周期收口。

## 当前落点

当前阶段 1 已完成，阶段 2 已开始收口：

1. 已新增 `HostRuntimeState`，把宿主 DPI / interactive resize / pending resize / deferred render 状态从 `Application` 中抽离。
2. 已新增 `WindowMessageDispatcher`，把 `WndProc` 中的宿主消息调度与 deferred render 调度拆到 `Host` 层。
3. 已把 `D3D12WindowRenderLoop` 从悬空 helper 升级为主窗口帧编排入口，开始统一 `BeginFrame / viewport render / UI present / fallback / resize interop` 这条链。
4. 已把 viewport render target 资源工厂从 `ProductViewportRenderTargets.h` 收成独立 manager，`ProductViewportHostService` 只保留请求/返回 frame 的业务外壳。
5. 已把 shader resource descriptor 分配职责从 `D3D12WindowRenderer` 抽到独立的 `D3D12ShaderResourceDescriptorAllocator`，减少窗口呈现器的非 swapchain 职责。
6. 下一步进入阶段 2 主体：继续拆 `NativeRenderer` 中的窗口互操作 / present 组合路径，把 D2D UI 光栅化与 D3D11On12 窗口合成进一步分离。