Dear ImGui — Administrator & Developer Guide

Dear ImGui is an immediate-mode graphical user interface library for C++. It outputs optimized vertex buffers that you render in your application using whatever graphics API you prefer. There are no widget objects to manage, no state to synchronize, and no callback registration. You call functions, Dear ImGui accumulates draw commands, and you render the result. This guide covers everything an administrator, integrator, or developer needs to deploy, configure, optimize, and extend Dear ImGui in production applications.

Table of Contents

1. Architecture Overview
2. System Requirements
3. Configuration Reference
4. Deployment & Scaling
5. Operations
6. Performance
7. Security
8. Developer Internals
9. Integration Points
10. Troubleshooting
11. Reference

1. Architecture Overview

The Immediate-Mode Paradigm

Dear ImGui follows the immediate-mode GUI (IMGUI) paradigm. Unlike retained-mode toolkits (Qt, GTK, WPF) where you create persistent widget objects, wire up event handlers, and synchronize state between your application data and the UI, Dear ImGui asks you to emit your UI every frame using plain function calls. There is no widget tree to manage, no observer pattern, no data binding. If a checkbox should be visible, you call ImGui::Checkbox(). If a window should exist, you call ImGui::Begin(). The library handles all layout, input processing, and rendering internally — your code simply describes what the UI should look like right now.

This paradigm eliminates an entire class of bugs related to state synchronization. The UI always reflects the current state of your application because it is rebuilt from that state every frame. The cost is that you must call the UI code every frame, but for the kinds of applications Dear ImGui targets (game engines, tools, debug overlays, prototypes), this is already happening.

Data Flow

┌─────────────┐
│  Your App   │
└──────┬──────┘
       │  1. Feed inputs (mouse, keyboard, gamepad, display size)
       ▼
┌──────────────┐
│  ImGuiIO     │──── Platform Backend populates this
└──────┬───────┘
       │  2. ImGui::NewFrame()
       ▼
┌──────────────────────────────────────────────┐
│  Widget Calls                                │
│  ImGui::Begin("Window")                      │
│  ImGui::Text("Hello")                        │
│  if (ImGui::Button("Click")) { DoStuff(); }  │
│  ImGui::End()                                │
└──────────────────┬───────────────────────────┘
                   │  3. ImGui::Render()
                   ▼
            ┌─────────────┐
            │ ImDrawData   │─── Collection of ImDrawLists
            └──────┬──────┘
                   │  4. Your renderer iterates draw commands
                   ▼
            ┌──────────────┐
            │ GPU Draw     │─── Renderer Backend handles this
            │ Calls        │
            └──────────────┘

Each frame follows this cycle:

1. Input: The platform backend (or your code) writes mouse position, button states, keyboard events, display size, and delta time into ImGuiIO.
2. NewFrame: ImGui::NewFrame() processes inputs, updates internal state, and prepares for the new frame.
3. Widget calls: Your application calls ImGui::Begin(), ImGui::Text(), ImGui::Button(), ImGui::SliderFloat(), etc. Each call may read from or write to your application variables (e.g., a slider modifies a float*). Internally, Dear ImGui accumulates geometry (vertices, indices) and draw commands into ImDrawList objects.
4. Render: ImGui::Render() finalizes the frame and produces ImDrawData — a collection of ImDrawList objects with all the vertex/index buffers and draw commands. Your renderer backend iterates this data and issues the corresponding GPU draw calls.

Component Inventory

Backend Architecture

Dear ImGui separates platform concerns from rendering concerns through a two-backend system:

Platform Backend — Handles the operating system and windowing layer:

• Window size and DPI reporting
• Mouse, keyboard, and gamepad input
• Clipboard access
• IME (Input Method Editor) support
• Mouse cursor shape changes
• File/URL opening via shell

Renderer Backend — Handles GPU interaction:

• Texture creation, updating, and destruction
• Rendering ImDrawData (vertex/index buffers, draw commands, clip rectangles)
• Optional: large mesh support via VtxOffset
• Optional: sampler state management for texture filtering

You combine one platform backend with one renderer backend. For example: GLFW + OpenGL3, SDL3 + Vulkan, Win32 + DirectX11. Some backends (Allegro5) combine both roles.

Technology Stack

• Language: C++ with C++11 as the minimum standard
• External dependencies: None for the core library
• Embedded libraries: stb_truetype, stb_textedit, stb_rect_pack (public domain)
• Optional dependencies: FreeType (font rasterization), plutosvg/lunasvg (SVG font support)
• Build system: None required — add .cpp files to your project

Key Design Principles

1. No hidden state: All widget state is either in your variables (passed as pointers to widget functions) or in Dear ImGui's internal state (keyed by widget ID). There are no hidden observer patterns, no event queues the user must poll, and no deferred updates.

2. Predictable lifetime: CreateContext() allocates, DestroyContext() frees. No garbage collection, no ref-counting, no weak pointers. Memory ownership is explicit.

3. Minimal abstraction: Dear ImGui does not abstract the rendering API, the windowing system, or the operating system. It outputs vertex buffers. You render them however you want. This is why Dear ImGui works on every platform that can draw textured triangles.

4. Backward compatibility: The public API (imgui.h) is treated as stable. Breaking changes are rare and always accompanied by compatibility shims (IMGUI_DISABLE_OBSOLETE_FUNCTIONS removes them). Internal API (imgui_internal.h) has no stability guarantees.

5. Self-contained: The entire library is ~6 files with zero mandatory external dependencies. Vendored stb headers are included. This makes Dear ImGui trivially embeddable in any project.

2. System Requirements

Hardware & Software Requirements

Build Requirements

Dear ImGui requires no special build system. Integration consists of adding source files to your existing build:

Minimum files to compile:

imgui.cpp
imgui_draw.cpp
imgui_tables.cpp
imgui_widgets.cpp
imgui_demo.cpp          (optional, but recommended during development)
backends/imgui_impl_*   (your chosen platform + renderer backends)

No CMakeLists.txt, no configure script, no package manager entry. Just add the .cpp files to your project's compilation and ensure the header directory is in your include path.

Optional Dependencies

3. Configuration Reference

Dear ImGui supports two layers of configuration: compile-time options set via #define macros (typically in imconfig.h), and runtime options set via the ImGuiIO struct and ImGuiStyle struct.

3.1 Compile-Time Options (imconfig.h)

All compile-time options are set by defining macros before imgui.h is included. The recommended approach is to edit imconfig.h (which is included by imgui.h). Alternatively, you can define macros in your build system's preprocessor definitions.

Important

Every compilation unit that includes imgui.h must see the same imconfig.h defines. Mismatched defines across translation units cause subtle memory corruption and crashes. Use IMGUI_CHECKVERSION() in your main file to detect version/configuration mismatches at runtime.

Assert & Debug

API Visibility & DLL

Feature Disabling

Platform-Specific Disabling

Standard Library Overrides

STB Library Overrides

Font & Rendering

Type Overrides

Extension Points

3.2 ImGuiIO Runtime Configuration

The ImGuiIO struct is accessed via ImGui::GetIO() and contains all runtime configuration, input data, and output status. Set configuration fields after CreateContext() and before the first NewFrame().

Configuration Flags

ImGuiIO& io = ImGui::GetIO();
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;  // Enable keyboard nav
io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;    // Enable gamepad nav

Font Configuration

Input Behavior

Window Behavior

Debug Configuration

Output Status (Read-Only)

3.3 ImGuiStyle Reference

The ImGuiStyle struct controls the visual appearance of all Dear ImGui elements. Access via ImGui::GetStyle(). All distances are in pixels. Colors are stored as ImVec4 (RGBA float, 0.0–1.0).

Tip

Call ImGui::ShowStyleEditor() to interactively tweak every style variable in real time. You can copy the resulting values as code. This is the fastest way to customize the look of your UI.

Size & Spacing

Font Sizing (1.92+)

Tree Lines (1.92+)

Rendering Quality

Mouse Cursor

Hover & Tooltip Timing

Colors

The Colors[] array (indexed by ImGuiCol_ enum values) controls all widget colors. There are 58 color entries. See the ImGuiCol_ enum in section 3.4 for the complete list. Use ImGui::PushStyleColor() / PopStyleColor() for per-widget overrides, or modify style.Colors[] directly for global changes.

3.4 All Flag Enumerations

ImGuiConfigFlags_

ImGuiBackendFlags_

ImGuiWindowFlags_

ImGuiChildFlags_

ImGuiInputTextFlags_

ImGuiTreeNodeFlags_

ImGuiPopupFlags_

ImGuiSelectableFlags_

ImGuiComboFlags_

ImGuiTabBarFlags_

ImGuiTabItemFlags_

ImGuiTableFlags_

ImGuiTableColumnFlags_

ImGuiTableRowFlags_

ImGuiTableBgTarget_

ImGuiItemFlags_

ImGuiFocusedFlags_

