Getting Started

Relevant source files

• docs/BACKENDS.md
• docs/EXAMPLES.md
• docs/FAQ.md
• docs/FONTS.md
• docs/README.md
• docs/TODO.txt
• examples/imgui_examples.sln

This page provides a practical guide for integrating Dear ImGui into your application. It covers choosing backends, understanding the integration pattern, and running your first example. For backend-specific implementation details, see Backend Architecture. For platform-specific examples, see sections 5.2 through 5.7.

---

Integration Overview

Dear ImGui integration requires three components working together:

Component	Purpose	Location
Core Library	Widget API, rendering data structures, context management	imgui.cpp, imgui.h, imgui_widgets.cpp, imgui_tables.cpp, imgui_draw.cpp
Platform Backend	Window management, input events (mouse/keyboard/gamepad)	backends/imgui_impl_*.cpp (platform)
Renderer Backend	Texture management, vertex/index buffer rendering	backends/imgui_impl_*.cpp (renderer)

The core library files are platform-agnostic and compile directly into your project. No special build process is required—simply add all .cpp files from the root directory to your build system.

Sources: docs/README.md42-44 docs/BACKENDS.md27-42

---

Choosing Backends

Platform Backend Selection

The platform backend handles OS integration and input. Choose based on your target platform:

Recommended choices:

• Portable applications: SDL3 (imgui_impl_sdl3.cpp) offers the broadest platform support
• Windows-only: Win32 (imgui_impl_win32.cpp) provides the best integration for multi-viewport support
• Existing GLFW projects: GLFW (imgui_impl_glfw.cpp) integrates seamlessly

Sources: docs/BACKENDS.md76-83 docs/BACKENDS.md108-120

Renderer Backend Selection

The renderer backend translates ImGui draw data into graphics API calls:

Graphics API	Backend File	Platforms	Notes
OpenGL 3+/ES2/ES3	imgui_impl_opengl3.cpp	All platforms, WebGL	Modern programmable pipeline
Vulkan	imgui_impl_vulkan.cpp	Win/Mac/Linux/Android	High-performance, verbose setup
DirectX 11	imgui_impl_dx11.cpp	Windows	Recommended for Windows
DirectX 12	imgui_impl_dx12.cpp	Windows	Complex initialization
Metal	imgui_impl_metal.mm	macOS/iOS	Apple platforms
WebGPU	imgui_impl_wgpu.cpp	Web + native	Modern web standard
SDL_GPU	imgui_impl_sdlgpu3.cpp	Portable SDL3 API	Simplifies cross-platform 3D

Sources: docs/BACKENDS.md85-98 examples/imgui_examples.sln1-221

---

The Integration Pattern

Frame Lifecycle Architecture

Every Dear ImGui application follows this three-phase lifecycle:

Sources: docs/EXAMPLES.md18-36 docs/BACKENDS.md187-210

Minimal Integration Code Structure

The following table maps conceptual phases to actual function calls:

Phase	Function Call	Location	Purpose
Setup	ImGui::CreateContext()	imgui.h	Allocates ImGuiContext
	ImGui_ImplXXX_Init()	backends/imgui_impl_*.h	Initialize platform backend
	ImGui_ImplYYY_Init()	backends/imgui_impl_*.h	Initialize renderer backend
Frame Start	ImGui_ImplXXX_NewFrame()	Platform backend	Update timing/display
	ImGui_ImplYYY_NewFrame()	Renderer backend	Prepare renderer
	ImGui::NewFrame()	imgui.h	Begin ImGui frame
UI Submission	ImGui::Begin(), ImGui::Button(), etc.	imgui.h	Widget API calls
Frame End	ImGui::Render()	imgui.h	Finalize draw data
	ImGui::GetDrawData()	imgui.h	Retrieve ImDrawData*
	ImGui_ImplYYY_RenderDrawData()	Renderer backend	Render to GPU
Cleanup	ImGui_ImplYYY_Shutdown()	Renderer backend	Destroy renderer resources
	ImGui_ImplXXX_Shutdown()	Platform backend	Destroy platform resources
	ImGui::DestroyContext()	imgui.h	Free ImGuiContext

Sources: docs/EXAMPLES.md20-36 docs/FAQ.md148-157

---

Running Your First Example

Example Application Structure

All examples follow a consistent file structure:

Building an Example

Windows (Visual Studio):

1. Open examples/imgui_examples.sln in Visual Studio
2. Select an example project (e.g., example_win32_directx11)
3. Build and run (F5)

Windows (Command Line):

cd examples/example_win32_directx11
build_win32.bat

Linux/macOS (Make):

cd examples/example_glfw_opengl3
make
./example_glfw_opengl3

Available examples: See 20+ combinations in examples/ directory, documented in docs/EXAMPLES.md51-216

Sources: docs/EXAMPLES.md51-216 examples/imgui_examples.sln1-221

Anatomy of example_win32_directx11

