Dear ImGui 架构拆解：为什么 74k 星的 C++ GUI 库选择了即时模式

核心判断

Dear ImGui 解决的不是"画一个 GUI 控件"的问题，而是"程序员在调试工具、可视化脚本、引擎编辑器这种场景里，如何避免维护一个 UI 状态与业务状态的双重数据源"的问题。它的做法是把整套渲染状态压缩成一组每帧调用的命令，不存 UI 状态对象，只存绘图原语，让源代码本身成为 UI 的 source of truth。从这个角度看它的架构选择，能立刻明白它和 Qt、Electron、Flutter 之间的边界。

项目坐标

仓库主分支的 docs/README.md（注：仓库根目录无 README.md，主入口在 docs/）开篇引用了 ryg 的一句调侃——“给某人状态，他今天就会有 bug；教他把状态写在两处再同步，他会持续有 bug一辈子”。这句话基本是 imgui 整个设计哲学的导语。

IMGUI 范式的本质

把"UI 状态"从库内部搬到调用方代码里

传统 GUI（Qt、WPF、SwiftUI、Flutter）采用 retained mode：你在代码里创建一个对象（Button btn;），库内部维护它的选中态、悬停态、位置、文字。每一帧库负责"渲染这个对象"。这意味着业务逻辑和 UI 状态需要双向同步：用户点击 → 库改 btn.checked → 业务代码读 btn.checked → 业务代码改 btn.checked → 库下次渲染。

这套范式对应用开发者很友好（声明式、所见即所得），但对工具开发者（调试器、内存查看器、引擎编辑器）有结构性不便：因为这些工具的 UI 是高度动态的——只有当前帧才存在的窗口、被调试对象一变化就要改的字段、调试会话结束就消失的面板。用 retained mode 表达这些场景，意味着要么发明一套完全动态的 GUI 库，要么手写 cleanup 逻辑。

imgui 的做法是 immediate mode：每帧重新描述 UI。伪代码直觉版本：

ImGui::Begin("Memory Inspector");
for (auto& obj : scene.objects()) {
    ImGui::Text("%s : %d bytes", obj.name.c_str(), obj.size);
    if (ImGui::SmallButton("release")) obj.pool.release(obj);
}
ImGui::End();

没有 Button 对象，没有 listener，没有 commit/revert。当 scene.objects() 被释放时，UI 自动消失——因为下一帧那段循环跑不到那个对象。当 obj.size 变了，下一帧显示的数字自动变——因为每帧重写 Text。

README 里 Omar 自己澄清了一个常见误解：immediate mode GUI ≠ immediate mode rendering。imgui 不让你每调一次 Text 就给 GPU 发一个 draw call。它把这一帧的所有调用收集到一个顶点缓冲 + 命令列表里，一次性交给 GPU。这意味着你的渲染器依然是 batched rendering，只是"描述 UI 的方式"变成了每帧重写。

状态该有还是要有的：库内部维护"输入态"，但不维护"UI 对象"

完全无状态的 IMGUI 是没用的——点击事件本帧在哪个 widget 上落点？悬停态怎么追踪？这些"输入态" imgui 必须在库内部维护。这块是 imgui.cpp 里 ImGuiIO 结构体 + 内部 ImGuiWindow / ImGuiInputData 子系统的职责。

关键区分：

• 库不维护的：UI 树本身、widget 句柄、回调注册、属性数据。
• 库维护的：当前帧的热点（hot item）、当前激活（active item）、鼠标位置、上一次点击时间、窗口的折叠/展开状态、滚轮速度。

这套边界既是 IMGUI 的力量，也是它的局限：库不需要复杂的 scene graph 调度，但调用方需要承担"UI 描述与业务状态同步"的责任。这部分责任通过一个简单约定收回——业务代码自己持有业务数据，UI 代码只是它的视图函数。

系统地图：核心模块边界

imgui 的"核心文件可以整体塞进你工程里编译"这条设计直接体现在这张表里——除了 demo，所有需要编译的源文件都在根目录的 imgui*.cpp / imgui*.h 里，新增功能不需要改 CMake，不需要配 dll 版本号。后端则是另一棵树。

任务流案例：一次点击如何被处理

下面把抽象机制用一次具体动作串起来——用户点击一个 Button("Save")，触发业务侧的 MySaveFunction()：

