XCEngine/docs/used/XCUI_Subplan-05_ImGui_Transition_Backend_完成归档_2026-04-04.md

XCUI Subplan 05: ImGui Transition Backend

归档日期：

• 2026-04-04

状态：

• 已完成

本次实际完成内容：

• 新增 XCUI 绘制数据契约：UIColor、UIDrawCommandType、UIDrawCommand、UIDrawList、UIDrawData
• 新增 ImGuiTransitionBackend 过渡后端，支持 FilledRect、RectOutline、Text、Image、PushClipRect、PopClipRect
• 新增最小 editor 接入样例 XCUIDemoPanel，用于在现有编辑器壳层中演示 XCUI draw data 到 ImGui draw call 的过渡链路
• 将 demo panel 接入 editor workspace，并补齐 editor/tests 构建入口
• 新增 Subplan-05 配套测试，覆盖 draw data 聚合与 backend flush 行为

本次涉及文件：

• editor/CMakeLists.txt
• editor/src/Core/EditorWorkspace.h
• editor/src/XCUIBackend/ImGuiTransitionBackend.h
• editor/src/panels/XCUIDemoPanel.cpp
• editor/src/panels/XCUIDemoPanel.h
• engine/include/XCEngine/UI/DrawData.h
• tests/editor/CMakeLists.txt
• tests/editor/test_xcui_draw_data.cpp
• tests/editor/test_xcui_imgui_transition_backend.cpp

验证结果：

• cmake --build . --config Debug --target editor_tests -- /m:1 /p:CL_MPCount=1
• ctest -C Debug -R "XCUIDrawDataTest|XCUIImGuiTransitionBackendTest" --output-on-failure
• 结果：4/4 通过
• cmake --build . --config Debug --target XCEditor -- /m:1 /p:UseMultiToolTask=false /p:CL_MPCount=1
• 结果：通过

提交记录：

• 75ded6f Add XCUI ImGui transition backend MVP

当前结论：

• Subplan-05 的最小过渡后端已经可用，可以作为 XCUI 在 editor 中落地的第一层渲染适配桥
• XCUI 逻辑层仍然不直接依赖 ImGui API，ImGui 仅存在于过渡 backend 和 editor 接入层
• 后续 Subplan-08、Subplan-09 可以直接基于这套 draw data 和 transition backend 继续推进

原始 subplan 内容归档如下：

Subplan 05：XCUI ImGui Transition Backend

目标：

• 在过渡阶段，让 ImGui 只承担宿主窗口和 draw submission 容器的职责
• 由 XCUI 自己生成 draw list，再交给 ImGui backend 落屏

负责人边界：

• 负责 editor/src/XCUIBackend/ 或等价新目录
• 负责 XCUI draw primitive 到 ImGui draw call 的映射
• 不负责 XCUI tree、布局、样式的内部规则

建议目录：

• editor/src/XCUIBackend/
• editor/src/UI/ 中与 XCUI backend 直接相关的桥接代码
• tests/Editor 中 backend 相关测试

前置依赖：

• 需要 Subplan-01 给出稳定 draw data 和 frame submission 契约
• 需要 Subplan-03 提供样式查询结果

现在就可以先做的内容：

• 定义 UIDrawList / UIDrawCommand / UIDrawText / UIDrawImage / UIDrawClip
• 先做矩形、边框、文字、图片四类 primitive
• 设计 frame begin / submit / end 的 adapter 流程
• 写一个最小 demo panel，用 XCUI draw list 通过 ImGui 显示

明确不做：

• 不做 RHI native backend
• 不做 docking 逻辑

交付物：

• XCUI 到 ImGui 的过渡 backend
• primitive 转换测试或快照测试
• 最小 editor 接入样例

验收标准：

• XCUI 逻辑层不直接依赖 ImGui API
• ImGui 只出现在 backend 适配层
• 可以渲染基础控件和文本