ImGuiHoveredFlags_

ImGuiDragDropFlags_

ImGuiColorEditFlags_

ImGuiSliderFlags_

ImGuiMultiSelectFlags_

ImGuiButtonFlags_ (Public Subset)

ImDrawFlags_

ImDrawListFlags_

ImFontAtlasFlags_

ImGuiCol_ (Color Identifiers)

ImGuiStyleVar_ (Style Variables for PushStyleVar)

ImGuiDir

ImGuiMouseButton_

ImGuiMouseCursor_

ImGuiMouseSource

ImGuiCond_

ImGuiDataType_

ImGuiSortDirection

ImGuiKey (Selected Navigation/Interaction Keys)

The ImGuiKey enum contains entries for every keyboard key, gamepad input, and mouse button. Keys include:

• Keyboard: ImGuiKey_Tab, ImGuiKey_LeftArrow, ImGuiKey_RightArrow, ImGuiKey_UpArrow, ImGuiKey_DownArrow, ImGuiKey_PageUp, ImGuiKey_PageDown, ImGuiKey_Home, ImGuiKey_End, ImGuiKey_Insert, ImGuiKey_Delete, ImGuiKey_Backspace, ImGuiKey_Space, ImGuiKey_Enter, ImGuiKey_Escape, ImGuiKey_A through ImGuiKey_Z, ImGuiKey_0 through ImGuiKey_9, ImGuiKey_F1 through ImGuiKey_F24, function keys, modifier keys (LeftCtrl, LeftShift, LeftAlt, LeftSuper, and right-side variants).
• Gamepad: ImGuiKey_GamepadStart, ImGuiKey_GamepadBack, ImGuiKey_GamepadFaceLeft/Right/Up/Down, ImGuiKey_GamepadDpadLeft/Right/Up/Down, ImGuiKey_GamepadL1/R1/L2/R2/L3/R3, ImGuiKey_GamepadLStickLeft/Right/Up/Down, ImGuiKey_GamepadRStickLeft/Right/Up/Down.
• Mouse: ImGuiKey_MouseLeft, ImGuiKey_MouseRight, ImGuiKey_MouseMiddle, ImGuiKey_MouseX1, ImGuiKey_MouseX2, ImGuiKey_MouseWheelX, ImGuiKey_MouseWheelY.
• Modifiers: ImGuiMod_Ctrl, ImGuiMod_Shift, ImGuiMod_Alt, ImGuiMod_Super, ImGuiMod_Mask_ (all modifiers).

4. Deployment & Scaling

Building Dear ImGui

Dear ImGui does not ship a build system. Integration is manual and deliberate:

1. Copy the core source files into your project (or add as a submodule/subtree).
2. Add the following to your compilation:
   • imgui.cpp
   • imgui_draw.cpp
   • imgui_tables.cpp
   • imgui_widgets.cpp
   • imgui_demo.cpp (optional, recommended for development)
   • Your chosen backend files (e.g., backends/imgui_impl_glfw.cpp + backends/imgui_impl_opengl3.cpp)
3. Ensure the root directory and backends/ directory are in your include path.
4. Build and link. No special flags required beyond C++11.

Platform-Specific Notes

Windows (Visual Studio)

Pre-built Visual Studio solution files are provided in examples/ for several backend combinations:

• example_win32_directx9/
• example_win32_directx10/
• example_win32_directx11/
• example_win32_directx12/
• example_win32_opengl3/
• example_glfw_opengl3/
• example_glfw_vulkan/
• example_sdl2_opengl3/
• example_sdl2_vulkan/
• example_sdl3_opengl3/
• example_sdl3_vulkan/
• example_sdl3_sdlgpu3/
• example_sdl3_sdlrenderer3/

MinGW is supported via the GNUmakefile in each example directory. For DLL builds, define IMGUI_API appropriately in imconfig.h.

Linux

Each example directory contains a Makefile for GCC/Clang. Install backend dependencies via your package manager:

# For GLFW + OpenGL3 example (Debian/Ubuntu)
apt-get install libglfw3-dev libgl1-mesa-dev

# For SDL2 + OpenGL3 example
apt-get install libsdl2-dev libgl1-mesa-dev

# For SDL3 examples (build SDL3 from source)

macOS

Xcode projects are provided for:

• example_apple_metal/ — Metal renderer with AppKit/UIKit
• example_apple_opengl2/ — Legacy OpenGL with GLUT
• example_glfw_metal/ — GLFW platform + Metal renderer

GLFW and SDL can be installed via Homebrew (brew install glfw, brew install sdl2).

Android

The example_android_opengl3/ directory contains a complete Android Studio project with Gradle and CMake integration. It uses the Android NDK's native activity and OpenGL ES 3.

Emscripten / WebAssembly

Several examples include Makefile.emscripten for building with Emscripten:

• example_emscripten_wgpu/ — WebGPU renderer (recommended for web)
• example_glfw_opengl3/ — OpenGL3 via Emscripten's GLFW port
• example_sdl2_opengl3/ — OpenGL3 via Emscripten's SDL2 port

iOS

The example_apple_metal/ example supports both macOS and iOS targets via a shared Xcode project.

Single-File Build

For projects that prefer a single compilation unit, misc/single_file/imgui_single_file.h includes all core .cpp files:

// In exactly ONE .cpp file:
#include "imgui_single_file.h"

This compiles all of Dear ImGui in a single translation unit, which can improve compile times and enable better inlining.

DLL / Shared Library

Warning

Using Dear ImGui as a shared library (DLL) is possible but introduces complexity at every DLL boundary. Each DLL that calls Dear ImGui functions must share the same ImGuiContext and memory allocators. This is NOT the default behavior on most platforms. Mishandling this causes crashes, memory corruption, and hard-to-diagnose bugs. If possible, statically link Dear ImGui into your application instead.

If you must use Dear ImGui across DLL boundaries:

1. Define IMGUI_API as __declspec(dllexport) when building the DLL and __declspec(dllimport) when consuming it.
2. In every DLL that uses Dear ImGui, call ImGui::SetCurrentContext() with the context from the host application.
3. Call ImGui::SetAllocatorFunctions() with the same allocator functions in each DLL, before any other Dear ImGui call.
4. Alternatively, compile Dear ImGui into each DLL and share context manually.

Console Platforms

Dear ImGui is designed to work on consoles (PlayStation, Xbox, Nintendo Switch). The rendering model (textured triangles with clip rectangles) maps directly to console graphics APIs. Console backends are typically proprietary and maintained by the console developer community. The core library has no platform-specific requirements that prevent console deployment.

Integration Checklist

The following checklist covers the minimum steps to integrate Dear ImGui into an existing application:

[ ] Copy imgui source files into your project tree
[ ] Add imgui.cpp, imgui_draw.cpp, imgui_tables.cpp, imgui_widgets.cpp to your build
[ ] Add imgui_demo.cpp to your build (recommended for development)
[ ] Choose and add a platform backend (e.g., imgui_impl_glfw.cpp)
[ ] Choose and add a renderer backend (e.g., imgui_impl_opengl3.cpp)
[ ] Add imgui/ and imgui/backends/ to your include path
[ ] In your init code: call ImGui::CreateContext()
[ ] In your init code: configure ImGuiIO (ConfigFlags, fonts, etc.)
[ ] In your init code: call backend Init functions
[ ] In your init code: build and upload the font atlas texture
[ ] In your main loop: call backend NewFrame functions
[ ] In your main loop: call ImGui::NewFrame()
[ ] In your main loop: call your UI code (Begin/End, widgets, etc.)
[ ] In your main loop: call ImGui::Render()
[ ] In your main loop: call backend RenderDrawData function
[ ] In your shutdown code: call backend Shutdown functions
[ ] In your shutdown code: call ImGui::DestroyContext()

Minimal Integration Example

#include "imgui.h"
#include "imgui_impl_glfw.h"
#include "imgui_impl_opengl3.h"
#include <GLFW/glfw3.h>

int main() {
    // Platform init
    glfwInit();
    GLFWwindow* window = glfwCreateWindow(1280, 720, "My App", NULL, NULL);
    glfwMakeContextCurrent(window);

    // Dear ImGui init
    IMGUI_CHECKVERSION();
    ImGui::CreateContext();
    ImGuiIO& io = ImGui::GetIO();
    io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;

    // Backend init
    ImGui_ImplGlfw_InitForOpenGL(window, true);
    ImGui_ImplOpenGL3_Init("#version 130");

    // Main loop
    while (!glfwWindowShouldClose(window)) {
        glfwPollEvents();

        ImGui_ImplOpenGL3_NewFrame();
        ImGui_ImplGlfw_NewFrame();
        ImGui::NewFrame();

        // Your UI code
        ImGui::ShowDemoWindow();

        // Render
        ImGui::Render();
        int display_w, display_h;
        glfwGetFramebufferSize(window, &display_w, &display_h);
        glViewport(0, 0, display_w, display_h);
        glClearColor(0.1f, 0.1f, 0.1f, 1.0f);
        glClear(GL_COLOR_BUFFER_BIT);
        ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
        glfwSwapBuffers(window);
    }

    // Shutdown
    ImGui_ImplOpenGL3_Shutdown();
    ImGui_ImplGlfw_Shutdown();
    ImGui::DestroyContext();
    glfwDestroyWindow(window);
    glfwTerminate();
    return 0;
}

