Backend System

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 document describes Dear ImGui's backend architecture, which provides the abstraction layer between Dear ImGui's core library and specific platform/rendering APIs. Backends handle platform-specific concerns (windowing, input, OS integration) and graphics API concerns (texture management, rendering primitives) separately, allowing any platform backend to work with any renderer backend.

For information about integrating backends into your application, see Getting Started. For details about specific backend implementations, see Platform Backends and Renderer Backends.

---

Backend Architecture Overview

Dear ImGui's backend system separates concerns into two distinct layers:

Sources: docs/BACKENDS.md1-50 docs/README.md42-48

Platform and Renderer Separation

Aspect	Platform Backend	Renderer Backend
Responsibility	Windowing, input, OS integration	Texture management, draw command rendering
Key Structures	ImGuiIO, ImGuiPlatformIO	ImDrawData, ImTextureData
Examples	imgui_impl_win32.cpp, imgui_impl_glfw.cpp	imgui_impl_dx11.cpp, imgui_impl_opengl3.cpp
Input/Output	Reads OS events → writes to ImGuiIO	Reads ImDrawData → renders to GPU
Functions	ImGui_ImplXXXX_Init(), ImGui_ImplXXXX_NewFrame()	ImGui_ImplXXXX_Init(), ImGui_ImplXXXX_RenderDrawData()

This separation allows any platform backend to be combined with any renderer backend. For example, imgui_impl_glfw.cpp can work with imgui_impl_opengl3.cpp, imgui_impl_vulkan.cpp, or imgui_impl_metal.mm.

Sources: docs/BACKENDS.md54-67 docs/EXAMPLES.md1-50

---

Standard Backend Implementations

Dear ImGui provides standard backends in the backends/ folder that support the most common platforms and graphics APIs.

Platform Backends

Backend File	Platform	Notes
imgui_impl_win32.cpp	Windows (Win32 API)	Native Windows support, DPI awareness, IME
imgui_impl_glfw.cpp	GLFW (cross-platform)	Windows, macOS, Linux
imgui_impl_sdl2.cpp	SDL2 (cross-platform)	Windows, macOS, Linux, iOS, Android
imgui_impl_sdl3.cpp	SDL3 (cross-platform)	Modern SDL API
imgui_impl_osx.mm	macOS (Cocoa)	Native macOS support
imgui_impl_android.cpp	Android	Native Android support
imgui_impl_glut.cpp	GLUT/FreeGLUT	Legacy, not recommended

Sources: docs/BACKENDS.md71-84 docs/README.md131-134

Renderer Backends

Backend File	Graphics API	Notes
imgui_impl_dx9.cpp	DirectX 9	Windows
imgui_impl_dx10.cpp	DirectX 10	Windows
imgui_impl_dx11.cpp	DirectX 11	Windows
imgui_impl_dx12.cpp	DirectX 12	Windows
imgui_impl_opengl2.cpp	OpenGL 2 (legacy)	Fixed pipeline, not for modern GL
imgui_impl_opengl3.cpp	OpenGL 3/4, OpenGL ES 2/3, WebGL	Programmable pipeline
imgui_impl_vulkan.cpp	Vulkan	Cross-platform
imgui_impl_metal.mm	Metal	macOS, iOS
imgui_impl_wgpu.cpp	WebGPU	Web and native (Dawn/WGPU)
imgui_impl_sdlrenderer2.cpp	SDL_Renderer (SDL 2.0.18+)	Software/hardware rendering
imgui_impl_sdlrenderer3.cpp	SDL_Renderer (SDL3)	Software/hardware rendering
imgui_impl_sdlgpu3.cpp	SDL_GPU (SDL3)	Portable 3D graphics API

Sources: docs/BACKENDS.md86-99 docs/EXAMPLES.md1-50

Framework Backends (Combined Platform + Renderer)

Backend File	Framework	Notes
imgui_impl_allegro5.cpp	Allegro 5	All-in-one
imgui_impl_null.cpp	Null (testing)	No rendering, for compilation tests

Sources: docs/BACKENDS.md100-104

---

Frame Lifecycle and Integration Pattern

Sources: docs/EXAMPLES.md16-36 docs/BACKENDS.md172-211

Typical Application Integration Code

The integration pattern is consistent across all backend combinations:

Sources: docs/EXAMPLES.md16-36 examples/ (all example applications)

---

Backend Capabilities (ImGuiBackendFlags)

Backends signal their capabilities using the ImGuiBackendFlags enum, stored in ImGuiIO::BackendFlags.

Platform Backend Flags

Flag	Meaning	Set By
ImGuiBackendFlags_HasGamepad	Backend can provide gamepad input and currently has one connected	Platform backend
ImGuiBackendFlags_HasMouseCursors	Backend supports changing the OS mouse cursor shape	Platform backend
ImGuiBackendFlags_HasSetMousePos	Backend supports io.WantSetMousePos to reposition the mouse	Platform backend
ImGuiBackendFlags_PlatformHasViewports	Platform backend supports creating/managing multiple OS windows (multi-viewport, docking branch)	Platform backend
ImGuiBackendFlags_HasMouseHoveredViewport	Platform backend can report which viewport is currently hovered by mouse	Platform backend

