【ZeloEngine】ImGui汇总

需求

游戏内置菜单（In-Game Menus）

GM界面，这是一个程序编写的界面

需求：

程序化的，代码驱动的界面
无需美术拼UI，注重实用，不太在乎美观
跨平台
入口，一键呼出，PC可以是快捷键，手机可以是一个可以移动的小按钮，手柄可以是一个组合键

以下图片来自《游戏引擎架构》

顽皮狗是自己定制的一个界面，属于ImGui的子集

Main development menu

Rendering submenu

Mesh options subsubmenu

Background meshes turned off

使用Icon

前面虽然说实用优先，不需要表面功夫，不过话说回来

程序开发的界面，Icon是一个很好的优化，美观，提供视觉引导

这种引导是潜移默化的，即使你不去看手册，一个有Icon的编辑器用多了，自然会看Icon来识别出哪个功能在哪里

而没有Icon的编辑器，则一直需要看文字来找位置

案例二

Images and Icons for Visual Studio - Visual Studio | Microsoft Docs

Icon Download

案例二

阿比盖尔 | Don’t Starve 中文維基 | Fandom

本地化

编辑器本地化有标准方案，参考Godot

说实话，对于国内团队，中文编辑器是刚需

大部分人的英文水平，仍然需要中文编辑器来达到最好的编辑效率

ImGui

如何开发/编程指南

ImGui基本原理
ImGui框架概念
ImGui接口
脚本绑定接口
脚本薄封装框架
参考项目

痛点

原理学完只是第一步，我们要铺量去写UI，那工具链要是完善的

目前抄了几个界面后的痛点是：对接口不熟悉，查接口要跳很多文档

理想的状态是：Model数据结构=》设计粗略View展示Model=》转换成代码=》迭代交互和样式

接口文档

https://blog.csdn.net/zolo_mario/article/details/120359861?spm=1001.2014.3001.5501

https://blog.csdn.net/zolo_mario/article/details/120357560?spm=1001.2014.3001.5501

https://blog.csdn.net/zolo_mario/article/details/120359935?spm=1001.2014.3001.5501

