imgui中文文档(一)

2024-03-23 21:14:28

2020年12月11日10:21:48

官方：https://github.com/ocornut/imgui

Dear ImGui

官方网站

https://www.dearimgui.org/

_{(该库可免费获得许可，但需要财务支持以保持其持续改进。除了维护和稳定性之外，还有许多需要添加的功能。如果您的公司正在使用Dear ImGui，请考虑与您联系。)}

商业：通过发票支持持续的开发和维护
技术支持，维护，赞助合同：

E-mail: contact @ dearimgui dot com

个人：支持持续的开发和维护 here.

Also see Sponsors page.

Dear ImGui 是一个 用于C ++的无膨胀图形用户界面库. 它输出优化的顶点缓冲区，您可以随时在启用3D管线的应用程序中进行渲染。它快速，可移植，与渲染器无关并且是独立的（无外部依赖性）。

Dear ImGui 被设计成 启用快速迭代 并 赋权程序员 以创建 内容创建工具和可视化/调试工具 (与普通最终用户的UI相对). 它有利于实现该目标的简单性和生产率，并且缺少通常在更高级的库中发现的某些功能。

Dear ImGui 特别适合集成到游戏引擎（用于工具），实时3D应用程序，全屏应用程序，嵌入式应用程序或非标准操作系统功能的控制台平台上的任何应用程序中。

用法 - 怎么运行 - 发布 - 实例 - 整合
即将发生的改变 - Gallery - 支持, FAQ - 获取帮助 - 赞助 - Credits - License
Wiki - Languages & frameworks backends/bindings - Software using Dear ImGui - User quotes

用法

Dear ImGui 的核心是独立于几个与平台无关的文件 您可以轻松地在应用程序/引擎中进行编译。它们都是存储库根文件夹中的所有文件（imgui.cpp，imgui.h，imgui_demo.cpp，imgui_draw.cpp等）。

不需要特定的构建过程. 您可以将.cpp文件添加到现有项目中。

您将需要一个后端来将Dear ImGui集成到您的应用程序中。后端将鼠标/键盘/游戏板输入和各种设置传递给Dear ImGui，并负责渲染最终的顶点。

各种图形API和渲染平台的后端 提供在 backends/ 文件夹, 以及实例/ 文件夹. See the 整合有关详细信息您也可以创建自己的后端。可以渲染纹理三角形的任何地方，都可以渲染Dear ImGui。

在您的应用程序中设置Dear ImGui之后，您可以在程序循环中的\ _anywhere \ _中使用它：

Code:

ImGui::Text("Hello, world %d", 123);
if (ImGui::Button("Save"))
    MySaveFunction();
ImGui::InputText("string", buf, IM_ARRAYSIZE(buf));
ImGui::SliderFloat("float", &f, 0.0f, 1.0f);

渲染结果:

(settings: Dark style (left), Light style (right) / Font: Roboto-Medium, 16px)
渲染结果图片放在文档最后面了

Code:

// 创建一个带有菜单栏的名为“我的第一个工具”的窗口。
ImGui::Begin("My First Tool", &my_tool_active, ImGuiWindowFlags_MenuBar);
if (ImGui::BeginMenuBar())
{
    if (ImGui::BeginMenu("File"))
    {
        if (ImGui::MenuItem("Open..", "Ctrl+O")) { /* Do stuff */ }
        if (ImGui::MenuItem("Save", "Ctrl+S"))   { /* Do stuff */ }
        if (ImGui::MenuItem("Close", "Ctrl+W"))  { my_tool_active = false; }
        ImGui::EndMenu();
    }
    ImGui::EndMenuBar();
}

// 编辑颜色 (stored as ~4 floats)
ImGui::ColorEdit4("Color", my_color);

// Plot some values
const float my_values[] = { 0.2f, 0.1f, 1.0f, 0.5f, 0.9f, 2.2f };
ImGui::PlotLines("Frame Times", my_values, IM_ARRAYSIZE(my_values));

// 在滚动区域中显示内容
ImGui::TextColored(ImVec4(1,1,0,1), "Important Stuff");
ImGui::BeginChild("Scrolling");
for (int n = 0; n < 50; n++)
    ImGui::Text("%04d: Some text", n);