Upgrading Between Versions

When upgrading Dear ImGui to a new version:

1. Read the relevant section of docs/CHANGELOG.txt for breaking changes.
2. Compile with IMGUI_DISABLE_OBSOLETE_FUNCTIONS temporarily defined to identify deprecated API usage.
3. Update backend files — they must match the core version.
4. Delete imgui.ini if the layout looks broken (settings format may have changed subtly).
5. Test with the demo window (ShowDemoWindow()) to verify rendering correctness.

Important

Always update the core library files and backend files together. Mixing core files from one version with backend files from another version causes subtle bugs, crashes, or compilation errors. The IMGUI_CHECKVERSION() macro helps detect version mismatches at runtime.

5. Operations

5.1 Settings Persistence (.ini)

Dear ImGui automatically saves and loads UI layout settings to a .ini file. This includes window positions, sizes, collapsed states, and table column configuration (widths, order, visibility, sort state).

Configuration

Manual Save/Load

// Save to disk
ImGui::SaveIniSettingsToDisk("imgui.ini");

// Save to memory (returns a string you can store however you like)
const char* ini_data = ImGui::SaveIniSettingsToMemory();

// Load from disk
ImGui::LoadIniSettingsFromDisk("imgui.ini");

// Load from memory buffer
ImGui::LoadIniSettingsFromMemory(ini_data, ini_data_size);

Custom Save Timing

Check io.WantSaveIniSettings each frame. When true, Dear ImGui wants to persist settings. You can save at that moment and clear the flag:

if (io.WantSaveIniSettings) {
    const char* data = ImGui::SaveIniSettingsToMemory();
    // Write 'data' to your custom storage (database, cloud, etc.)
    io.WantSaveIniSettings = false;
}

What Gets Stored

• Window state: Position, size, collapsed/expanded, scroll position
• Table state: Column widths, column order, column visibility, sort column and direction
• Settings handlers: Custom data via ImGuiSettingsHandler (register with ImGui::AddSettingsHandler())

5.2 Debug Tools

Dear ImGui ships several built-in debug tools for inspecting internal state:

Metrics/Debugger Window

ImGui::ShowMetricsWindow(&show_metrics);

Tip

The Metrics window is the single most useful debugging tool in Dear ImGui. It shows windows, draw commands, font atlas contents, active IDs, internal state, and memory usage. When something looks wrong, open Metrics first.

Features:

• Window list with geometry, flags, draw command counts
• Draw command list per window (texture, vertex count, clip rect)
• Font atlas visualization
• Active ID / hovered ID display
• Input event log
• Internal state inspection

Debug Log Window

ImGui::ShowDebugLogWindow(&show_debug_log);

Displays a simplified event log of internal Dear ImGui events (focus changes, activation, navigation, etc.). Use io.ConfigDebugHighlightIdConflicts to detect and surface duplicate ID issues.

ID Stack Tool

ImGui::ShowIDStackToolWindow(&show_id_stack);

Hover any item to see the full ID stack that produced its unique identifier. Invaluable for diagnosing ID conflicts, which manifest as widgets sharing state (e.g., two sliders that move together).

About Window

ImGui::ShowAboutWindow(&show_about);

Shows version information, build configuration, credits, and compile-time options that are active.

Item Picker

ImGui::DebugStartItemPicker();

Activates a mode where you can click any widget to select it in the Metrics window. Useful for finding which code created a specific visual element.

Style Color Flash

ImGui::DebugFlashStyleColor(ImGuiCol_Button);

Briefly flashes all widgets using the specified color, helping you identify which elements use which style colors.

Compile-Time Debug Options

• IMGUI_DEBUG_PARANOID — Enable slower, stricter assertions. For CI/development builds.
• IMGUI_DEBUG_HIGHLIGHT_ALL_ID_CONFLICTS — Highlight every conflicting ID (not just the first pair). Performance impact.

5.3 Logging / Capture

Dear ImGui can capture all text output from widgets to a file, the clipboard, or TTY:

// Start logging
ImGui::LogToTTY();              // Log to stdout
ImGui::LogToFile(-1, "log.txt"); // Log to file
ImGui::LogToClipboard();         // Log to OS clipboard

// ... render widgets (their text output is captured) ...

// Stop logging
ImGui::LogFinish();

// Show log buttons in the UI
ImGui::LogButtons();  // Renders Log To TTY / File / Clipboard buttons

// Insert custom text into the log
ImGui::LogText("Custom log entry\n");

Logging captures the text content of all widgets rendered between LogTo*() and LogFinish(). This is useful for generating text summaries of UI state or for accessibility.

6. Performance

Draw Call Batching

Dear ImGui automatically batches draw calls by texture. All widgets rendered with the same texture (typically the font atlas) are merged into continuous vertex/index buffers with a single draw command. Texture changes or clip rectangle changes create new draw commands.

The number of draw commands per frame is visible in the Metrics window. Typical applications with a single font produce very few draw commands (often single digits).

Note

Dear ImGui's rendering is NOT immediate-mode at the GPU level. Despite the immediate-mode API, Dear ImGui accumulates geometry into optimized vertex buffers that are rendered in batched draw calls. This is comparable to retained-mode rendering performance for the same geometry.

Large List Optimization with ImGuiListClipper

For lists with thousands or millions of items, ImGuiListClipper performs viewport culling — only items visible on screen are processed:

ImGuiListClipper clipper;
clipper.Begin(1000000);  // 1 million items
while (clipper.Step()) {
    for (int i = clipper.DisplayStart; i < clipper.DisplayEnd; i++) {
        ImGui::Text("Item %d", i);
    }
}

This reduces per-frame cost from O(N) to O(visible items), regardless of total count.

Index Buffer Size

By default, ImDrawIdx is unsigned short (16-bit), limiting each ImDrawList to 65535 vertices. For complex UIs that exceed this:

• Recommended: Define ImDrawIdx as unsigned int in imconfig.h for 32-bit indices.
• Alternative: Enable ImGuiBackendFlags_RendererHasVtxOffset in your renderer to support the ImDrawCmd::VtxOffset field, which allows 16-bit indices with vertex offsets.

Anti-Aliasing Controls

SSE Optimizations

SSE intrinsics are used for ImVec2/ImVec4 operations when available (x86/x64, MSVC/GCC/Clang). Disable with IMGUI_DISABLE_SSE if targeting non-SSE platforms or if conflicts arise.

Memory Management

Dear ImGui uses a pluggable allocator system:

// Set custom allocators BEFORE CreateContext()
ImGui::SetAllocatorFunctions(MyMallocFunc, MyFreeFunc, my_user_data);
ImGui::CreateContext();

All internal allocations go through these functions. The default uses malloc/free. Custom allocators can integrate with your engine's memory system, track allocations, or use pool allocators for reduced fragmentation.

Text Rendering

For large text blocks, use TextUnformatted() instead of Text():

// Slow for large text: copies and formats the string
ImGui::Text("%s", large_buffer);

// Fast for large text: no copy, no formatting, direct rendering
ImGui::TextUnformatted(large_buffer, large_buffer + large_buffer_size);

TextUnformatted() accepts a begin/end pointer pair and renders directly without copying or formatting. For multi-megabyte text blocks, this is significantly faster.

Font Atlas Optimization

The font atlas texture size directly impacts GPU memory and upload time. Optimize by:

Performance Profiling

Use the Metrics window (ShowMetricsWindow()) to monitor:

• Draw commands per frame: Should be low (single digits for simple UIs, tens for complex ones)
• Vertices/indices per frame: Thousands is normal; hundreds of thousands suggests optimization opportunities
• Window count: Hidden windows still consume memory; use NoSavedSettings for transient windows
• Font atlas size: Monitor texture dimensions; consider glyph range reduction if oversized

Threading Considerations

Dear ImGui is NOT thread-safe. All calls must happen on a single thread (the thread that calls NewFrame() and Render()). Common safe patterns:

• Collect data from worker threads into shared buffers, then display from the main thread
• Use ImGui::SetCurrentContext() if different threads use different contexts (rare)
• The ImDrawList splitter (ImDrawListSplitter) can help organize draw data but does not enable multi-threaded submission

7. Security

Dear ImGui is a client-side UI library with a minimal attack surface. It does not open network connections, parse untrusted input formats, or manage credentials. Security considerations are primarily about integration safety.

File System Access

By default, Dear ImGui performs file I/O only for:

• Settings: Loading/saving imgui.ini (controlled by io.IniFilename)
• Logging: Writing to io.LogFilename when logging is active
• Shell: Opening files/URLs via Platform_OpenInShellFn

To fully disable file I/O:

// In imconfig.h
#define IMGUI_DISABLE_FILE_FUNCTIONS  // Removes ALL file I/O, including .ini

To disable only shell execution:

#define IMGUI_DISABLE_DEFAULT_SHELL_FUNCTIONS

Memory Safety

• All assertions are configurable via IM_ASSERT. Override to integrate with your crash reporting.
• Buffer sizes for InputText are caller-controlled. Dear ImGui respects the provided buffer size.
• ImVector (internal dynamic array) uses bounds checking in debug builds.

Input Validation

Dear ImGui uses IM_ASSERT extensively to catch programmer errors (null pointers, mismatched Begin/End calls, invalid parameters). These are development-time checks, not security validations. In release builds, IM_ASSERT typically compiles to nothing.

Caution

When using Dear ImGui across DLL boundaries, you MUST call ImGui::SetCurrentContext() and ImGui::SetAllocatorFunctions() in every DLL before making any Dear ImGui calls. Failure to do this causes memory corruption: one DLL allocates with its own heap, another DLL frees from a different heap. This is the most common source of crashes in DLL-based Dear ImGui deployments.

No Secrets Handling

Dear ImGui does not process, store, or transmit credentials, tokens, or sensitive data. The InputText widget with ImGuiInputTextFlags_Password masks display characters but stores the plaintext in the caller's buffer — Dear ImGui does not manage that buffer's lifetime or security.

Anti-Cheat Considerations

The CONTRIBUTING.md file explicitly states that Dear ImGui does not accept contributions related to cheating in online games. While Dear ImGui is commonly used for game development tools and debug overlays, using it to create cheat interfaces for online games is outside the project's intended use and community norms.

8. Developer Internals

8.1 Repository Structure

imgui/
├── imgui.cpp                    Core library (~22K lines)
├── imgui.h                      Public API header
├── imgui_internal.h             Internal types (not public API)
├── imgui_widgets.cpp            All standard widgets
├── imgui_tables.cpp             Table system
├── imgui_draw.cpp               Drawing, font atlas, textures
├── imgui_demo.cpp               Demo window with inline code samples
├── imconfig.h                   Compile-time configuration
├── imstb_rectpack.h             Embedded stb_rect_pack
├── imstb_textedit.h             Embedded stb_textedit
├── imstb_truetype.h             Embedded stb_truetype
├── backends/                    Platform + renderer backends
│   ├── imgui_impl_glfw.cpp/h        GLFW platform backend
│   ├── imgui_impl_sdl2.cpp/h        SDL2 platform backend
│   ├── imgui_impl_sdl3.cpp/h        SDL3 platform backend
│   ├── imgui_impl_win32.cpp/h       Win32 platform backend
│   ├── imgui_impl_osx.mm/h          macOS/Cocoa platform backend
│   ├── imgui_impl_android.cpp/h     Android platform backend
│   ├── imgui_impl_glut.cpp/h        GLUT platform backend (legacy)
│   ├── imgui_impl_opengl2.cpp/h     OpenGL2 renderer backend
│   ├── imgui_impl_opengl3.cpp/h     OpenGL3/ES2/ES3 renderer backend
│   ├── imgui_impl_opengl3_loader.h  Minimal OpenGL function loader
│   ├── imgui_impl_dx9.cpp/h         DirectX9 renderer backend
│   ├── imgui_impl_dx10.cpp/h        DirectX10 renderer backend
│   ├── imgui_impl_dx11.cpp/h        DirectX11 renderer backend
│   ├── imgui_impl_dx12.cpp/h        DirectX12 renderer backend
│   ├── imgui_impl_vulkan.cpp/h      Vulkan renderer backend
│   ├── imgui_impl_metal.mm/h        Metal renderer backend
│   ├── imgui_impl_wgpu.cpp/h        WebGPU renderer backend
│   ├── imgui_impl_sdlgpu3.cpp/h     SDL_GPU renderer backend
│   ├── imgui_impl_sdlrenderer2.cpp/h  SDL_Renderer2 renderer backend
│   ├── imgui_impl_sdlrenderer3.cpp/h  SDL_Renderer3 renderer backend
│   ├── imgui_impl_allegro5.cpp/h    Allegro5 combined backend
│   ├── imgui_impl_null.cpp/h        Null/no-op backend (for testing)
│   ├── vulkan/                      GLSL shaders + SPIR-V for Vulkan
│   └── sdlgpu3/                     Shaders for SDL_GPU backend
├── examples/                    26 example applications
│   ├── example_win32_directx9/
│   ├── example_win32_directx10/
│   ├── example_win32_directx11/
│   ├── example_win32_directx12/
│   ├── example_win32_opengl3/
│   ├── example_glfw_opengl2/
│   ├── example_glfw_opengl3/
│   ├── example_glfw_vulkan/
│   ├── example_glfw_metal/
│   ├── example_sdl2_opengl2/
│   ├── example_sdl2_opengl3/
│   ├── example_sdl2_vulkan/
│   ├── example_sdl2_sdlrenderer2/
│   ├── example_sdl3_opengl3/
│   ├── example_sdl3_vulkan/
│   ├── example_sdl3_sdlgpu3/
│   ├── example_sdl3_sdlrenderer3/
│   ├── example_apple_metal/
│   ├── example_apple_opengl2/
│   ├── example_android_opengl3/
│   ├── example_emscripten_wgpu/
│   ├── example_allegro5/
│   ├── example_glut_opengl2/
│   └── example_null/
├── misc/
│   ├── cpp/                     std::string InputText helpers
│   │   ├── imgui_stdlib.cpp
│   │   └── imgui_stdlib.h
│   ├── debuggers/               IDE/debugger helpers
│   │   ├── imgui.natvis          Visual Studio type visualization
│   │   ├── imgui.natstepfilter   Visual Studio step filter
│   │   ├── imgui.gdb             GDB pretty printers
│   │   └── imgui_lldb.py         LLDB synthetic children
│   ├── fonts/                   Bundled TTF fonts (7 fonts)
│   ├── freetype/                FreeType font rasterizer integration
│   │   └── imgui_freetype.cpp/h
│   └── single_file/            Single-compilation-unit header
│       └── imgui_single_file.h
└── docs/                        Documentation
    ├── FAQ.md
    ├── BACKENDS.md
    ├── FONTS.md
    ├── CHANGELOG.txt
    ├── EXAMPLES.md
    ├── README.md
    ├── TODO.txt
    └── CONTRIBUTING.md

8.2 Architecture Deep Dive

ImGuiContext

ImGuiContext is the central state container. Everything Dear ImGui knows is stored here: the window list, IO state, style, font atlas, navigation state, settings, active widget IDs, drag-and-drop state, and more. A global pointer (GImGui) points to the current context.

// Create and set context (typically once at startup)
ImGuiContext* ctx = ImGui::CreateContext();

// Multiple contexts are supported (e.g., for testing)
ImGuiContext* ctx2 = ImGui::CreateContext();
ImGui::SetCurrentContext(ctx2);  // Switch active context

Multiple contexts are independent — each has its own windows, fonts, style, and state. This is used for unit testing, editor-within-editor scenarios, or DLL boundary management.

Window System

Windows (ImGuiWindow) are created and managed internally. Each ImGui::Begin("Name") call finds or creates a window identified by the hash of its name string. Windows store:

• Position, size, scroll position
• Draw list (ImDrawList)
• Content region and work rect
• Collapsed/skipped state
• Parent/child relationships

Window ordering (front-to-back) is managed by the focus system. BringToFront operations are deferred to avoid reordering during iteration.

ID System

Dear ImGui uses a stack-based hashing system to generate unique IDs for widgets. Each widget needs a unique ID to maintain its state (active, focused, edited value, etc.) across frames.

// ID is hash of "##MySlider" + window ID
ImGui::SliderFloat("##MySlider", &value, 0.0f, 1.0f);

// Push additional ID components onto the stack
ImGui::PushID(item_index);
ImGui::Button("OK");    // ID = window + item_index + "OK"
ImGui::PopID();

// String IDs
ImGui::PushID("subsection");
ImGui::Button("OK");    // ID = window + "subsection" + "OK"
ImGui::PopID();

ID conflicts (two widgets with the same ID) cause them to share state — sliders move together, buttons activate together. Use the ID Stack Tool (ShowIDStackToolWindow()) and io.ConfigDebugHighlightIdConflicts to detect these issues.

ImDrawList

ImDrawList is the low-level drawing API. Each window has one. It accumulates draw commands as vertex/index buffers:

• Primitives: AddLine(), AddRect(), AddRectFilled(), AddCircle(), AddCircleFilled(), AddTriangle(), AddTriangleFilled()
• Complex shapes: AddBezierCubic(), AddBezierQuadratic(), AddPolyline(), AddConvexPolyFilled(), AddConcavePolyFilled()
• Text: AddText()
• Images: AddImage(), AddImageQuad(), AddImageRounded()
• Clipping: PushClipRect(), PopClipRect()

You can also obtain a foreground or background ImDrawList via ImGui::GetForegroundDrawList() / ImGui::GetBackgroundDrawList() for drawing outside of window boundaries.

ImDrawData

After ImGui::Render(), ImGui::GetDrawData() returns an ImDrawData struct containing:

• CmdLists[] — Array of ImDrawList pointers
• TotalVtxCount, TotalIdxCount — Total vertex/index count
• DisplayPos, DisplaySize — Viewport coordinates
• FramebufferScale — For high-DPI rendering

The renderer backend iterates CmdLists, then iterates each list's CmdBuffer (array of ImDrawCmd), setting up clip rectangles and textures, and issuing draw calls.

ImFontAtlas

ImFontAtlas manages font loading, glyph rasterization, and texture atlas packing:

ImGuiIO& io = ImGui::GetIO();

// Add fonts
io.Fonts->AddFontDefault();                                    // ProggyClean 13px
io.Fonts->AddFontFromFileTTF("Roboto-Medium.ttf", 16.0f);     // Custom font
io.Fonts->AddFontFromFileTTF("icons.ttf", 16.0f, &config, icon_ranges);  // Icon font

// Build the atlas (called automatically, or manually)
io.Fonts->Build();

// Get texture data for upload to GPU
unsigned char* pixels;
int width, height;
io.Fonts->GetTexDataAsRGBA32(&pixels, &width, &height);
// Upload 'pixels' to your GPU texture...

In v1.92+, the font atlas supports dynamic rebuilding and the ImTextureData / ImTextureRef system for decoupling texture identity from GPU upload timing.

Navigation System

Dear ImGui includes a complete keyboard/gamepad navigation system. When enabled via ImGuiConfigFlags_NavEnableKeyboard or ImGuiConfigFlags_NavEnableGamepad:

• Arrow keys move focus between widgets
• Enter/Space activate the focused widget
• Alt activates menu bars
• Escape closes popups/menus
• Ctrl+Tab switches between windows

The navigation system handles focus scoping, shortcut routing (ensuring the correct widget receives a keyboard shortcut), and input ownership (which subsystem "owns" a particular key press this frame).

Settings System

The settings system persists and restores UI state across sessions. Built-in handlers save window and table state. Custom handlers can be registered:

ImGuiSettingsHandler handler;
handler.TypeName = "MyData";
handler.TypeHash = ImHashStr("MyData");
handler.ReadOpenFn = MyReadOpenFn;
handler.ReadLineFn = MyReadLineFn;
handler.WriteAllFn = MyWriteAllFn;
ImGui::AddSettingsHandler(&handler);

8.3 Backend Interface

Writing a Custom Platform Backend

A platform backend feeds Dear ImGui with OS-level information. Implement these responsibilities:

Required:

1. Set io.DisplaySize every frame with the window/framebuffer dimensions.
2. Set io.DeltaTime every frame with the elapsed time since last frame.
3. Feed keyboard input via io.AddKeyEvent(), io.AddKeyAnalogEvent().
4. Feed mouse input via io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent().
5. Set io.AddFocusEvent() when the application window gains/loses focus.

Optional: 6. Set io.BackendFlags |= ImGuiBackendFlags_HasMouseCursors and implement cursor shape changes via ImGui::GetMouseCursor(). 7. Set io.BackendFlags |= ImGuiBackendFlags_HasSetMousePos if you can reposition the OS mouse. 8. Set io.BackendFlags |= ImGuiBackendFlags_HasGamepad and feed gamepad input. 9. Implement platform_io.Platform_GetClipboardTextFn / Platform_SetClipboardTextFn for clipboard. 10. Implement platform_io.Platform_SetImeDataFn for IME support. 11. Implement platform_io.Platform_OpenInShellFn for opening files/URLs.

Writing a Custom Renderer Backend

A renderer backend creates GPU resources and draws the geometry Dear ImGui produces.

Required:

1. Create a GPU texture from the font atlas pixel data (io.Fonts->GetTexDataAsRGBA32()).
2. Store the GPU texture handle in io.Fonts->SetTexID().
3. Implement the render loop: iterate ImDrawData->CmdLists[], set up an orthographic projection, and for each ImDrawCmd:
   • Set the clip/scissor rectangle from cmd.ClipRect
   • Bind the texture from cmd.GetTexID()
   • Draw cmd.ElemCount indices starting at cmd.IdxOffset with vertex offset cmd.VtxOffset
4. Handle the special ImDrawCallback values: if cmd.UserCallback == ImDrawCallback_ResetRenderState, reset your render state.

Note

The platform_io.Textures[] system (new in v1.92) provides a backend-agnostic way to manage textures dynamically. When ImGuiBackendFlags_RendererHasTextures is set, Dear ImGui creates ImTextureData entries in platform_io.Textures[] that the renderer should process (upload new textures, update changed ones, destroy removed ones) each frame. This enables dynamic font atlas rebuilding without application-level intervention.

Optional: 5. Set io.BackendFlags |= ImGuiBackendFlags_RendererHasVtxOffset if your renderer supports ImDrawCmd::VtxOffset (required for large meshes with 16-bit indices). 6. Handle ImDrawCallback_SetSamplerLinear and ImDrawCallback_SetSamplerNearest for texture filtering control. 7. Set io.BackendFlags |= ImGuiBackendFlags_RendererHasTextures and process platform_io.Textures[] for dynamic texture management.

8.4 Official Backends Inventory

Platform Backends

Renderer Backends

Combined Backends

8.5 Module Reference

imgui.cpp (~22,000 lines)

The core module. Implements:

• Context management: CreateContext(), DestroyContext(), SetCurrentContext(), GetCurrentContext()
• Frame lifecycle: NewFrame(), EndFrame(), Render(), GetDrawData()
• Window system: Begin(), End(), window creation/destruction, ordering, focus management
• ID system: PushID(), PopID(), GetID(), the hash stack
• Layout: cursor positioning, SameLine(), NewLine(), Separator(), Spacing(), Dummy(), Indent(), Unindent(), Group
• Input processing: mouse, keyboard, gamepad event queue, input ownership, focus routing
• Navigation: keyboard/gamepad focus movement, shortcut routing, SetKeyboardFocusHere()
• Popups & modals: OpenPopup(), BeginPopup(), BeginPopupModal(), CloseCurrentPopup(), popup stack management
• Drag-and-drop: BeginDragDropSource(), SetDragDropPayload(), BeginDragDropTarget(), AcceptDragDropPayload()
• Settings: .ini load/save, ImGuiSettingsHandler registration
• Miscellaneous: IsItemHovered(), IsItemActive(), IsItemClicked(), SetTooltip(), BeginTooltip(), color conversion, clipboard, style management

imgui_widgets.cpp

All user-facing widgets:

• Text: Text(), TextColored(), TextWrapped(), TextUnformatted(), BulletText(), SeparatorText(), TextLink(), TextLinkOpenURL()
• Buttons: Button(), SmallButton(), InvisibleButton(), ArrowButton(), ImageButton()
• Checkboxes & radio: Checkbox(), CheckboxFlags(), RadioButton()
• Sliders: SliderFloat(), SliderInt(), SliderAngle(), SliderScalar(), VSliderFloat(), VSliderInt(), VSliderScalar()
• Drags: DragFloat(), DragInt(), DragScalar(), DragFloatRange2(), DragIntRange2()
• Input: InputText(), InputTextMultiline(), InputFloat(), InputInt(), InputDouble(), InputScalar()
• Color: ColorEdit3(), ColorEdit4(), ColorPicker3(), ColorPicker4(), ColorButton()
• Trees: TreeNode(), TreeNodeEx(), TreePush(), TreePop(), CollapsingHeader(), SetNextItemOpen()
• Selectables: Selectable()
• Multi-select: BeginMultiSelect(), EndMultiSelect(), SetNextItemSelectionUserData()
• Combo: BeginCombo(), EndCombo(), Combo()
• List box: BeginListBox(), EndListBox(), ListBox()
• Menus: BeginMenuBar(), EndMenuBar(), BeginMainMenuBar(), EndMainMenuBar(), BeginMenu(), EndMenu(), MenuItem()
• Tabs: BeginTabBar(), EndTabBar(), BeginTabItem(), EndTabItem(), TabItemButton(), SetTabItemClosed()
• Tooltips: SetTooltip(), BeginTooltip(), EndTooltip(), BeginItemTooltip(), SetItemTooltip()
• Values: Value() (convenience wrappers for displaying labeled values)
• Images: Image(), ImageButton()
• Progress: ProgressBar()

imgui_tables.cpp