┌─────────────────────┐          ┌─────────────────────┐
│  后端（SDL2/GLFW）  │          │   业务侧代码         │
└─────────────────────┘          └─────────────────────┘
         │                               │
   鼠标点击事件                         每帧调用
   MouseDown(x,y)                       ImGui::Button("Save")
   │                                   │
         ▼                               │
   ImGui_ImplSDL2_ProcessEvent          │
   ├─ ImGui::GetIO()                    │
   ├─ io.AddMouseButtonEvent(0, true)   │
   │                                    ▼
   │                              ImGui 接收鼠标状态
   │                              ├─ 更新 ImGuiInputData
   │                              ├─ 计算本帧 hot item
   │                              └─ 保存历史点击位置
   ▼
   ImGui::NewFrame()  ←─ 后端调用，触发输入数据 reset
   ImGui::Button("Save")
   ├─ 算当前 item bbox
   ├─ 命中测试：mouse 是否在 bbox 内？
   │  → 是：item 设为 hot
   ├─ 检查 io.MouseClickedThisFrame[0]
   │  → 是：item 设为 active
   ├─ 检查 active item 当前帧是否被 release
   │  → 是：返回 true，触发回调
   ▼
   if (ImGui::Button("Save"))
       MySaveFunction();   ←─ 业务回调
   ▼
   ImGui::Render()  ←─ 后端调用
   ├─ 收集所有 draw command
   ├─ 生成 ImDrawData
   ▼
   ImGui_ImplOpenGL3_RenderDrawData(...)
   ├─ 拿到 ImDrawData.vertex/cmd lists
   ├─ 生成 OpenGL draw call
   ▼
   屏幕显示一帧

整个流程没有任何 widget 对象持久存在。Button 调用结束的瞬间，相关数据结构就出栈了。active item 是库内部输入态的一部分，它在下一帧 NewFrame() 时清零——这意味着跨帧"按住"必须靠业务侧手动调用 Button(..., ImGuiButtonFlags_Repeat) 或自己拿 IsItemActive() 持续判断。

关键设计取舍

1. 单上下文 vs 多上下文

imgui 默认一个进程一个 ImGuiContext。这对工具程序 99% 够用。多上下文也支持（每个上下文独立 IO + style），代价是必须手动 SetCurrentContext(ctx) 切换。不默认多上下文是有意的——它逼调用方想清楚"这个程序到底有几套独立的 UI 状态"。游戏引擎内嵌"调试 GUI"通常一个上下文；并行测试运行的 harness 各自一个上下文。

2. 字体：内置 stb_truetype，附带 Proggy 字体

imgui_draw.cpp 里嵌入了一份 stb_truetype.h，意味着你不需要额外装 FreeType。默认字体是 ProggyClean（docs/CHANGELOG.md 提到 ProggyForever 是更新版）。这套"自带光栅化"的代价是：超大字体（>5MB ttf）、复杂脚本（阿拉伯文从右到左、印度文连写、emoji 字距）会比较吃力，但 99% 的英文 UI、调试信息、ASCII 日志完全够用。

3. 输入：不参与主循环，自己轮询

imgui 不订阅窗口系统的事件回调，而是要求调用方把"这帧发生了什么"塞进 ImGuiIO：

ImGuiIO& io = ImGui::GetIO();
io.AddMousePosEvent(x, y);
io.AddMouseButtonEvent(0, true);  // left mouse down
io.AddKeyEvent(ImGuiKey_A, true);
io.AddTextUTF16(buf, len);        // 字符输入（unicode）

这是 imgui “无外部依赖” 的代价——你必须自己做事件翻译。backends/imgui_impl_sdl2.cpp / imgui_impl_glfw.cpp 之类的文件就是把 SDL2/GLFW 的事件格式手动转成这种"IO 事件"格式。这也是为什么后端代码那么多，但 backends/ 之外没有"主线事件循环"。

4. 绘图输出：ImDrawData 是数据结构，不是渲染后端调用

ImDrawData draw_data = ImGui::GetDrawData();
// draw_data 包含：cmd lists, idx/vert buffers, texture id, clip rect

ImDrawData 是纯 POD 描述（顶点缓冲 + 索引缓冲 + 纹理 + 裁剪矩形列表），后端把它转成自己的渲染 API 调用。这意味着：理论上你可以写一个 imgui + 自定义 Vulkan rendering pipeline 的工程而不碰任何 OpenGL 代码，imgui 不替你做 viewport 管理、不做 viewport/scissor pipeline state 自管理（裁剪靠 scissor 而非 stencil）。

5. Docking 与 Multi-Viewport：放在 docking 分支

master 分支是稳定主干，docking 分支额外提供 docking（多窗口可停靠）+ multi-viewport（一个进程渲染到多个 OS 窗口）。docking 分支定期 rebase 到 master，README 建议"高级用户可以用 docking 分支，但 master 也够用"。这种分支隔离让稳定主线不背兼容性包袱。

6. 国际化与无障碍：明确不支持

README 直说：“righ-to-left text, bidirectional text, text shaping, accessibility features are not supported”。这不是疏忽，是边界声明——imgui 把自己定位为"程序员内嵌调试器"，不是"终端用户 UI 框架"。如果你要做一个面向最终用户的应用，应该用 Qt / Flutter / React Native 之类的东西，再在调试版本里嵌 imgui。

