在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

ocornut/imgui

菜单

概述

相关源文件

Dear ImGui 是一个无臃肿的 C++ 图形用户界面库，它采用了即时模式范式。它主要用于创建快速、可移植且易于使用的工具、调试、可视化和内容创作界面，而不是最终用户应用程序。本文档将介绍 Dear ImGui 的核心架构、集成流程和关键概念。

有关具体的集成说明，请参阅 集成指南，有关后端特定的详细信息，请参阅 后端系统。

核心理念

Dear ImGui 遵循一系列设计原则，使其区别于传统的保留模式 UI 库。

  1. 即时模式范式：UI 每帧都会重新创建，提供更简单的思维模型和更大的灵活性。
  2. 最小化状态存储：减少应用程序和 UI 库之间的状态重复，从而最大限度地减少同步问题。
  3. 低依赖性：自包含，外部依赖最少，使其在各种平台上高度可移植。
  4. 简单的集成：通常只需 25-100 行代码即可集成到现有应用程序中。
  5. 性能优先：尽管每帧都重新创建 UI，但 Dear ImGui 针对性能进行了优化。

来源： imgui.cpp1-126 docs/README.md20-39

系统架构

Dear ImGui 在核心功能和后端实现之间进行了清晰的分离。核心库处理 UI 元素的逻辑表示、布局和交互，而后端则负责平台特定的操作和图形渲染。

来源： imgui.h147-307 imgui_internal.h134-185

关键组件

ImGuiContext

包含所有 Dear ImGui 状态的中央结构。每个应用程序通常创建一个 ImGuiContext，但为了高级用例也支持多个上下文。

ImGuiIO & ImGuiPlatformIO

  • ImGuiIO：用于输入/输出操作的接口，处理鼠标/键盘/游戏手柄输入、增量时间、显示尺寸和配置标志。
  • ImGuiPlatformIO：用于多视口和其他平台操作的平台特定接口。

控件系统

提供各种 UI 元素，如按钮、滑块、文本输入，以及表格和树等更复杂的组件。

窗口管理

处理窗口创建、焦点、堆叠、折叠和滚动。

绘图系统

将 UI 命令转换为渲染图元（顶点缓冲区和绘图命令），这些图元可以通过渲染器后端由任何图形 API 渲染。

字体系统

管理字体的加载、光栅化和渲染，支持 TTF/OTF 文件和 Unicode。

来源： imgui.h180-201 imgui_internal.h178-182

集成流程

将 Dear ImGui 集成到应用程序中遵循一个可预测的流程。

典型的集成需要：

  1. 初始化:

    • 创建 ImGui 上下文
    • 配置 IO 设置
    • 初始化平台和渲染器后端
    • 设置字体

  2. 每帧:

    • 通过平台后端提供输入状态
    • 调用 NewFrame() 开始新的一帧
    • 定义 UI 元素
    • 调用 Render() 完成帧并生成绘图命令
    • 通过渲染器后端渲染绘图命令

  3. 关机:

    • 清理后端
    • 销毁 ImGui 上下文

来源： imgui.cpp274-367

平台和渲染器后端

Dear ImGui 需要平台特定和渲染器特定的后端来处理输入和渲染。该库为常见的平台和图形 API 包含许多预制后端。

平台后端

处理窗口创建、输入事件（鼠标、键盘、游戏手柄）、剪贴板操作、计时和操作系统特定功能。

常见的平台后端

  • Win32
  • GLFW
  • SDL2/SDL3
  • OSX/iOS
  • Android

渲染器后端

将 Dear ImGui 的绘图命令转换为 API 特定的渲染命令。

常见的渲染器后端

  • DirectX 9/10/11/12
  • OpenGL 2/3
  • Vulkan
  • Metal
  • WebGPU

来源： imgui.cpp274-367 examples/README.txt1-10

核心数据结构

Dear ImGui 中最重要的数据结构包括：

结构描述
ImGuiContext包含所有 ImGui 状态的主上下文
ImGuiIO输入/输出配置和状态
ImGuiPlatformIO平台特定函数和状态
ImGuiWindow单个窗口状态和数据
ImDrawList渲染命令集合
ImDrawData传递给渲染器的最终渲染数据
ImGuiStyle颜色、大小和视觉设置
ImFontAtlas字体纹理和字形数据

来源： imgui.h162-201 imgui_internal.h145-184

基本使用示例

使用 Dear ImGui 创建简单的 UI 非常直接。

来源： imgui.cpp274-367 docs/README.md40-92

主要功能

Dear ImGui 提供了许多用于构建工具和 UI 元素的功能。

  1. 窗口管理：创建、调整大小、移动、折叠窗口
  2. 控件：按钮、滑块、复选框、下拉菜单等。
  3. 布局系统：自动布局、列、子窗口
  4. 输入：文本字段、键盘/鼠标/游戏手柄导航
  5. 表格：可排序、可调整大小的多列表格
  6. 绘图：简单的线形图和直方图
  7. 停靠：创建可停靠、可调整大小的面板（在 docking 分支中）
  8. 多视口：处理多个 OS 窗口（在 docking 分支中）
  9. 字体支持：加载自定义字体、Unicode 支持
  10. 样式系统：自定义颜色和大小

来源： imgui_demo.cpp1-123 imgui_widgets.cpp1-34

ID 系统和状态管理

Dear ImGui 使用基于堆栈的 ID 系统来唯一标识 UI 元素。理解此系统对于正确管理 UI 状态和交互至关重要。

  • 每个控件都会将 ID 推入/弹出堆栈
  • ID 可以来自字符串、整数值或指针地址
  • 具有相同 ID 的控件会相互干扰
  • 控件在帧之间存储的状态极少（主要是活动/焦点状态）

创建唯一 ID 的常用方法

  1. 使用字符串标签： Button("Label")
  2. 使用字符串 ID： PushID("ID"); Button("Same Label"); PopID();
  3. 使用指针作为 ID： PushID(ptr); Button("Button"); PopID();
  4. 使用整数作为 ID： PushID(42); Button("Button"); PopID();

来源： imgui.cpp90-100 docs/FAQ.md26-27

结论

Dear ImGui 提供了一个快速、轻量且易于集成的解决方案，用于创建图形界面，特别适合开发者工具、调试、可视化和内容创作。与传统的保留模式 GUI 库相比，其即时模式范式提供了一种不同的方法，优先考虑简洁性、性能和直接的代码到 UI 映射。

有关更详细的信息，请浏览此 wiki 的其他部分、官方文档以及 imgui_demo.cpp 中详尽的演示代码。

来源： imgui.cpp107-126 docs/README.md20-39