The complete table system:

• BeginTable() / EndTable() — create a table with specified columns and flags
• TableSetupColumn() — define column properties (label, flags, initial width)
• TableHeadersRow() — emit the header row with clickable sort headers
• TableAngledHeadersRow() — emit angled (rotated) column headers
• TableNextRow() / TableNextColumn() / TableSetColumnIndex() — navigate cells
• TableSetBgColor() — set per-row or per-cell background colors
• TableGetSortSpecs() — retrieve current sort specification for implementing custom sort
• Column auto-fit, freezing (horizontal/vertical), scrolling, context menu for column visibility
• Per-column state persistence in .ini files

imgui_draw.cpp

Drawing and font systems:

• ImDrawList: all rendering primitives, vertex/index buffer management, draw command batching
• ImFontAtlas: font loading (AddFontFromFileTTF, AddFontFromMemoryTTF, AddFontDefault), atlas building, glyph lookup, custom rectangles
• ImFont: per-font glyph data, text measurement (CalcTextSizeA), rendering
• ImTextureData: texture metadata and pixel data management (v1.92+)
• Polyline rendering: anti-aliased line and fill algorithms

imgui_demo.cpp

The interactive demo window (ShowDemoWindow()) demonstrates every feature with inline source code. It serves as both documentation and testing surface. Widgets are organized by category with collapsing sections. The demo window is the primary learning resource for Dear ImGui.

misc/freetype/imgui_freetype.cpp

Optional FreeType integration for higher-quality font rasterization:

• Better hinting and anti-aliasing than stb_truetype
• SVG-in-OpenType support (emoji fonts, color fonts) via plutosvg or lunasvg
• Dynamic font scaling improvements
• Enable with IMGUI_ENABLE_FREETYPE in imconfig.h

misc/cpp/imgui_stdlib.cpp

std::string wrapper for InputText:

#include "misc/cpp/imgui_stdlib.h"

std::string my_string = "Hello";
ImGui::InputText("Label", &my_string);  // Resizes std::string automatically

misc/debuggers/

Debugger visualization helpers:

8.6 Code Patterns & Conventions

Formatting

• Indentation: 4 spaces (no tabs)
• Braces: Opening brace on the same line for functions and control flow
• Line length: No strict limit, but generally under ~120 characters

Naming

Comments

// Text comment describing behavior
//FunctionCall();  // Commented-out code (no space after //)

C++ Usage

Dear ImGui intentionally uses minimal C++ features:

• No exceptions, no RTTI
• No STL containers in the public API (uses ImVector internally)
• C-style casts preferred over C++ casts
• Limited template usage
• No virtual functions in the public API
• ImVec2 and ImVec4 are plain structs, not classes

Public API Conventions

• All public functions are in the ImGui:: namespace
• All public symbols are decorated with IMGUI_API
• Enum types use a trailing underscore: ImGuiWindowFlags_
• Flag enums use power-of-two values for bitwise combination
• Output parameters are typically the first pointer argument
• Return values indicate interaction (e.g., Button() returns true when clicked)

8.7 Testing

Dear ImGui Test Engine

The primary testing tool is the Dear ImGui Test Engine (ocornut/imgui_test_engine), a separate repository. It provides:

• Simulated input (mouse clicks, keyboard input, navigation)
• Automated UI interaction testing
• Screenshot comparison
• Performance benchmarking
• Enabled by defining IMGUI_ENABLE_TEST_ENGINE in imconfig.h

CI / Build Verification

GitHub Actions workflows verify that Dear ImGui compiles cleanly across:

• Multiple compilers (GCC, Clang, MSVC)
• Multiple platforms (Windows, Linux, macOS)
• Multiple C++ standards (C++11 through C++20)
• All example applications

Static Analysis

• PVS-Studio: Used for static analysis (configuration in repository)
• Code coverage: OpenCppCoverage for measuring test coverage on Windows

Version Checking

// In your main file — detects config/version mismatches across translation units
IMGUI_CHECKVERSION();

IMGUI_CHECKVERSION() compares the version string, sizeof(ImGuiIO), and sizeof(ImGuiStyle) against the compiled library. A mismatch indicates that different translation units are using different imconfig.h settings or different Dear ImGui versions — a guaranteed crash source.

8.8 Contributing

Contributor License Agreement

All code contributed to Dear ImGui becomes part of the project under the MIT license. Copyright is assigned to the project maintainer (Omar Cornut / ocornut).

Branch Strategy

• master — Stable releases and ongoing development
• docking — Multi-viewport and docking branch (experimental features)
• Feature branches for pull requests

Code Style Requirements

• Match existing conventions exactly: 4 spaces, naming patterns, comment style
• Include screenshots or GIFs for any visual changes
• Provide a Minimal Complete Verifiable Example (MCVE) for bug reports

Issue Reporting

• Bugs: GitHub Issues with MCVE
• Feature requests: GitHub Issues with use case description
• Build/linking help: GitHub Discussions (not Issues)
• Cheating-related: Not accepted. Explicitly excluded in CONTRIBUTING.md.

9. Integration Points

Language Bindings

Dear ImGui has bindings for virtually every programming language. The two primary C wrapper projects are:

Auto-generated bindings exist for:

Framework Integrations

Dear ImGui integrates with major game engines and application frameworks:

Notable Extensions

Custom Widget Creation

Create custom widgets using the low-level ImDrawList API combined with cursor and item registration:

void MyCustomWidget(const char* label, float* value) {
    ImGuiWindow* window = ImGui::GetCurrentWindow();
    if (window->SkipItems) return;

    ImGuiContext& g = *GImGui;
    const ImGuiStyle& style = g.Style;
    const ImGuiID id = window->GetID(label);

    ImVec2 pos = window->DC.CursorPos;
    ImVec2 size(200, 30);

    ImRect bb(pos, ImVec2(pos.x + size.x, pos.y + size.y));
    ImGui::ItemSize(size);
    if (!ImGui::ItemAdd(bb, id)) return;

    bool hovered, held;
    bool pressed = ImGui::ButtonBehavior(bb, id, &hovered, &held);

    ImDrawList* draw_list = ImGui::GetWindowDrawList();
    draw_list->AddRectFilled(bb.Min, bb.Max,
        ImGui::GetColorU32(held ? ImGuiCol_ButtonActive :
                          hovered ? ImGuiCol_ButtonHovered : ImGuiCol_Button));
    // ... draw your widget content ...
}

Custom Backend Creation

To create a custom platform or renderer backend:

Platform Backend Template:

// imgui_impl_myplatform.h
#pragma once
#include "imgui.h"

bool ImGui_ImplMyPlatform_Init(MyWindowHandle* window);
void ImGui_ImplMyPlatform_Shutdown();
void ImGui_ImplMyPlatform_NewFrame();

// imgui_impl_myplatform.cpp
#include "imgui.h"
#include "imgui_impl_myplatform.h"

struct ImGui_ImplMyPlatform_Data {
    MyWindowHandle* Window;
    double          Time;
    // ... platform-specific state ...
};

static ImGui_ImplMyPlatform_Data* ImGui_ImplMyPlatform_GetBackendData() {
    return ImGui::GetCurrentContext()
        ? (ImGui_ImplMyPlatform_Data*)ImGui::GetIO().BackendPlatformUserData
        : NULL;
}

bool ImGui_ImplMyPlatform_Init(MyWindowHandle* window) {
    ImGuiIO& io = ImGui::GetIO();

    auto* bd = IM_NEW(ImGui_ImplMyPlatform_Data)();
    io.BackendPlatformUserData = (void*)bd;
    io.BackendPlatformName = "imgui_impl_myplatform";
    io.BackendFlags |= ImGuiBackendFlags_HasMouseCursors;
    io.BackendFlags |= ImGuiBackendFlags_HasSetMousePos;

    bd->Window = window;
    bd->Time = 0.0;

    // Set up clipboard functions
    io.PlatformIO.Platform_GetClipboardTextFn = MyGetClipboardText;
    io.PlatformIO.Platform_SetClipboardTextFn = MySetClipboardText;

    return true;
}

void ImGui_ImplMyPlatform_NewFrame() {
    ImGuiIO& io = ImGui::GetIO();
    auto* bd = ImGui_ImplMyPlatform_GetBackendData();

    // Update display size
    int w, h;
    MyGetWindowSize(bd->Window, &w, &h);
    io.DisplaySize = ImVec2((float)w, (float)h);

    // Update delta time
    double current_time = MyGetTime();
    io.DeltaTime = bd->Time > 0.0
        ? (float)(current_time - bd->Time)
        : (float)(1.0f / 60.0f);
    bd->Time = current_time;

    // Feed mouse input
    io.AddMousePosEvent(MyGetMouseX(), MyGetMouseY());
    io.AddMouseButtonEvent(0, MyIsMouseDown(MOUSE_LEFT));
    io.AddMouseButtonEvent(1, MyIsMouseDown(MOUSE_RIGHT));
    io.AddMouseButtonEvent(2, MyIsMouseDown(MOUSE_MIDDLE));

    // Feed keyboard input (for each key event since last frame)
    // io.AddKeyEvent(ImGuiKey_..., is_pressed);
}