Sources: docs/BACKENDS.md177-186

Renderer Backend Flags

Flag	Meaning	Set By
ImGuiBackendFlags_RendererHasVtxOffset	Renderer supports ImDrawCmd::VtxOffset for rendering with vertex offsets (allows >64K vertices per window)	Renderer backend
ImGuiBackendFlags_RendererHasViewports	Renderer backend supports multiple viewports (multi-viewport, docking branch)	Renderer backend
ImGuiBackendFlags_RendererHasTextures	Renderer backend supports ImTextureData system for dynamic texture management (1.92+)	Renderer backend

Sources: docs/BACKENDS.md214-217 docs/BACKENDS.md295-318

---

Platform Backend Implementation

Core Responsibilities

Sources: docs/BACKENDS.md172-211

Platform Backend Structure

Platform backends typically follow this structure:

Initialization (ImGui_ImplXXXX_Init):

• Allocate backend data, store in io.BackendPlatformUserData
• Set io.BackendPlatformName = "imgui_impl_xxxx"
• Set io.BackendFlags with supported features
• Setup platform-specific handlers in ImGuiPlatformIO
• Initialize input state

Per-Frame Update (ImGui_ImplXXXX_NewFrame):

• Update io.DeltaTime (time since last frame)
• Update io.DisplaySize (window dimensions)
• Update io.DisplayFramebufferScale (macOS retina displays)
• Update mouse cursor shape if ImGuiBackendFlags_HasMouseCursors is set

