集成指南

相关源文件

• docs/FAQ.md
• docs/FONTS.md
• docs/README.md
• examples/README.txt
• examples/example_glfw_opengl2/main.cpp
• examples/example_glfw_opengl3/main.cpp
• examples/example_glfw_vulkan/main.cpp

本指南提供了将 Dear ImGui 集成到您的应用程序或游戏引擎的全面说明。它涵盖了核心集成过程、平台和渲染器选择，以及在您的代码库中运行 Dear ImGui 所需的基本设置步骤。

有关特定控件系统的信息，请参阅 控件系统，有关后端特定的实现细节，请参阅 后端系统。

1. 集成概述

Dear ImGui 的设计采用了模块化架构，将核心用户界面库与平台特定的代码和渲染后端实现分离开来。这种设计允许将其集成到各种平台和渲染 API 中。

集成过程遵循以下基本步骤：

图示：Dear ImGui 集成流程

来源： docs/README.md117-123 examples/example_glfw_vulkan/main.cpp352-534

2. 基本集成步骤

2.1 设置 ImGui 上下文

第一步是初始化 Dear ImGui 上下文并配置基本设置。

您的整个应用程序只需要一个 ImGui 上下文。该上下文包含所有状态，包括窗口、控件、输入和样式信息。

来源： examples/example_glfw_opengl3/main.cpp80-89 examples/example_glfw_vulkan/main.cpp385-394

2.2 选择和设置后端

Dear ImGui 需要两种类型的后端：

1. 平台后端：处理窗口创建、输入事件和计时。
2. 渲染器后端：处理将 ImGui 绘制命令渲染到您的图形 API。

图示：Dear ImGui 后端系统架构

来源： docs/README.md122-123 examples/README.txt3-4

平台后端初始化

根据您的应用程序的窗口系统选择平台后端。

来源： examples/example_glfw_opengl3/main.cpp92-96 examples/example_glfw_vulkan/main.cpp397

渲染器后端初始化

根据您的图形 API 选择渲染器后端。

来源： examples/example_glfw_opengl3/main.cpp96 examples/example_glfw_vulkan/main.cpp398-414

2.3 主应用程序循环

集成到应用程序的主循环涉及几个关键步骤：

图示：Dear ImGui 逐帧集成流程

来源： examples/example_glfw_opengl3/main.cpp126-193 examples/example_glfw_vulkan/main.cpp437-517

开始新帧

来源： examples/example_glfw_vulkan/main.cpp445-466 examples/example_glfw_opengl3/main.cpp143-145

创建用户界面

来源： examples/example_glfw_vulkan/main.cpp477-492 examples/example_glfw_opengl3/main.cpp156-171

渲染 ImGui

来源： examples/example_glfw_vulkan/main.cpp505-516 examples/example_glfw_opengl3/main.cpp185-191

2.4 清理与关闭

应用程序关闭时，您需要正确关闭 Dear ImGui。

来源： examples/example_glfw_vulkan/main.cpp522-525 examples/example_glfw_opengl3/main.cpp200-202

3. 特定平台集成

Dear ImGui 通过其后端系统支持各种平台。以下是可用的平台后端概述：

图示：Dear ImGui 平台后端选项

来源： docs/README.md125-128

3.1 桌面集成（Windows、macOS、Linux）

对于桌面平台，最常用的后端是：

平台后端	描述	最佳搭配
GLFW	跨平台窗口和输入 API	OpenGL, Vulkan, DirectX, Metal
SDL2/SDL3	跨平台多媒体库	OpenGL, Vulkan, DirectX, Metal
Win32	Windows 特有 API	DirectX (9, 10, 11, 12)
OSX	macOS 特有 API	Metal

基础 GLFW 集成示例

来源： examples/example_glfw_opengl3/main.cpp38-96

3.2 移动和 Web 集成

对于移动平台：

平台	后端	备注
Android	imgui_impl_android	需要 NDK 和额外的输入处理
iOS	imgui_impl_osx	可能需要针对触摸输入进行平台特定适配

对于 Web 平台：

• Emscripten 通过 GLFW 或 SDL 后端以及特定的初始化得到支持。
• WebGPU 渲染器后端可用于现代 Web 图形。

来源： examples/example_glfw_opengl3/main.cpp92-96

4. 特定渲染器集成

Dear ImGui 为各种图形 API 提供了多种渲染器后端。

图示：Dear ImGui 渲染器后端选项

来源： docs/README.md126

4.1 OpenGL 集成

OpenGL 有两个后端实现：

• imgui_impl_opengl2：用于旧版 OpenGL（固定功能管线）。
• imgui_impl_opengl3：用于现代 OpenGL 3+（可编程管线）、OpenGL ES 和 WebGL。

来源： examples/example_glfw_opengl3/main.cpp44-96

4.2 DirectX 集成

DirectX 后端需要适当的设备和上下文初始化。

4.3 Vulkan 集成

由于 Vulkan 的显式性质，其设置过程更为复杂。

来源： examples/example_glfw_vulkan/main.cpp191-208 examples/example_glfw_vulkan/main.cpp398-414

5. 高级集成主题

5.1 输入处理

Dear ImGui 需要接收输入事件才能正常运行。在大多数情况下，平台后端会自动处理此问题，但您需要了解如何在 ImGui 和您的应用程序之间管理输入分发。

来源： docs/FAQ.md106-126

5.2 字体加载和自定义

您可以加载自定义字体来替换默认字体

对于非拉丁字符支持，请加载适当的字形范围

来源： docs/FONTS.md79-162

5.3 DPI 处理

为了正确的 DPI 缩放

来源： docs/FAQ.md540-551

5.4 多视口支持

对于支持独立窗口的应用程序（停靠分支）

6. 常见问题与解决方案

6.1 渲染问题

问题	潜在解决方案
文本丢失/方块代替文本	字体图集未正确加载。请检查字体初始化和纹理上传。
裁剪问题	确保在您的渲染函数中正确处理裁剪矩形。
Z轴顺序/深度问题	请确保您的渲染管线遵守 Dear ImGui 的深度设置。

来源： docs/FAQ.md162-192

6.2 输入问题

问题	潜在解决方案
UI 对输入没有反应	检查您是否正确地将输入事件转发给了平台后端。
错误的控件接收输入	很可能是 ID 堆栈冲突。对具有相同标签的控件使用唯一的 ID。
输入在应用程序中工作，但在 ImGui 中无效	确保 io.WantCaptureMouse/io.WantCaptureKeyboard 已正确遵循。

来源： docs/FAQ.md200-346

6.3 性能考量

• 在性能关键部分最小化控件创建
• 在频繁调用的 ImGui 代码中，请小心处理繁重的操作
• 对于大型 UI 元素，使用子窗口或裁剪
• 考虑控件的可见性，并有条件地创建昂贵的 UI 元素

7. 结论

将 Dear ImGui 集成到您的应用程序中，需要选择合适的平台和渲染器后端，正确地初始化它们，并实现每帧的循环。虽然初步集成需要理解其架构，但其模块化设计使其能够适应各种应用程序和平台。

有关更详细的信息，请参阅 examples/ 文件夹中的示例代码，其中展示了与各种平台和渲染器组合的集成。

来源： docs/README.md116-123 examples/README.txt1-10