void ImGui_ImplMyPlatform_Shutdown() {
    auto* bd = ImGui_ImplMyPlatform_GetBackendData();
    ImGuiIO& io = ImGui::GetIO();
    io.BackendPlatformUserData = NULL;
    io.BackendPlatformName = NULL;
    IM_DELETE(bd);
}

Renderer Backend Template (render loop core):

void ImGui_ImplMyRenderer_RenderDrawData(ImDrawData* draw_data) {
    // Set up orthographic projection
    float L = draw_data->DisplayPos.x;
    float R = draw_data->DisplayPos.x + draw_data->DisplaySize.x;
    float T = draw_data->DisplayPos.y;
    float B = draw_data->DisplayPos.y + draw_data->DisplaySize.y;
    MySetProjectionMatrix(L, R, T, B);

    ImVec2 clip_off = draw_data->DisplayPos;
    ImVec2 clip_scale = draw_data->FramebufferScale;

    for (int n = 0; n < draw_data->CmdListsCount; n++) {
        const ImDrawList* cmd_list = draw_data->CmdLists[n];

        // Upload vertex/index data
        MyUploadVertexBuffer(cmd_list->VtxBuffer.Data,
                            cmd_list->VtxBuffer.Size * sizeof(ImDrawVert));
        MyUploadIndexBuffer(cmd_list->IdxBuffer.Data,
                           cmd_list->IdxBuffer.Size * sizeof(ImDrawIdx));

        for (int cmd_i = 0; cmd_i < cmd_list->CmdBuffer.Size; cmd_i++) {
            const ImDrawCmd* pcmd = &cmd_list->CmdBuffer[cmd_i];

            if (pcmd->UserCallback) {
                if (pcmd->UserCallback == ImDrawCallback_ResetRenderState)
                    MyResetRenderState(draw_data);
                else
                    pcmd->UserCallback(cmd_list, pcmd);
                continue;
            }

            // Compute clip rectangle
            ImVec2 clip_min((pcmd->ClipRect.x - clip_off.x) * clip_scale.x,
                           (pcmd->ClipRect.y - clip_off.y) * clip_scale.y);
            ImVec2 clip_max((pcmd->ClipRect.z - clip_off.x) * clip_scale.x,
                           (pcmd->ClipRect.w - clip_off.y) * clip_scale.y);
            if (clip_max.x <= clip_min.x || clip_max.y <= clip_min.y)
                continue;

            MySetScissorRect((int)clip_min.x, (int)clip_min.y,
                            (int)(clip_max.x - clip_min.x),
                            (int)(clip_max.y - clip_min.y));
            MyBindTexture(pcmd->GetTexID());
            MyDrawIndexed(pcmd->ElemCount,
                         pcmd->IdxOffset,
                         pcmd->VtxOffset);
        }
    }
}

ImDrawVert Layout

The vertex format used by Dear ImGui:

struct ImDrawVert {
    ImVec2 pos;   // 2 floats: screen-space position
    ImVec2 uv;    // 2 floats: texture coordinates
    ImU32  col;   // 4 bytes: packed RGBA color (or BGRA with IMGUI_USE_BGRA_PACKED_COLOR)
};
// Total: 20 bytes per vertex (no padding on most platforms)

Your renderer's vertex input layout must match this structure exactly. The position is in screen-space pixels (not normalized). The UV coordinates reference the font atlas texture. The color is pre-multiplied by alpha in some cases (check your blending setup).

Recommended Blend State

Dear ImGui expects alpha blending to be enabled:

SrcBlend = SRC_ALPHA
DstBlend = ONE_MINUS_SRC_ALPHA
SrcBlendAlpha = ONE
DstBlendAlpha = ONE_MINUS_SRC_ALPHA
BlendOp = ADD

Disable depth testing and backface culling. Enable scissor testing.

10. Troubleshooting

Build & Link Errors

Problem: Undefined reference to ImGui::CreateContext() or other Dear ImGui functions. Solution: Ensure all required .cpp files are compiled and linked: imgui.cpp, imgui_draw.cpp, imgui_tables.cpp, imgui_widgets.cpp, plus your chosen backend files.

Problem: Multiple definition errors for Dear ImGui symbols. Solution: Each .cpp file should be compiled exactly once. If using imgui_single_file.h, do not also compile the individual .cpp files. If using a build system, ensure Dear ImGui sources are not added to multiple targets without proper linking.

Problem: IMGUI_CHECKVERSION() assertion fails. Solution: Different translation units are seeing different imconfig.h settings or different Dear ImGui versions. Ensure all files include the same imconfig.h and the same version of Dear ImGui headers.

Problem: Linker errors related to stb_truetype or stb_rect_pack duplicate symbols. Solution: If you compile stb libraries separately, define IMGUI_DISABLE_STB_TRUETYPE_IMPLEMENTATION and/or IMGUI_DISABLE_STB_RECT_PACK_IMPLEMENTATION in imconfig.h.

Problem: "Cannot open include file: 'imgui.h'" in backend files. Solution: Add the Dear ImGui root directory to your include path. Backend files include "imgui.h" without a path prefix.

Backend Initialization

Problem: Black screen after initialization — no UI visible. Solution: Verify that io.DisplaySize is set to valid (non-zero) values. Check that the rendering clear color is different from the window background color. Ensure ImGui::Render() is called after ImGui::EndFrame() (which is called automatically by Render()).

Problem: UI renders but doesn't respond to input. Solution: Verify that the platform backend is feeding input events (check io.MousePos, io.KeysDown in the Metrics window). Ensure ImGui::NewFrame() is called before any widget code. Check io.WantCaptureMouse / io.WantCaptureKeyboard — if you're filtering events based on these, ensure you're checking them at the right time (after NewFrame()).

Problem: Crash on ImGui::NewFrame() — null pointer dereference. Solution: The font atlas has not been built. Ensure at least one font is loaded (or use AddFontDefault()) and that the atlas texture has been uploaded to the GPU before the first frame.

Problem: Assertion g.IO.DeltaTime >= 0.0f or extreme layout jitter. Solution: io.DeltaTime must be positive. A value of 0.0f or negative causes division-by-zero or infinite values in layout. Ensure your frame timing code handles edge cases (first frame, breakpoints, system sleep).

Font & Text Rendering

Problem: Text appears as white rectangles or question marks. Solution: The font atlas texture was not uploaded to the GPU, or the texture ID is incorrect. Rebuild the atlas and re-upload after adding fonts. Check that io.Fonts->TexID matches the GPU texture handle.

Problem: Chinese/Japanese/Korean characters display as ? or boxes. Solution: Load a font that contains CJK glyphs and specify the appropriate glyph range:

io.Fonts->AddFontFromFileTTF("NotoSansCJK.ttf", 18.0f, NULL,
    io.Fonts->GetGlyphRangesChineseFull());

Problem: Font is blurry or too small/large on high-DPI displays. Solution: Use style.FontScaleDpi to account for display scaling. Load fonts at a higher pixel size (e.g., 2x the desired display size) and set the scale accordingly. FreeType (IMGUI_ENABLE_FREETYPE) provides better hinting at various sizes.

Problem: Font atlas texture is too large (exceeds GPU texture size limit). Solution: Reduce the number of fonts or glyph ranges. Use ImFontAtlasFlags_NoPowerOfTwoHeight to avoid wasting space. Consider using multiple atlases or loading only the glyph ranges you need.

Tables

Problem: Table columns have unexpected widths or don't resize properly. Solution: Check ImGuiTableFlags_SizingFixedFit vs ImGuiTableFlags_SizingStretchProp. Fixed-fit columns need explicit widths in TableSetupColumn(). Stretch columns divide available space proportionally.

Problem: Table sort specification not updating when headers are clicked. Solution: You must call TableGetSortSpecs() each frame and check specs->SpecsDirty. When dirty, re-sort your data and set specs->SpecsDirty = false.

Problem: Assertion failure or visual corruption with many table columns. Solution: Tables support up to 64 columns. If you need more, consider a different layout approach. For wide tables, enable ImGuiTableFlags_ScrollX.

Drawing

Problem: IM_ASSERT failure: thickness must be > 0.0f in AddLine or similar. Solution: Ensure all line thickness values are strictly positive. A thickness of 0.0f is not valid. Use 1.0f as the minimum.

Problem: Draw list vertex overflow — assertion on vertex count. Solution: Define ImDrawIdx as unsigned int in imconfig.h for 32-bit indices, or ensure your renderer supports ImDrawCmd::VtxOffset (set ImGuiBackendFlags_RendererHasVtxOffset).