ImGui::EndChild();
ImGui::End();

渲染结果:

Dear ImGui 允许你 创建精致的工具 以及非常短暂的工具。从短期来看，极端的一面是：使用现代编译器的“编辑并继续”（热代码重载）功能，您可以在应用程序运行时添加一些小部件来调整变量，并在一分钟后删除代码！亲爱的ImGui不仅是在调整价值。您可以通过发出文本命令来使用它来跟踪正在运行的算法。您可以将其与自己的反射数据一起使用，实时浏览数据集。您可以使用它来公开引擎中子系统的内部，创建记录器，检查工具，分析器，调试器，整个游戏制作编辑器/框架等。

怎么运行

如果您想了解IMGUI范例背后的核心原理，请查看Wiki的关于IMGUI范例部分。从用户的角度来看，IMGUI试图最大程度地减少多余的状态重复，状态同步和状态保留。与传统的保留模式界面相比，它不那么容易出错（更少的代码和更少的错误），并且可以创建动态用户界面。

Dear ImGui 输出顶点缓冲区和命令列表，您可以在应用程序中轻松渲染它们。进行绘制所需的绘制调用和状态更改的数量非常少。由于Dear ImGui无法直接知道或触摸图形状态，因此您可以在代码中的任何位置（例如，正在运行的算法中间或在您自己的渲染过程中间）调用其功能。请参阅examples /文件夹中的示例应用程序，以获取有关如何将Dear ImGui与现有代码库集成的说明。

_一个常见的误解是将立即模式gui误认为是立即模式渲染，这通常意味着用一堆效率低下的画图调用和当gui函数被调用时的状态更改来重击驱动程序/ GPU。这不是亲爱的ImGui所做的。亲爱的ImGui输出顶点缓冲区和一小部分绘制调用批次。它永远不会直接触摸您的GPU。抽奖批处理非常理想，您可以稍后在应用程序中甚至远程渲染它们。

发布

查看 Releases.

实例

调用ImGui :: ShowDemoWindow()函数将创建一个演示窗口，其中展示了各种功能和示例。该代码始终可在imgui_demo.cpp中参考。

您应该能够从源代码构建示例（在Windows / Mac / Linux上经过测试）。如果您不这样做，请告诉我们！如果您想快速了解某些Dear ImGui功能，可以在此处下载该演示应用程序的Windows二进制文件：
-imgui-demo-binaries-20200918.zip（Windows，1.78 WIP，内置2020/09/18，主分支）或较旧的演示二进制文件。

演示应用程序不支持DPI，因此希望在4K屏幕上有些模糊。为了使您的应用程序了解DPI，可以按不同比例加载/重新加载字体，并使用 style.ScaleAllSizes() (see FAQ).

Integration

在大多数平台上和使用C ++时, 您应该可以使用imgui_impl_xxxx后端的组合而无需进行修改 (e.g. imgui_impl_win32.cpp + imgui_impl_dx11.cpp). 如果您的引擎支持多个平台，请考虑使用更多的imgui_impl_xxxx文件，而不是重写它们：对您来说这将减少工作量，您可以立即运行Dear ImGui。如果愿意，您可以_later_决定使用自定义引擎功能重写自定义后端。

将Dear ImGui集成到您的自定义引擎中只需1）连接鼠标/键盘/游戏手柄输入2）将一个纹理上载到GPU /渲染引擎3）提供可绑定纹理并渲染纹理三角形的渲染功能。 The examples/文件夹中填充了执行此操作的应用程序。如果您是一位熟练的程序员，熟悉这些概念，则将您花费不到两个小时的时间将Dear ImGui集成到您的自定义引擎中. Make sure to spend time reading the FAQ, comments, and some of the examples/ application!

官方维护的后端/绑定（在存储库中）：

渲染器：DirectX9，DirectX10，DirectX11，DirectX12，OpenGL（旧版），OpenGL3 / ES / ES2（现代），Vulkan，Metal。
平台：GLFW，SDL2，Win32，Glut，OSX。
框架：Emscripten，Allegro5，Marmalade。

