基本集成

相关源文件

• examples/example_glfw_opengl2/main.cpp
• examples/example_glfw_opengl3/main.cpp

本文档提供了将 Dear ImGui 集成到您的应用程序中的分步指南。它涵盖了适用于所有支持的平台和渲染 API 的基本集成模式。有关平台特定的集成细节，请参阅桌面集成或移动和 Web 集成。

集成概述

Dear ImGui 需要与两个后端系统集成

1. 一个平台后端，用于处理窗口创建、输入事件和计时
2. 一个渲染器后端，用于通过图形 API 处理绘图命令

基本集成流程包括四个主要阶段

来源：examples/example_glfw_opengl3/main.cpp80-208

1. 初始化 Dear ImGui 上下文

第一步是创建并初始化 Dear ImGui 上下文，它管理所有 ImGui 状态。

关键步骤

• 调用 IMGUI_CHECKVERSION() 以验证版本一致性（可选但建议）
• 使用 ImGui::CreateContext() 创建 ImGui 上下文
• 使用 ImGui::GetIO() 获取 IO 结构体引用
• 通过诸如 ImGuiConfigFlags_NavEnableKeyboard 等标志配置 IO 选项
• 使用 ImGui::StyleColorsDark() 或其他选项设置视觉外观

来源：examples/example_glfw_opengl3/main.cpp80-89 examples/example_glfw_opengl2/main.cpp49-58

2. 设置平台和渲染器后端

Dear ImGui 需要平台（窗口/输入）和渲染器（图形 API）接口的后端实现。

常见的平台后端包括

• GLFW (imgui_impl_glfw.h/cpp)
• SDL2/SDL3 (imgui_impl_sdl2.h/cpp / imgui_impl_sdl3.h/cpp)
• Win32 (imgui_impl_win32.h/cpp)

常见的渲染器后端包括

• OpenGL 3 (imgui_impl_opengl3.h/cpp)
• OpenGL 2 (imgui_impl_opengl2.h/cpp)
• DirectX 9/10/11/12
• Vulkan, Metal, WebGPU

GLFW + OpenGL 3 示例

• 初始化 GLFW 并创建窗口
• 使用 ImGui_ImplGlfw_InitForOpenGL(window, true) 初始化 GLFW 平台后端
• 使用 ImGui_ImplOpenGL3_Init(glsl_version) 初始化 OpenGL 3 渲染器后端

来源：examples/example_glfw_opengl3/main.cpp40-96 examples/example_glfw_opengl2/main.cpp38-62

3. 主循环

ImGui 集成的核心是每帧主循环，它负责

1. 处理输入事件
2. 开始一个新的 ImGui 帧
3. 定义 UI 元素
4. 渲染 ImGui 内容

每帧的关键步骤

1. 处理平台事件（例如，glfwPollEvents()）
2. 开始一个新的 ImGui 帧
   • 调用渲染器后端的 NewFrame() 函数
   • 调用平台后端的 NewFrame() 函数
   • 调用 ImGui::NewFrame()
3. 定义您的用户界面（窗口、控件等）
4. 渲染 ImGui 帧
   • 调用 ImGui::Render() 以完成帧渲染
   • 使用 ImGui::GetDrawData() 调用渲染器后端的 RenderDrawData() 函数
5. 呈现帧（例如，glfwSwapBuffers()）

来源：examples/example_glfw_opengl3/main.cpp120-194 examples/example_glfw_opengl2/main.cpp85-160

4. 关闭和清理

适当的清理可确保在应用程序退出时释放资源

关闭顺序

1. 使用 ImGui_ImplRenderer_Shutdown() 清理渲染器后端资源
2. 使用 ImGui_ImplPlatform_Shutdown() 清理平台后端资源
3. 使用 ImGui::DestroyContext() 销毁 ImGui 上下文
4. 清理任何剩余的平台特定资源

来源：examples/example_glfw_opengl3/main.cpp199-207 examples/example_glfw_opengl2/main.cpp162-170

基本 UI 实现

集成设置完成后，您可以在 ImGui::NewFrame() 和 ImGui::Render() 之间定义窗口和小部件来创建您的 UI。

UI 工作流程示例

1. 使用 ImGui::Begin("Window Title") 启动一个窗口
2. 添加控件，例如：
   • 用于文本显示的 ImGui::Text()
   • 用于可点击按钮的 ImGui::Button()
   • 用于布尔切换的 ImGui::Checkbox()
   • 用于可调节值的 ImGui::SliderFloat(), ImGui::ColorEdit3()
3. 使用 ImGui::End() 关闭窗口定义

来源：examples/example_glfw_opengl3/main.cpp147-182 examples/example_glfw_opengl2/main.cpp105-140

输入处理

Dear ImGui 可以处理其 UI 的输入事件，同时允许您的应用程序处理其他用途的输入

• 当鼠标事件应由 ImGui 捕获时，ImGui 会设置 io.WantCaptureMouse
• 当键盘事件应由 ImGui 捕获时，ImGui 会设置 io.WantCaptureKeyboard
• 您的应用程序可以检查这些标志以确定何时自行处理输入

来源：examples/example_glfw_opengl3/main.cpp130-135 examples/example_glfw_opengl2/main.cpp88-93

完整集成示例

一个完整的基本集成通常遵循以下结构

上图展示了 Dear ImGui 从初始化到关闭的完整集成流程。

来源：examples/example_glfw_opengl3/main.cpp38-208 examples/example_glfw_opengl2/main.cpp36-171

额外集成注意事项

集成 Dear ImGui 时，请记住以下几点

• 字体加载：在上下文创建后但在第一帧渲染前加载自定义字体
• 配置标志：根据您的需要设置配置标志，例如 ImGuiConfigFlags_NavEnableKeyboard
• DPI 感知：通过设置适当的缩放来处理高 DPI 显示器
• 多视口：启用 ImGuiConfigFlags_ViewportsEnable 以支持多窗口（需要额外设置）
• 键盘导航：启用 ImGuiConfigFlags_NavEnableKeyboard 以实现完整的键盘控制
• 游戏手柄导航：启用 ImGuiConfigFlags_NavEnableGamepad 以支持游戏手柄

来源：examples/example_glfw_opengl3/main.cpp83-85 examples/example_glfw_opengl3/main.cpp98-113