This example demonstrates Win32 + DirectX 11 integration:

Key file locations:

• Main application logic: examples/example_win32_directx11/main.cpp
• Win32 platform backend: backends/imgui_impl_win32.cpp backends/imgui_impl_win32.h
• DirectX 11 renderer backend: backends/imgui_impl_dx11.cpp backends/imgui_impl_dx11.h

Sources: docs/EXAMPLES.md200-202 examples/imgui_examples.sln10-11

---

Common Integration Patterns

Pattern 1: Using Standard Backends Unmodified

Recommended approach for most users:

Benefits:

• Battle-tested implementations handle edge cases correctly
• Automatic updates for bug fixes and new features
• Multi-viewport support works out-of-the-box (docking branch)
• Reduces integration time to <1 hour

Sources: docs/BACKENDS.md123-143

Pattern 2: Custom Rendering with Standard Platform

For engines with custom renderers but standard windowing:

When to use:

• Your engine has its own high-level rendering abstraction
• You want to keep standard platform backend for correct input handling
• You need custom texture management

Sources: docs/BACKENDS.md145-149

---

First Steps After Integration

Step 1: Display the Demo Window

Once your example builds and runs, call ImGui::ShowDemoWindow() to see all features:

The demo window source code (imgui_demo.cpp112) serves as:

• Interactive documentation for all widgets
• Copy-paste reference for common patterns
• Live examples of advanced features

Sources: docs/README.md110-112

Step 2: Understanding Input Handling

Check io.WantCaptureMouse and io.WantCaptureKeyboard to determine input routing:

Flag	Meaning	Action
io.WantCaptureMouse == true	ImGui wants mouse input	Don't pass mouse to your app
io.WantCaptureKeyboard == true	ImGui wants keyboard input	Don't pass keyboard to your app
io.WantTextInput == true	ImGui needs text input	Show on-screen keyboard (mobile)

Important: Always pass ALL input events to ImGui via io.AddMousePosEvent(), io.AddKeyEvent(), etc., regardless of these flags. ImGui needs to see all events to function correctly (e.g., to detect clicks in empty space for unfocusing).

Sources: docs/FAQ.md162-186

Step 3: Loading Custom Fonts

The default embedded font (ProggyClean) is 13px and may appear small. To load custom fonts:

For detailed font documentation, see Font System.

Sources: docs/FONTS.md111-143

---

Troubleshooting Common Issues

Issue: "Little squares instead of text"

Symptom: All text appears as white rectangles.

Causes:

1. Font texture failed to upload (texture too large pre-1.92)
2. Texture not bound correctly in renderer
3. Atlas not built before rendering

Solutions:

• With 1.92+ backends: This should not happen; file a bug report
• Pre-1.92: Reduce font count or enable ImFontAtlasFlags_NoPowerOfTwoHeight
• Check graphics debugger (RenderDoc) to verify texture upload

Sources: docs/FAQ.md226-231

Issue: "Widgets clipping incorrectly"

Symptom: UI elements disappear or clip incorrectly when moving windows.

Cause: Clipping rectangles not handled correctly in custom renderer.

Solution:

• In RenderDrawData() implementation, use ImDrawCmd->ClipRect as (x1, y1, x2, y2) NOT (x, y, width, height)
• Subtract draw_data->DisplayPos when converting to viewport space

Sources: docs/FAQ.md236-257

Issue: "Same label causes collision"

Symptom: Multiple widgets with same label interfere with each other.

Cause: ImGui uses labels to generate IDs. Duplicate labels = duplicate IDs.

Solutions:

1. Use ## suffix: ImGui::Button("OK##1"), ImGui::Button("OK##2")
2. Use PushID()/PopID(): wrap widgets in ID scope
3. Use ### to separate label from ID: ImGui::Button("OK###unique_id")

Sources: docs/FAQ.md265-438

---

Next Steps

Learning Resources

Resource	Purpose	Location
Demo Window	Interactive examples of all widgets	Call ImGui::ShowDemoWindow()
Demo Source	Reference implementations	imgui_demo.cpp
FAQ	Common questions and issues	docs/FAQ.md
Programmer Guide	Architecture overview	imgui.cpp1-500 header comments
Wiki	Community tutorials and extensions	GitHub Wiki

Recommended Reading Order

1. Run and explore ImGui::ShowDemoWindow() interactively
2. Read "PROGRAMMER GUIDE" section in imgui.cpp header comments
3. Study an example application matching your target platform
4. Consult FAQ for specific integration issues
5. Review Backend Architecture if writing custom backends

Advanced Topics

After basic integration works:

• Multi-viewports: Detachable windows (docking branch) - see Backend Architecture
• Dynamic font scaling: Runtime font size changes - see Font Atlas and Management
• Custom rendering: Draw callbacks and primitives - see Custom Draw Commands
• Performance optimization: Reducing draw calls - see Performance Optimization

Sources: docs/README.md119-144 docs/FAQ.md51-64