与其他 GUI 框架的边界

一个简单的判断准则：你的 UI 由谁负责维护状态？ 如果是程序员自己，imgui 很自然；如果是设计师画图后由开发实现，Retained mode 更自然。

集成与构建

不依赖任何构建系统的最小集成方式：

// 把以下文件加入你工程的某个 source group：
//   imgui.cpp, imgui_draw.cpp, imgui_tables.cpp, imgui_widgets.cpp
//   imgui.h, imgui_internal.h, imgui_demo.cpp（可选）
//   backends/imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp（GLFW + OpenGL 的组合）
//
// main loop:
while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    
    ImGui_ImplOpenGL3_NewFrame();
    ImGui_ImplGlfw_NewFrame();
    ImGui::NewFrame();
    
    // --- 你的 UI 代码 ---
    ImGui::Begin("Debug");
    ImGui::Text("FPS: %.1f", ImGui::GetIO().Framerate);
    if (ImGui::Button("Reload")) LoadScene();
    ImGui::End();
    
    ImGui::Render();
    ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
    
    glfwSwapBuffers(window);
}

C++20 模块用户可以用 stripe2933/imgui-module（README 提到的第三方）。第三方语言绑定由 cimgui 和 dear_bindings 仓库自动生成元数据并产出对应语言的绑定文件（C#、Go、Rust、Lua、Python、Swift、Zig、Ruby 等），覆盖面非常广。

何时用 / 何时不用

适合的场景：

• 游戏引擎的内部编辑器（关卡编辑器、Inspector、资源浏览）。
• 调试工具（内存检查器、网络包查看器、shader 热编辑器）。
• 实时数据可视化（profiler、波形图、节点图）。
• 临时脚本工具（“我需要在程序里改个参数，看效果”）。
• 资源受限环境（嵌入式、控制台）—— 因为 imgui 几乎零运行时依赖。
• 任何"这个工具只活一天/一周"的快速开发。

不适合的场景：

• 面向终端用户的桌面应用（SaaS 客户端、消费类软件）。
• 需要完整国际化（包括 RTL、双向文本）的产品。
• 需要辅助功能（屏幕阅读器、键盘导航、对比度）的产品。
• 多媒体文档编辑器（图片、视频、设计稿）—— ImGui 的文本编辑能力薄弱。
• 大规模团队多人协作维护的 UI 库—— imgui 没有"声明式 UI diff"的明确边界。

Benchmark 与性能

imgui 的性能特点要分清测的是哪部分：

imgui 自己没有正式的 benchmark suite，Dear ImGui Test Engine 是单独仓库（ocornut/imgui_test_engine），更适合做回归测试和性能追踪。

与"扩展"的边界

README 列出三类推荐的扩展：

• ImPlot（epezent/implot）—— 2D 绘图（折线、散点、热图）。
• ImPlot3D（brenocq/implot3d）—— 3D 绘图。
• Dear ImGui Test Engine（ocornut/imgui_test_engine）—— 自动化 UI 测试。

还有 Wiki 的 “Useful Extensions” 页面列出了节点编辑器、时间轴编辑器、自动测试、文本编辑器等多个三方扩展。这些扩展都共用 imgui 的绘图原语，不重做窗口 / 输入栈，所以"加一个节点编辑器"在工程上的成本远低于在 Qt 里加一个节点编辑器。

阅读路径建议

1. 先跑 examples/example_glfw_opengl3/——5 分钟编译，看到 demo 窗口，触发一下 ShowDemoWindow() 的所有示例。
2. 翻 imgui_demo.cpp 找最贴近你场景的 widget——里面的代码就是可以直接复制粘贴的样板，且附带注释。
3. 只看 imgui.h 的 struct 注释，不读 .cpp——imgui.h 头文件里每个公开 struct 字段都有注释，比阅读 .cpp 实现快得多。
4. 学习后端文件的"事件翻译"——你的事件格式只要学会翻译到 imgui 的 IO API 就能用。
5. 只在 debug 版本启用——release 不带 save/load 按钮的 UI，避免 UI 体积膨胀。

参考资源

• 主仓库：https://github.com/ocornut/imgui
• 测试引擎：https://github.com/ocornut/imgui_test_engine
• FAQ：https://github.com/ocornut/imgui/blob/master/docs/FAQ.md
• 后端使用指南：https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md
• IMGUI 范式 Wiki：https://github.com/ocornut/imgui/wiki#about-the-imgui-paradigm
• Web 版 demo 浏览器：https://pthom.github.io/imgui_explorer（imgui_explorer）
• 语言绑定元数据生成：https://github.com/cimgui/cimgui 与 https://github.com/dearimgui/dear_bindings