Doc/Editor/ImGui/**

imgui的文档维护比较糟糕，接口文档都在代码里，所以我整理了一份文档

脚本绑定接口

原文档

imgui_patch.lua

文档导出的桩文件，基本可用，按需要改即可

脚本绑定方案和接口，可以多看看几个方案，但是持续维护目前的就够了

主要是由于C和Lua的差异，脚本接口是有微小差异的，所以需要维护一套

ImGui Demo 自解释

ImGui本身有很多参数，ImGui本身又是一个参数编辑器框架，所以Demo基本就是自己编辑自己

UI框架

基本架构

ImGui(C++) => sol wrapper => ImGui(Lua) => ImGui Framework

框架主要是做一个薄封装和分类，便于开发

薄封装

ImGui接口本身都是全局函数，有两个问题：

没有做分类，量很大，从开发者角度有一些冗余
- 同样功能不同接口二选一，Column和Table
- 实际用不到的
- 过时的接口
- beta接口
脚本绑定后Lua接口和C接口的差异
ImGui更新（docking分支目前仍然不是主分支），后向兼容性的风险

脚本绑定减少重载

既然脚本层封装了，那么绑定层就不要提供太多重载，影响性能

以MenuItem为例，下面这样写太复杂了，封装成一个接口就可以了

bool MenuItem ( const  char * label, const  char *shortcut = NULL , bool selected = false , bool enabled = true );
激活时返回真。bool MenuItem ( const  char * label, const  char * shortcut, bool * p_selected, bool enabled = true );
激活时返回 true + toggle (*p_selected) 如果 p_selected != NULL

inline bool MenuItem(const std::string &label) { return ImGui::MenuItem(label.c_str()); }inline bool MenuItem(const std::string &label, const std::string &shortcut) {return ImGui::MenuItem(label.c_str(), shortcut.c_str());
}inline std::tuple<bool, bool> MenuItem(const std::string &label, bool selected) {bool activated = ImGui::MenuItem(label.c_str(), nullptr, &selected);return std::make_tuple(selected, activated);
}inline std::tuple<bool, bool> MenuItem(const std::string &label, const std::string &shortcut, bool selected) {bool activated = ImGui::MenuItem(label.c_str(), shortcut.c_str(), &selected);return std::make_tuple(selected, activated);
}inline std::tuple<bool, bool> MenuItem(const std::string &label, const std::string &shortcut, bool selected,bool enabled) {bool activated = ImGui::MenuItem(label.c_str(), shortcut.c_str(), &selected, enabled);return std::make_tuple(selected, activated);
}

--- Parameters A: text (label), text (shortcut) [0]
--- Parameters B: text (label), text (shortcut), bool (selected)
--- Parameters C: text (label), bool (selected)
--- Returns A: bool (activated)
--- returns B: bool (selected), bool (activated)
--- Overloads
--- activated = ImGui.MenuItem("Label")
--- activated = ImGui.MenuItem("Label", "ALT+F4")
--- selected, activated = ImGui.MenuItem("Label", selected)
--- selected, activated = ImGui.MenuItem("Label", "ALT+F4", selected)
--- selected, activated = ImGui.MenuItem("Label", "ALT+F4", selected, true)
--- ```
function ImGui.MenuItem(label, shortcut, selected) end

本地化

略，没空

UI图片

ImGui接受GL的纹理ID

Docking

https://github.com/ocornut/imgui/issues/2109

把多个窗口合并到一个窗口的分页
把窗口吸附到窗口边上
多视口，是指可以把imgui窗口拖出Windows窗口独立存在
- 这个目前仅在Windows上测试通过
- 这个功能对代码的改动比较大

接口

启用Docking

ImGuiManager.EnableDocking

PanelWindow启动Docking

local DefaultPanelWindowSettings = {dockable = true;
}

撤销机制 Undo/Redo

https://github.com/ocornut/imgui/issues/1875

Lua脚本兼容性

指针参数

指针参数被额外用作返回值，也就是in+out

lua肯定是没有这种用法，对应改成额外返回值即可

也就是说，原来一个变量，要改成传入参数，再传出结果

lua变量open传入C时，C API会解包做拷贝传参，成为局部变量，对lua的open是没有影响的

p_open还额外携带bool信息，lua没有可空类型，一般还是额外传参数

bool ImGui::Begin(const char* name, bool* p_open, ImGuiWindowFlags flags)window->HasCloseButton = (p_open != NULL);

函数重载

C函数重载，基本靠动态解析lua传来的参数来匹配

有两个问题，脚本重构火葬场，和解析性能

首先有一个痛点，就是IDE，因为lua IDE是没法辅助重载的，基本靠文档和人脑记忆

大批量写代码时，跑到才会报错，非常蛋疼

然后就是重载的越多，解析越复杂

所以应该限制重载

以BeginChild为例

脚本绑定之后没有额外开销，最后都是调用一个函数

这里重载是为了默认参数，其实文档用最长的即可

脚本接口

-- ImGui.BeginChild(...)
-- Parameters: text (name), float (size_x) [O], float (size_y) [O], ImGuiWindowFlags (flags) [O]
-- Returns: bool (shouldDraw)
-- Overloads
shouldDraw = ImGui.BeginChild("Name", 100)
shouldDraw = ImGui.BeginChild("Name", 100)
shouldDraw = ImGui.BeginChild("Name", 100, 200)
shouldDraw = ImGui.BeginChild("Name", 100, 200, true)
shouldDraw = ImGui.BeginChild("Name", 100, 200, true, ImGuiWindowFlags.NoMove)-- ImGui.EndChild()
ImGui.EndChild()

脚本绑定

bool BeginChild(const std::string &name) { return ImGui::BeginChild(name.c_str()); }bool BeginChild(const std::string &name, float sizeX) { return ImGui::BeginChild(name.c_str(), {sizeX, 0}); }bool BeginChild(const std::string &name, float sizeX, float sizeY) {return ImGui::BeginChild(name.c_str(), {sizeX, sizeY});
}bool BeginChild(const std::string &name, float sizeX, float sizeY, bool border) {return ImGui::BeginChild(name.c_str(), {sizeX, sizeY}, border);
}bool BeginChild(const std::string &name, float sizeX, float sizeY, bool border, int flags) {return ImGui::BeginChild(name.c_str(), {sizeX, sizeY}, border, static_cast<ImGuiWindowFlags>(flags));
}ImGui.set_function("BeginChild", sol::overload(
sol::resolve<bool(const std::string &)>(BeginChild),
sol::resolve<bool(const std::string &, float)>(BeginChild),
sol::resolve<bool(const std::string &, float, float)>(BeginChild),
sol::resolve<bool(const std::string &, float, float, bool)>(BeginChild),
sol::resolve<bool(const std::string &, float, float, bool, int)>(BeginChild)
));

调到的内核接口

bool BeginChild(const char* str_id, const ImVec2& size = ImVec2(0, 0), bool border = false, ImGuiWindowFlags flags = 0);

控件ID

为什么控件交互没有反应？

https://github.com/ocornut/imgui/blob/master/docs/FAQ.md#q-why-is-my-widget-not-reacting-when-i-click-on-it

ImGui隐式维护ID，控件树中的控件路径被hash来标识一个控件

每个控件的接口一般都有label，是该控件的ID

所以传空串就会导致无法交互，解决是用##XXX来标识，这些在显示时被忽略

因为复杂的控件其实维护了状态，比如树节点，有开关状态，所以在帧之间需要标识，这个控件调用就是这个控件

ID

ID可以是字符串（label参数），索引，或者指针
索引指针用于标识列表控件中的item
PushID/PopID用于手工构造作用域，来解决冲突
因为label还承担显示名字的作用，用##XXX来解决ID冲突

用指针做ID的例子，不过lua脚本没法这么用，可以用##i来标识

int i;
bool node_open = ImGui.TreeNodeEx((void*)(intptr_t)i, node_flags, "Selectable Node %d", i);

// ID堆栈/范围
//阅读 FAQ（docs/FAQ.md 或 http://dearimgui.org/faq）以了解有关如何在 Dear imgui 中处理 ID 的更多详细信息。
// - 通过对 ID 堆栈系统的理解来回答和影响这些问题：
//    - “问：为什么我的小部件在我点击时没有反应？”
//    - “问：我怎样才能拥有带有空标签的小部件？”
//    - “问：我怎样才能拥有多个具有相同标签的小部件？”
// - 简短版本：ID 是整个 ID 堆栈的哈希值。如果您在循环中创建小部件，您很可能
//   想要推送一个唯一标识符（例如对象指针、循环索引）来唯一区分它们。
// - 您还可以在小部件标签中使用“标签##foobar”语法来区分它们。
// - 在这个头文件中，我们使用“标签”/“名称”术语来表示将显示的字符串 + 用作 ID，
//   而 "str_id" 表示仅用作 ID 且不正常显示的字符串。
void           PushID ( const  char * str_id);                                     //将字符串推入 ID 堆栈（将哈希字符串）。
void           PushID ( const  char * str_id_begin, const  char * str_id_end);       //将字符串推入 ID 堆栈（将哈希字符串）。
void           PushID ( const  void * ptr_id);                                     //将指针推入 ID 堆栈（将散列指针）。
void           PushID ( int int_id);                                             //将整数推入 ID 堆栈（将散列整数）。
void           PopID ();                                                        //从 ID 堆栈中弹出。
ImGuiID        GetID ( const  char * str_id);                                      //计算唯一 ID（整个 ID 堆栈的哈希值 + 给定参数）。例如，如果您想自己查询 ImGuiStorage
ImGuiID        GetID ( const  char * str_id_begin, const  char * str_id_end);
ImGuiID        GetID ( const  void * ptr_id);

Cpp Trick in ImGui

避免大函数，拆分成小函数

避免大函数，拆分成小函数，因为链接大函数的时间的复杂度是非线性的

ImGui的调用风格

返回bool，给if去触发逻辑
额外的返回值通过指针参数传出
pStatus承担了至多三种功能，输入和返回值，NULL时还是禁用
相对复杂的控件是带状态的，有控件ID，输入参数会被缓存在控件状态中

bool MenuItem(const char * label, const char *shortcut, bool *p_selected, bool enabled=true);

变长参数

TextXXX文本控件有两个版本，比如Text和TextV

两个都是vararg，一个是接口，一个是内部实现

…用va_start和va_end可以收集到一个va_list中

void ImGui::Text(const char* fmt, ...)
{va_list args;va_start(args, fmt);TextV(fmt, args);va_end(args);
}void ImGui::TextV(const char* fmt, va_list args)
{ImGuiWindow* window = GetCurrentWindow();if (window->SkipItems)return;ImGuiContext& g = *GImGui;const char* text_end = g.TempBuffer + ImFormatStringV(g.TempBuffer, IM_ARRAYSIZE(g.TempBuffer), fmt, args);TextEx(g.TempBuffer, text_end, ImGuiTextFlags_NoWidthForLargeClippedText);
}

常见问题

无法获取键盘输入

https://github.com/ocornut/imgui/issues/2608

io.AddInputCharacter()

Character和Key的概念和接口是分开的

字体要支持中文，否则只能用英文输入法

AddFontFromMemoryTTF的内存问题

Assertion failed: font_offset >= 0 && "FontData is incorrect, or FontNo cannot be found.",
file imgui_draw.cpp, line 2117

错误信息并没有什么

找到出错的接口，从内存加载ttf字体

IMGUI_API ImFont* AddFontFromMemoryTTF(void* font_data, int font_size, float size_pixels);

出错的原因在于这个接口的NOTE，大意是所有权移交ImFontAtlas，ttf的内存会被delete掉

NB: Transfer ownership of ‘ttf_data’ to ImFontAtlas, unless font_cfg_template->FontDataOwnedByAtlas == false.
Owned TTF buffer will be deleted after Build().

类似的加载资源的第三方库接口其实都要注意这点，比如stbimage加载纹理，imgui加载字体，要注意资源的内存是自己还是库来管理
否则要么是释放了两次，运行时报错，要么是内存泄漏

这里要拷贝一份资源内存交给imgui去使用

对应ZeloEngine的Resource有两个接口read和readCopy，这里使用后者