本资料是 MuJoCo 及其 Python 绑定、WebViewer 等目标的 Dear ImGui 界面开发与架构指南,适用于 C++(ImGui::)与 Python(imgui.)两种写法。核心要点如下。
用途与命名:ImGui 不直接渲染像素,而是记录绘制命令列表;提交 UI 控件的函数应命名为 build_gui、build_xxx_gui(Python)或 BuildGui、BuildXxxGui(C++),render/draw 仅保留给底层图形后端操作。
解耦与可测试性:GUI 只负责布局、呈现和输入转发,业务逻辑、网络/RPC、文件操作、仿真步进不得混入帧构建函数;核心逻辑应放入独立库(如 inspector_lib.py 与 inspector_gui.py 分离),耗时操作放到工作线程,GUI 读取缓存状态。
自定义控件:写成即时模式纯函数,尽量无每控件持久状态;共享控件置于 Studio UX 模块的 imgui_widgets.h/cc;实现前应查上游 changelog、GitHub issues 与 Wiki,若功能已在上游则优先更新依赖。构建时定义 IMGUI_DISABLE_OBSOLETE_FUNCTIONS 和 IMGUI_DISABLE_OBSOLETE_KEYIO,避免使用 imgui_internal.h 等内部头文件。
性能:长列表/表格/日志必须用 ImGuiListClipper(C++)或 imgui.ListClipper(Python)虚拟化,仅提交可见项;大段只读文本用 imgui.TextUnformatted。
ID 栈:## 会隐藏后缀并参与哈希,用于区分同名控件;### 会重置哈希种子、丢弃其前文字,用于可见文本变化时保持 ID 稳定;图标按钮如 f'{ICON_FA_PLAY}###PlayButton' 可提供语义化标识;也可用 PushID/PopID 作用域。
布局与主题:网格排列优先用 Tables API(BeginTable、TableNextRow、TableNextColumn),避免过时的 Columns() 和手工 SameLine 偏移;颜色使用语义令牌如 imgui.Col.Text、imgui.Col.FrameBg,或经 GetStyleColorVec4 获取,避免硬编码 RGB,必要时成对 PopStyleColor/PopStyleVar。此外,用户可见字符串尽量写在单行便于源码搜索;Python 绑定应保持薄封装、按需添加且不删除、并与上游 C++ 头文件顺序一致;键盘快捷键前须检查 not imgui.GetIO().WantCaptureKeyboard;打开搜索框或弹窗时用 imgui.SetKeyboardFocusHere() 设置初始焦点。Dear ImGui Test Engine 目前未随 MuJoCo 捆绑,但计划支持;具体版本、安装与授权细节暂未提供。