XCEngine/docs/plan/NewEditor_ArchitectureClosurePlan_2026-04-22.md

NewEditor Architecture Closure Plan

Date: 2026-04-22

1. Objective

彻底收口 new_editor 当前仍然残留的旧语义、冗余结构和重复控制面。

这次不是补丁式修正，而是把当前主架构重新收成单一路径：

1. 主窗口 UI 渲染只保留一条 D3D12 实例化 primitive pass。
2. 启动截图策略只保留一个控制源。
3. Rendering/Native 这层已经失效的旧模块边界被移除。
4. 已确认无用的死代码和错误语义命名被清理。

2. Confirmed Root Issues

2.1 D3D12 UI renderer still contains a legacy geometry sub-pipeline

当前 D3D12UiRenderer 虽然已经是 D3D12 主路径，但内部仍然并存两套 UI 几何编译/提交策略：

1. QuadInstanced
2. LegacyIndexed

其中绝大多数 UI 命令已经走实例化 primitive 路径，只有少量三角形命令仍然维持整套：

• legacy vertex buffer
• legacy index buffer
• legacy pipeline state
• legacy batch kind

这会导致：

• UI renderer 不是单一路径
• 缓冲管理、缓存结构、绘制分发继续为旧几何方案付复杂度成本
• “legacy” 语义真正活着，而不是只有名字没改

2.2 Startup auto-capture ownership is split across two layers

当前 startup capture 既在 EditorWindowScreenshotController::Initialize(...) 内通过环境变量触发， 又在 EditorWindowRuntimeController::Initialize(...) 内通过 autoCaptureOnStartup + env 触发。

这导致：

• 策略决定权不是单点
• autoCaptureOnStartup 形参不是唯一真实来源
• 非主窗口也可能被环境变量隐式触发 startup request

2.3 Rendering/Native module boundary is obsolete

app/Rendering/Native/ 目录现在只剩 AutoScreenshot.*。

它已经不再承担旧的 native renderer backend 职责，但目录和 include 关系仍然保留旧时代边界。

2.4 Confirmed dead code remains in the hot renderer unit

D3D12UiRenderer.cpp 里存在已无调用方的辅助函数，说明之前的旧几何阶段没有清理彻底。

3. Target End State

完成后应满足：

1. D3D12UiRenderer 不再存在 LegacyIndexed / legacy* 动态几何资源。
2. 所有 UI draw command 都编译为同一类实例化 primitive 数据。
3. 渲染时只绑定一套 UI primitive pipeline。
4. EditorWindowScreenshotController 不再自行读取 startup env，也不再拥有策略判断权。
5. startup capture 是否发生，只由窗口创建策略单点决定。
6. Rendering/Native 目录被清空或完全移除。
7. 已确认无调用的渲染死代码删除。

4. Refactor Strategy

Phase A. Collapse UI geometry into one primitive pipeline

把当前 UI pass 改成单一实例化 primitive 方案：

• 保留单位 quad carrier vertex/index buffer
• 删除动态 legacy vertex/index buffer
• 删除 legacy pipeline state
• 删除 legacy batch kind
• 统一 batch 为 instance range + texture + scissor

需要新增的 primitive 能力：

• 现有 rect / outline / circle / text / image / gradient
• 新增 triangle primitive，让 FilledTriangle 也走实例化路径

triangle 的正确实现目标：

• 不是回退到 indexed geometry
• 不是临时特判 draw call
• 而是作为实例化 primitive 的一种 kind，被统一编译、缓存、上传和绘制

Phase B. Rebuild renderer data model around the unified path

同步调整：

• UiBatchKind 去除或退化
• UiQuadInstance 升级为更通用的 UiPrimitiveInstance
• CompiledDrawList 不再缓存 legacy vertices / indices
• EnsureFrameBufferCapacity(...) 只维护 primitive instance buffer
• render dispatch 只保留单一 pipeline bind 分支

Phase C. Collapse startup capture ownership to one source of truth

把 startup capture 的策略权上移并单点化：

• Application 或窗口创建层读取 env / policy
• CreateParams.autoCaptureOnStartup 成为唯一窗口级输入
• EditorWindowRuntimeController 只消费该参数
• EditorWindowScreenshotController 只做请求/路径/结果管理，不做策略判断

Phase D. Remove obsolete Native module shell

将截图控制器从 app/Rendering/Native/ 迁移到更合理的位置， 预计是窗口运行时或通用 support/capture 模块。

要求：

• 迁移后 active include 不再引用 Rendering/Native
• new_editor/CMakeLists.txt 同步更新

Phase E. Delete dead helpers and normalize semantics

删除已经确认无调用的旧辅助函数，并统一命名：

• legacy* -> 按真实职责改名，或随着删除一起消失
• 清理无用 helper
• 保证 renderer 术语与当前架构一致

5. File-Level Work

5.1 UI renderer core

Primary:

• new_editor/app/Rendering/D3D12/D3D12UiRenderer.h
• new_editor/app/Rendering/D3D12/D3D12UiRenderer.cpp

5.2 Startup capture boundary

Primary:

• new_editor/app/Bootstrap/Application.cpp
• new_editor/app/Platform/Win32/EditorWindow.cpp
• new_editor/app/Platform/Win32/EditorWindowRuntimeController.h
• new_editor/app/Platform/Win32/EditorWindowRuntimeController.cpp
• new_editor/app/Platform/Win32/EditorWindowManager.h

5.3 Screenshot controller relocation

Current source:

• new_editor/app/Platform/Win32/EditorWindowScreenshotController.h
• new_editor/app/Platform/Win32/EditorWindowScreenshotController.cpp

Target:

• move into non-legacy module location

5.4 Build graph cleanup

• new_editor/CMakeLists.txt

6. Validation

6.1 Structural validation

完成后搜索应满足：

• no LegacyIndexed in active UI renderer
• no m_legacyPipelineState
• no legacyVertexBuffer
• no legacyIndexBuffer
• no app/Rendering/Native/AutoScreenshot.* active include path

6.2 Runtime validation

必须验证：

1. XCUIEditorApp Debug 构建通过
2. editor 正常启动
3. 主窗口 UI 正常显示与交互
4. startup auto-capture 正常生成
5. detached window 不会错误触发 startup capture

7. Completion Criteria

只有满足以下条件，这个 plan 才算真正收口：

1. UI 渲染路径内部不再存在旧几何子管线
2. startup capture 策略控制权单点化
3. 旧 Native 模块边界消失
4. 死代码删除
5. 构建、启动、截图验证全部通过