Problem: Textures display with wrong filtering (pixelated or blurry). Solution: Texture sampling depends on your renderer's sampler state. Dear ImGui 1.92+ supports ImDrawCallback_SetSamplerLinear and ImDrawCallback_SetSamplerNearest callbacks for per-draw-command sampler control. Ensure your renderer backend handles these callbacks if you mix pixel art and smooth textures.

Navigation

Problem: Keyboard/gamepad navigation doesn't work. Solution: Enable navigation via config flags:

io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;
io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;

For gamepad, the platform backend must also set ImGuiBackendFlags_HasGamepad and feed gamepad input.

Problem: Navigation skips certain widgets or gets "stuck." Solution: Some widgets (like InvisibleButton or widgets with ImGuiItemFlags_NoNav) are excluded from navigation. Check if the widget explicitly opts out. For custom widgets, ensure ImGui::ItemAdd() is called with a valid ID.

Settings (.ini)

Problem: Window positions reset every launch. Solution: Verify io.IniFilename is set to a writable path. Check that the application exits cleanly (calls ImGui::DestroyContext()), which triggers the auto-save. Alternatively, call SaveIniSettingsToDisk() explicitly.

Problem: .ini file grows very large or contains stale entries. Solution: Windows that are created once and never shown again still persist in the .ini file. Use ImGuiWindowFlags_NoSavedSettings for temporary/transient windows. Manually delete the .ini file to reset.

Problem: .ini file from an older version causes layout issues. Solution: Dear ImGui handles version changes gracefully — unrecognized sections are ignored. However, if layouts look wrong, delete the .ini file to start fresh. Consider versioning your .ini filename (e.g., myapp_v2.ini) when making significant layout changes.

DPI & Scaling

Problem: UI is too small on 4K/HiDPI displays. Solution: Use the platform backend's DPI detection and set style.FontScaleDpi accordingly. Load fonts at a higher size (e.g., round(13 * dpi_scale) for the default font). On Windows, the Win32 backend handles DPI awareness via ImGui_ImplWin32_EnableDpiAwareness().

Problem: UI is rendered at the correct size but the framebuffer is wrong (blurry). Solution: Distinguish between window size (logical pixels) and framebuffer size (physical pixels). Set io.DisplaySize to the window size, and set io.DisplayFramebufferScale to the ratio of framebuffer-to-window size. The Vulkan, Metal, and some OpenGL backends handle this automatically.

Memory

Problem: Memory leak in custom backend. Solution: Ensure you destroy all GPU resources (textures, buffers, pipelines) in your backend's shutdown function. If using the platform_io.Textures[] system, process pending texture destruction requests each frame. Call ImGui::DestroyContext() on shutdown.

Problem: IM_ASSERT failure in allocator. Solution: If you use SetAllocatorFunctions(), ensure the functions are set before CreateContext() and remain valid for the lifetime of the context. When using DLLs, set allocators in each DLL.

Miscellaneous

Warning

When IsItemHovered() or IsItemActive() returns unexpected values, check the order of your calls. These functions always refer to the last item submitted. If you call Button("A") then Text("B"), IsItemHovered() refers to the Text, not the Button. Query interaction state immediately after the widget call.

Problem: Two widgets share state (sliders move together, checkboxes toggle together). Solution: This is an ID conflict. The two widgets have the same ID. Use PushID() / PopID() to add unique identifiers, or use the "##" separator in labels to add hidden ID suffixes:

ImGui::Button("OK##dialog1");
ImGui::Button("OK##dialog2");

Problem: Popup appears and immediately closes. Solution: OpenPopup() and BeginPopup() must be called in the same ID scope (same window). Ensure OpenPopup() is not called every frame — it should be called only on the triggering event (e.g., inside an if (Button(...)) block).

Problem: Begin()/End() mismatch assertion. Solution: Every ImGui::Begin() must have a matching ImGui::End(), even when Begin() returns false (window is collapsed/clipped). The false return means you can skip content but must still call End().

Problem: Context menu does not appear on right-click. Solution: Use BeginPopupContextItem() immediately after the target widget, or BeginPopupContextWindow() for window-level context menus. Ensure ImGuiPopupFlags_MouseButtonRight is used (this is the default for context popup functions). If the popup was previously opened and closed, it may need ImGuiPopupFlags_NoReopen to avoid flickering.

Problem: Drag-and-drop payload is not received by the target. Solution: Verify that the payload type string matches exactly between SetDragDropPayload() and AcceptDragDropPayload(). Check that BeginDragDropTarget() is called immediately after the receiving widget (it applies to the last item). Ensure the source does not use ImGuiDragDropFlags_PayloadNoCrossContext if source and target are in different contexts.

Problem: InputText does not accept certain characters. Solution: Check if ImGuiInputTextFlags_CharsDecimal, CharsHexadecimal, CharsUppercase, or CharsNoBlank is set. These flags filter input characters. Use a CallbackCharFilter for custom filtering logic.

Problem: InputText buffer overflow or truncation. Solution: The buf_size parameter must include space for the null terminator. A buffer of size 64 can hold 63 characters plus \0. For dynamic resizing with std::string, use the misc/cpp/imgui_stdlib.h wrapper with ImGuiInputTextFlags_CallbackResize.

Problem: Colors look wrong (swapped red/blue channels). Solution: If using IMGUI_USE_BGRA_PACKED_COLOR, ensure your renderer expects BGRA vertex colors. DirectX typically uses BGRA; OpenGL typically uses RGBA. Mismatch between the define and your renderer causes red/blue channel swap.

Problem: Multi-select does not work — only one item can be selected. Solution: Multi-select requires wrapping your selection loop with BeginMultiSelect() / EndMultiSelect() and processing the ImGuiMultiSelectIO requests returned by these functions. Each selectable item must call SetNextItemSelectionUserData() before the Selectable() call. Without BeginMultiSelect(), each Selectable() operates independently.

Problem: Table columns reappear after being hidden via the context menu. Solution: Table state is persisted in the .ini file. If you recreate the table with a different column count or different column setup, the old state may conflict. Use ImGuiTableFlags_NoSavedSettings for tables whose column structure changes dynamically, or change the table's string ID when the structure changes.

Problem: ShowDemoWindow() is not available / linker error. Solution: imgui_demo.cpp must be compiled and linked. If you defined IMGUI_DISABLE_DEMO_WINDOWS, the demo window code is stripped. Remove that define or don't call ShowDemoWindow().

Problem: Assertion window->IDStack.Size > 0 or similar ID stack assertion. Solution: You have mismatched PushID() / PopID() calls. Every PushID() must have exactly one matching PopID(). Use the ID Stack Tool (ShowIDStackToolWindow()) to inspect the stack at runtime.

Problem: ImGui::Image() displays a white rectangle instead of the texture. Solution: The texture ID passed to Image() does not match a valid GPU texture handle. Verify that the texture was uploaded to the GPU and that the handle (stored as ImTextureID) is correct. On some backends, the texture handle is a pointer; on others, it is an integer. Ensure the type matches your backend's expectations.

Problem: Keyboard shortcuts fire in the wrong window. Solution: Dear ImGui routes keyboard shortcuts to the focused window. Use ImGui::SetNextWindowFocus() or ensure the correct window has focus when the shortcut should be active. For global shortcuts, process them in your application code before ImGui::NewFrame(), checking io.WantCaptureKeyboard to avoid conflicts.

Problem: Application freezes or hangs during ImGui::Render(). Solution: This typically indicates an infinite loop in layout calculation, caused by contradictory size constraints (e.g., a child window that auto-resizes based on content that auto-resizes based on the child window). Simplify the layout to break the circular dependency.

Problem: ImGui::GetIO() crashes or returns garbage. Solution: No context has been created. Call ImGui::CreateContext() before any other Dear ImGui function. If using multiple threads, ensure each thread that calls Dear ImGui has the correct context set via ImGui::SetCurrentContext().

11. Reference

11.1 Version History

Current: v1.92.8 WIP (commit bda4982, 2026-04-24)

Branches:

• master — Stable releases and ongoing development
• docking — Multi-viewport + docking features (experimental, API subject to change)

11.2 Embedded Fonts

The default font (ProggyClean 13px) is embedded in the source code and available without loading any file. Define IMGUI_DISABLE_DEFAULT_FONT to remove it and save ~10KB of binary size.

11.3 Embedded Third-Party Libraries

These are vendored copies of Sean Barrett's stb single-header libraries, with minor modifications. Override paths with IMGUI_STB_TRUETYPE_FILENAME, IMGUI_STB_RECT_PACK_FILENAME, or IMGUI_STB_SPRINTF_FILENAME to use your own versions.

11.4 Example Applications

The examples/ directory contains 26 ready-to-build applications demonstrating different platform + renderer combinations:

11.5 Commonly Used Public API Functions (Quick Reference)

Context & Lifecycle

Windows

Layout

Style

Fonts