第三方库 backends/bindings wiki page:

语言：C, C# and: Beef, ChaiScript, Crystal, D, Go, Haskell, Haxe/hxcpp, Java, JavaScript, Julia, Kotlin, Lua, Odin, Pascal, PureBasic, Python, Ruby, Rust, Swift ...
框架：AGS/Adventure Game Studio, Amethyst, bsf, Cinder, Cocos2d-x, Diligent Engine, Flexium, GML/Game Maker Studio2, Godot, GTK3+OpenGL3, Irrlicht Engine, LÖVE+LUA, Magnum, NanoRT, nCine, Nim Game Lib, Ogre, openFrameworks, OSG/OpenSceneGraph, Orx, Photoshop, px_render, Qt/QtDirect3D, SFML, Sokol, Unity, Unreal Engine 4, vtk, Win32 GDI, WxWidgets.。
请注意，C绑定（cimgui）是自动生成的，您可以使用其json / lua输出生成其他语言的绑定。

Useful widgets and extensions wiki page:

文本编辑器，节点编辑器，时间线编辑器，绘图，软件渲染器，远程网络访问，内存编辑器，小控件等。

另请参阅Wiki，以获取更多链接和想法。

即将发生的改变

Some of the goals for 2020 are:

Work on Tables (see #2957, now merged in master.
Work on Docking (see #2109, in public docking branch)
Work on Multi-Viewport / Multiple OS windows. (see #1542, in public docking branch looking for feedback)
Work on gamepad/keyboard controls. (see #787)
Work on automation and testing system, both to test the library and end-user apps. (see #435)
Make the examples look better, improve styles, improve font support, make the examples hi-DPI and multi-DPI aware.

2020年的一些目标是：

在表格上工作（请参阅＃2957，现在已合并为master。
在公共停靠上进行停靠工作（请参阅＃2109。科）
在多视口/多个OS窗口上工作。（请参阅＃1542，在公共docking
在游戏手柄/键盘控件上工作。（请参阅＃787）
开发自动化和测试系统，以测试库和最终用户应用程序。（请参阅＃435）
使示例看起来更好，改善样式，改善字体支持，使示例具有高DPI和多DPI意识。

Gallery

有关使用Dear ImGui的更多用户提交的项目的屏幕截图，请查看 Gallery Threads!

有关第三方窗口小部件和扩展的列表，请查看 Useful Widgets wiki 页面.

定制引擎

Tracy Profiler

支持，常见问题 (FAQ)

查看: Frequently Asked Questions (FAQ) 回答常见问题的地方.

查看: Wiki 有关许多链接，参考资料和文章。

查看: Articles about the IMGUI paradigm 阅读/学习即时模式GUI范例。

如果您不熟悉Dear ImGui，并且遇到以下问题：编译，链接，添加字体，接线输入，运行或显示Dear ImGui：您可以使用 Discord server.

否则，对于任何其他问题，错误报告，请求，反馈，您可以发布在https://github.com/ocornut/imgui/issues上。请仔细阅读并填写新发行模板。

私人支持可用于付费业务客户 (E-mail: contact @ dearimgui dot com).

我应该获得哪个版本？

我们有时会标记Releases，但通常它是安全的，建议同步到master / latest。该库相当稳定，当报告时，回归趋于快速修复.

高级用户可能希望将docking分支与Multi-Viewport和Docking一起使用 / issues / 2109）功能。该分支定期与主节点保持同步。
谁在用 Dear ImGui?

See the Quotes, Sponsors, Software using dear imgui Wiki页面，了解谁在使用Dear ImGui。如果可以，请添加您的游戏/软件！另请参阅 Gallery Threads!

如何获取帮助

How can I help?

您可以参加 Discord server, GitHub forum/issues.
您可以帮助开发并提交请求请求！请理解，提交PR也是在向维护人员提交请求，要求其检查您的代码，然后永久接管其维护工作。公关的制定既要符合最终用户的利益，也要使维护者易于理解和接受。
See Help wanted on the Wiki for some more ideas.
让贵公司在财务上支持该项目（请通过电子邮件联系）

码农公寓