Event Handling (typically in application's event loop or callbacks):

• Mouse: io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent(), io.AddMouseSourceEvent()
• Keyboard: io.AddKeyEvent(), io.AddInputCharacter()
• Gamepad: io.AddKeyEvent(ImGuiKey_GamepadXXX), io.AddKeyAnalogEvent()
• Focus: io.AddFocusEvent()

Shutdown (ImGui_ImplXXXX_Shutdown):

• Cleanup backend data
• Clear io.BackendPlatformUserData, io.BackendPlatformName

Sources: docs/BACKENDS.md172-211

Key Input Functions

Function	Purpose
io.AddMousePosEvent(x, y)	Report mouse position
io.AddMouseButtonEvent(button, down)	Report mouse button press/release
io.AddMouseWheelEvent(wheel_x, wheel_y)	Report mouse wheel scroll
io.AddMouseSourceEvent(source)	Distinguish mouse/touchscreen/pen input
io.AddKeyEvent(key, down)	Report keyboard key press/release
io.AddInputCharacter(c)	Report text input character (UTF-16)
io.AddKeyAnalogEvent(key, down, value)	Report analog input (gamepad sticks/triggers)
io.AddFocusEvent(focused)	Report window focus gained/lost

Sources: docs/BACKENDS.md194-206

---

Renderer Backend Implementation

Core Responsibilities

Sources: docs/BACKENDS.md212-293

Rendering Pipeline

The ImGui_ImplXXXX_RenderDrawData() function must:

1. Update Textures (if ImGuiBackendFlags_RendererHasTextures is set):

   • Iterate draw_data->Textures array
   • Process textures with Status != ImTextureStatus_OK
   • Handle creation, updates, and destruction

2. Setup Render State:

   • Enable alpha blending
   • Disable backface culling
   • Disable depth testing/writing
   • Enable scissor testing
   • Setup bilinear texture sampling
   • Setup viewport covering draw_data->DisplayPos to draw_data->DisplayPos + draw_data->DisplaySize
   • Setup orthographic projection matrix

3. Process Draw Commands:

Sources: docs/BACKENDS.md218-293

ImDrawCmd Structure

Each ImDrawCmd represents a rendering batch:

Field	Type	Purpose
ClipRect	ImVec4	Scissor rectangle (x1, y1, x2, y2) in display coordinates
TextureId	ImTextureID	Texture to bind (use GetTexID() to retrieve)
VtxOffset	unsigned int	Offset in vertex buffer (if ImGuiBackendFlags_RendererHasVtxOffset)
IdxOffset	unsigned int	Offset in index buffer
ElemCount	unsigned int	Number of indices (draw ElemCount/3 triangles)
UserCallback	function pointer	Optional custom rendering callback

Sources: docs/BACKENDS.md246-290

---

Texture Management System (1.92+)

Version 1.92 introduced ImTextureData for dynamic texture management, which is the foundation for dynamic font scaling and other advanced features.

ImTextureData Lifecycle

ImTextureStatus Enum

Status	Meaning	Backend Action
ImTextureStatus_WantCreate	Texture needs creation	Create GPU texture, upload all pixels, call SetTexID() and SetStatus(OK)
ImTextureStatus_OK	Texture is valid	No action needed
ImTextureStatus_WantUpdate	Texture needs partial update	Upload pixels in UpdateRect, call SetStatus(OK)
ImTextureStatus_WantDestroy	Texture should be destroyed	Destroy GPU texture (after in-flight frames), call SetStatus(Destroyed)
ImTextureStatus_Destroyed	Texture destroyed	No action needed

Sources: docs/BACKENDS.md295-378

Processing Texture Updates

Sources: docs/BACKENDS.md333-378

Key ImTextureData Functions

Function	Purpose
tex->GetPixels()	Get pointer to pixel data (CPU-side copy)
tex->GetPixelsAt(x, y)	Get pointer to pixel at specific coordinates
tex->GetPitch()	Get row stride in bytes
tex->SetTexID(id)	Store backend-specific texture identifier
tex->SetStatus(status)	Acknowledge texture state transition
tex->Width, tex->Height	Texture dimensions
tex->Format	Pixel format (ImTextureFormat_RGBA32 or ImTextureFormat_Alpha8)
tex->UpdateRect	Rectangle to update (for WantUpdate status)
tex->UnusedFrames	Frames since last use (for delayed destruction)
tex->BackendUserData	Storage for backend-specific data

Sources: docs/BACKENDS.md333-378 docs/FAQ.md444-493

Backend Migration to ImGuiBackendFlags_RendererHasTextures

Supporting ImGuiBackendFlags_RendererHasTextures typically adds 20-90 lines of code to a renderer backend:

Standard backend migration commits (for reference):

• DirectX11: commit 372fd27 (+40 lines)
• OpenGL3: commit dbb91a5 (+47 lines)
• Vulkan: commit abe294b (+33 lines)
• Metal: commit 26c017d (+55 lines)

Required changes:

1. Set ImGuiBackendFlags_RendererHasTextures flag during initialization
2. In RenderDrawData(): Iterate draw_data->Textures and process updates
3. In Shutdown(): Iterate ImGui::GetPlatformIO().Textures and destroy all textures

Sources: docs/BACKENDS.md295-318

---

Example Backend Combinations

The examples/ folder demonstrates various backend combinations:

Windows Platform

Example	Platform Backend	Renderer Backend	Notes
example_win32_directx9	imgui_impl_win32.cpp	imgui_impl_dx9.cpp	DirectX 9
example_win32_directx11	imgui_impl_win32.cpp	imgui_impl_dx11.cpp	DirectX 11 (recommended)
example_win32_directx12	imgui_impl_win32.cpp	imgui_impl_dx12.cpp	DirectX 12
example_win32_opengl3	imgui_impl_win32.cpp	imgui_impl_opengl3.cpp	OpenGL 3+
example_win32_vulkan	imgui_impl_win32.cpp	imgui_impl_vulkan.cpp	Vulkan

Cross-Platform (GLFW)

Example	Platform Backend	Renderer Backend	Notes
example_glfw_opengl2	imgui_impl_glfw.cpp	imgui_impl_opengl2.cpp	Legacy OpenGL
example_glfw_opengl3	imgui_impl_glfw.cpp	imgui_impl_opengl3.cpp	Modern OpenGL, WebGL
example_glfw_vulkan	imgui_impl_glfw.cpp	imgui_impl_vulkan.cpp	Vulkan
example_glfw_metal	imgui_impl_glfw.cpp	imgui_impl_metal.mm	Metal (macOS)
example_glfw_wgpu	imgui_impl_glfw.cpp	imgui_impl_wgpu.cpp	WebGPU

Cross-Platform (SDL)

Example	Platform Backend	Renderer Backend	Notes
example_sdl2_opengl3	imgui_impl_sdl2.cpp	imgui_impl_opengl3.cpp	SDL2 + OpenGL
example_sdl3_opengl3	imgui_impl_sdl3.cpp	imgui_impl_opengl3.cpp	SDL3 + OpenGL
example_sdl3_sdlgpu3	imgui_impl_sdl3.cpp	imgui_impl_sdlgpu3.cpp	SDL3 + SDL_GPU
example_sdl2_vulkan	imgui_impl_sdl2.cpp	imgui_impl_vulkan.cpp	SDL2 + Vulkan

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

---

Custom Backend Development

For guidance on writing custom backends, see Custom Backend Development.

Key considerations:

• Use standard backends first: Standard backends are battle-tested and handle edge cases correctly. Custom backends often have fewer features and more bugs.
• Platform backends are harder: Input handling, IME support, multi-viewport, and DPI awareness have many subtleties. Renderer backends are more straightforward.
• Start with one platform: Get desktop builds working first (e.g., Win32 + your renderer) before attempting other platforms.
• Reference existing backends: Study similar backends in backends/ folder as templates.

Sources: docs/BACKENDS.md126-171