Platform Backends

Relevant source files

• backends/imgui_impl_allegro5.cpp
• backends/imgui_impl_android.cpp
• backends/imgui_impl_android.h
• backends/imgui_impl_glfw.cpp
• backends/imgui_impl_glfw.h
• backends/imgui_impl_glut.cpp
• backends/imgui_impl_glut.h
• backends/imgui_impl_osx.mm
• backends/imgui_impl_sdl2.cpp
• backends/imgui_impl_sdl2.h
• backends/imgui_impl_sdl3.cpp
• backends/imgui_impl_sdl3.h
• backends/imgui_impl_win32.cpp
• backends/imgui_impl_win32.h

Purpose and Scope

Platform backends provide the interface between Dear ImGui's core library and the underlying operating system or windowing framework. They handle window management, input event processing (keyboard, mouse, gamepad), clipboard operations, IME support, and OS-specific features like DPI awareness. Platform backends work in conjunction with renderer backends (see Renderer Backends) to provide a complete integration—the platform backend handles input/windowing while the renderer backend handles graphics output.

For information about the overall backend architecture and how platform and renderer backends work together, see Backend Architecture. For implementing custom platform backends, see Custom Backend Development. For specific backend implementations, see child pages GLFW Backend, SDL Backends, Win32 Backend, etc.

---

Core Responsibilities

Platform backends are responsible for the following operations:

Responsibility	Description	ImGuiIO Integration
Window Management	Creating windows, handling resize, focus events	io.DisplaySize, io.AddFocusEvent()
Keyboard Input	Translating OS key events to ImGui key events	io.AddKeyEvent(), io.SetKeyEventNativeData()
Mouse Input	Mouse position, button clicks, wheel scrolling	io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent()
Gamepad Input	Controller/gamepad button and analog input	io.AddKeyAnalogEvent() for gamepad axes and buttons
Clipboard	Copy/paste text operations	platform_io.Platform_GetClipboardTextFn, platform_io.Platform_SetClipboardTextFn
Mouse Cursor	Setting cursor shape and visibility	ImGui::GetMouseCursor() + backend-specific cursor updates
IME Support	Input Method Editor for international text	platform_io.Platform_SetImeDataFn
Time Management	Delta time calculation for animations	io.DeltaTime

Sources: backends/imgui_impl_glfw.cpp1-100 backends/imgui_impl_sdl3.cpp1-100 backends/imgui_impl_win32.cpp1-100

---

Available Platform Backends

The following platform backends are provided:

Backend	File	Platforms	Notes
GLFW	imgui_impl_glfw.cpp/h	Windows, Linux, macOS	Cross-platform, modern, recommended
SDL2	imgui_impl_sdl2.cpp/h	Windows, Linux, macOS, iOS, Android, Web	Cross-platform, widely used
SDL3	imgui_impl_sdl3.cpp/h	Windows, Linux, macOS, iOS, Android, Web	SDL3 support with new SDL_GPU backend
Win32	imgui_impl_win32.cpp/h	Windows	Native Windows API, full Windows feature support
macOS	imgui_impl_osx.mm/h	macOS, iOS	Native Cocoa API
Android	imgui_impl_android.cpp/h	Android	Android native app support
GLUT	imgui_impl_glut.cpp/h	Cross-platform	Legacy, not recommended for new projects
Allegro5	imgui_impl_allegro5.cpp/h	Cross-platform	Combined platform+renderer backend

Sources: backends/imgui_impl_glfw.h1-72 backends/imgui_impl_sdl3.h1-55 backends/imgui_impl_win32.h1-54

---

Platform Backend API Pattern

All platform backends follow a consistent API pattern for initialization, frame processing, and shutdown:

Typical Platform Backend Initialization

Sources: backends/imgui_impl_glfw.cpp671-743 backends/imgui_impl_sdl3.cpp496-572 backends/imgui_impl_win32.cpp161-213

Initialization Functions

Platform backends provide specialized initialization functions based on the target renderer:

// GLFW examples
ImGui_ImplGlfw_InitForOpenGL(window, install_callbacks)
ImGui_ImplGlfw_InitForVulkan(window, install_callbacks)
ImGui_ImplGlfw_InitForOther(window, install_callbacks)

// SDL3 examples
ImGui_ImplSDL3_InitForOpenGL(window, gl_context)
ImGui_ImplSDL3_InitForVulkan(window)
ImGui_ImplSDL3_InitForD3D(window)
ImGui_ImplSDL3_InitForMetal(window)
ImGui_ImplSDL3_InitForSDLRenderer(window, renderer)
ImGui_ImplSDL3_InitForSDLGPU(window)

// Win32 examples
ImGui_ImplWin32_Init(hwnd)
ImGui_ImplWin32_InitForOpenGL(hwnd)

Sources: backends/imgui_impl_glfw.h33-35 backends/imgui_impl_sdl3.h31-37 backends/imgui_impl_win32.h24-27

---

Backend Data Structure Pattern

Platform backends store their internal state in a backend-specific data structure, stored in io.BackendPlatformUserData:

Common Backend Data Members

Backend	Structure Name	Key Members
GLFW	ImGui_ImplGlfw_Data	Window, Time, MouseCursors[], PrevUserCallback* callbacks
SDL3	ImGui_ImplSDL3_Data	Window, WindowID, Time, MouseCursors[], Gamepads, ImeData
Win32	ImGui_ImplWin32_Data	hWnd, Time, TicksPerSecond, XInputDLL, XInputGetState
macOS	ImGui_ImplOSX_Data	Time, MouseCursors[], Observer, KeyEventResponder, InputContext

Sources: backends/imgui_impl_glfw.cpp199-233 backends/imgui_impl_sdl3.cpp107-136 backends/imgui_impl_win32.cpp114-135 backends/imgui_impl_osx.mm84-96

---

Input Event Flow

Platform backends translate native OS events into Dear ImGui's event system through the ImGuiIO interface:

Input Event Translation Functions

Each backend provides key translation functions:

• GLFW: ImGui_ImplGlfw_KeyToImGuiKey() at backends/imgui_impl_glfw.cpp275-402
• SDL3: ImGui_ImplSDL3_KeyEventToImGuiKey() at backends/imgui_impl_sdl3.cpp215-365
• Win32: ImGui_ImplWin32_KeyEventToImGuiKey() at backends/imgui_impl_win32.cpp438-579
• macOS: ImGui_ImplOSX_KeyCodeToImGuiKey() at backends/imgui_impl_osx.mm272-393

Sources: backends/imgui_impl_glfw.cpp275-402 backends/imgui_impl_sdl3.cpp380-483 backends/imgui_impl_win32.cpp580-850

---

Feature Comparison Matrix

Feature	GLFW	SDL2	SDL3	Win32	macOS	Android	GLUT
Clipboard	✓	✓	✓	✓	✓	✗	✗
Mouse Cursor Shape	✓	✓	✓	✓	✓	✗	✗
Gamepad	✓	✓	✓	✓	✓	✗	✗
IME Support	✗	✓	✓	✓	✓	✗	✗
Touch/Pen Discrimination	Windows only	✓	✓	✓	✓	✓	✗
Multi-Context Support	✓	Limited	Limited	Limited	Limited	✗	✗
DPI Awareness	✓	✓	✓	✓	✓	✗	✗

Sources: backends/imgui_impl_glfw.cpp6-15 backends/imgui_impl_sdl3.cpp5-11 backends/imgui_impl_win32.cpp4-9

---

Backend Initialization Pattern

The typical initialization sequence for a platform backend:

Backend Capability Flags

Platform backends set capability flags in io.BackendFlags:

• ImGuiBackendFlags_HasMouseCursors - Backend can set mouse cursor shape
• ImGuiBackendFlags_HasSetMousePos - Backend can reposition mouse (for navigation)
• ImGuiBackendFlags_HasGamepad - Backend provides gamepad input

Sources: backends/imgui_impl_glfw.cpp671-743 backends/imgui_impl_sdl3.cpp496-572 backends/imgui_impl_win32.cpp161-213

---

NewFrame Responsibilities

During ImGui_ImplXXX_NewFrame(), platform backends must:

Example: GLFW NewFrame Implementation

The GLFW backend's NewFrame() function at backends/imgui_impl_glfw.cpp1146-1204 performs:

1. Updates io.DisplaySize from glfwGetWindowSize() and glfwGetFramebufferSize()
2. Calculates io.DeltaTime using glfwGetTime()
3. Updates mouse position via ImGui_ImplGlfw_UpdateMouseData()
4. Updates mouse cursor shape via glfwSetCursor()
5. Updates gamepad state via ImGui_ImplGlfw_UpdateGamepads()

Sources: backends/imgui_impl_glfw.cpp1146-1204 backends/imgui_impl_sdl3.cpp874-950 backends/imgui_impl_win32.cpp401-434

---

Callback Management

Platform backends handle native events through callbacks or event processing functions:

GLFW Callback Pattern

GLFW backends can install callbacks automatically or allow manual callback installation:

GLFW callback functions chain to previously installed user callbacks at backends/imgui_impl_glfw.cpp608-623:

void ImGui_ImplGlfw_InstallCallbacks(GLFWwindow* window)
{
    bd->PrevUserCallbackWindowFocus = glfwSetWindowFocusCallback(window, ImGui_ImplGlfw_WindowFocusCallback);
    bd->PrevUserCallbackCursorEnter = glfwSetCursorEnterCallback(window, ImGui_ImplGlfw_CursorEnterCallback);
    // ... etc
}

Sources: backends/imgui_impl_glfw.cpp608-640 backends/imgui_impl_glfw.h46-63

SDL Event Processing Pattern

SDL backends use an event processing function called from the application's event loop:

The ProcessEvent() function returns true if the event was handled by ImGui, allowing the application to skip processing.

Sources: backends/imgui_impl_sdl3.cpp380-483 backends/imgui_impl_sdl2.cpp380-504

Win32 Message Handler Pattern

The Win32 backend uses a WndProc message handler that must be called from the application's window procedure:

// Application code
LRESULT CALLBACK WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
    if (ImGui_ImplWin32_WndProcHandler(hWnd, msg, wParam, lParam))
        return true;
    
    // ... application's own message handling
}

The handler processes messages at backends/imgui_impl_win32.cpp580-850 including:

• WM_MOUSEMOVE, WM_LBUTTONDOWN, etc. → Mouse events
• WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, WM_SYSKEYUP → Keyboard events
• WM_MOUSEWHEEL, WM_MOUSEHWHEEL → Mouse wheel events
• WM_SETFOCUS, WM_KILLFOCUS → Focus events
• WM_CHAR, WM_IME_CHAR → Character input
• WM_SETCURSOR → Cursor shape updates

Sources: backends/imgui_impl_win32.cpp580-850 backends/imgui_impl_win32.h29-36

---

Mouse Cursor Management

Platform backends manage mouse cursor shape and visibility:

Cursor Mapping Examples

• GLFW at backends/imgui_impl_glfw.cpp1180-1191: Uses glfwCreateStandardCursor() with GLFW_ARROW_CURSOR, GLFW_IBEAM_CURSOR, etc.
• SDL3 at backends/imgui_impl_sdl3.cpp544-556: Uses SDL_CreateSystemCursor() with SDL_SYSTEM_CURSOR_DEFAULT, SDL_SYSTEM_CURSOR_TEXT, etc.
• Win32 at backends/imgui_impl_win32.cpp246-277: Uses LoadCursor() with IDC_ARROW, IDC_IBEAM, etc.

Sources: backends/imgui_impl_glfw.cpp1146-1204 backends/imgui_impl_sdl3.cpp544-556 backends/imgui_impl_win32.cpp246-277

---

Gamepad Support

Platform backends provide gamepad/controller input through the ImGui key event system:

Gamepad Input Examples

• Win32 uses XInput at backends/imgui_impl_win32.cpp343-399: XInputGetState() with XINPUT_GAMEPAD structure
• SDL3 uses SDL_Gamepad at backends/imgui_impl_sdl3.cpp741-820: SDL_GetGamepadButton() and SDL_GetGamepadAxis()
• macOS uses GameController framework at backends/imgui_impl_osx.mm512-632: GCController API

Gamepad mode settings (SDL2/SDL3):

• ImGui_ImplSDL3_GamepadMode_AutoFirst - Use first available gamepad
• ImGui_ImplSDL3_GamepadMode_AutoAll - Merge input from all gamepads
• ImGui_ImplSDL3_GamepadMode_Manual - User manages gamepad array

Sources: backends/imgui_impl_win32.cpp343-399 backends/imgui_impl_sdl3.cpp741-820 backends/imgui_impl_sdl3.h42-45

---

IME (Input Method Editor) Support

Platform backends that support IME provide cursor position feedback for text composition:

IME Implementation Examples

• SDL3 at backends/imgui_impl_sdl3.cpp174-212: Uses SDL_SetTextInputArea() and SDL_StartTextInput()
• Win32 at backends/imgui_impl_win32.cpp708-739: Uses ImmSetCompositionWindow() and handles WM_IME_* messages
• macOS at backends/imgui_impl_osx.mm140-156: Uses NSTextInputClient protocol with firstRectForCharacterRange

Sources: backends/imgui_impl_sdl3.cpp174-212 backends/imgui_impl_win32.cpp708-739 backends/imgui_impl_osx.mm116-244

---

Multi-Context Support

Some platform backends support multiple Dear ImGui contexts, though single context with multiple windows (docking branch) is recommended:

The GLFW backend maintains a window-to-context map at backends/imgui_impl_glfw.cpp181-189:

struct ImGui_ImplGlfw_WindowToContext { GLFWwindow* Window; ImGuiContext* Context; };
static ImVector<ImGui_ImplGlfw_WindowToContext> g_ContextMap;

When callbacks are invoked, the backend retrieves the correct context using the window handle.

Note: Multi-context support is not well tested in most backends. The preferred approach is using the docking branch with multiple viewports (single context, multiple windows).

Sources: backends/imgui_impl_glfw.cpp181-189 backends/imgui_impl_glfw.cpp235-253

---

Platform-Specific Features

DPI Awareness (Win32)

The Win32 backend provides DPI awareness helpers at backends/imgui_impl_win32.h44-46:

ImGui_ImplWin32_EnableDpiAwareness()        // Enable DPI awareness at startup
ImGui_ImplWin32_GetDpiScaleForHwnd(hwnd)    // Get DPI scale for window
ImGui_ImplWin32_GetDpiScaleForMonitor(mon)  // Get DPI scale for monitor

These functions dynamically load SetProcessDpiAwareness() and GetDpiForWindow() to support various Windows versions without manifest requirements.

Sources: backends/imgui_impl_win32.cpp927-1067

Content Scale (GLFW, SDL)

GLFW and SDL backends provide content scale helpers for high-DPI displays:

ImGui_ImplGlfw_GetContentScaleForWindow(window)
ImGui_ImplGlfw_GetContentScaleForMonitor(monitor)
ImGui_ImplSDL2_GetContentScaleForWindow(window)
ImGui_ImplSDL2_GetContentScaleForDisplay(display_index)

These return the ratio between framebuffer pixels and screen coordinates, allowing proper UI scaling on Retina/4K displays.

Sources: backends/imgui_impl_glfw.cpp1207-1243 backends/imgui_impl_sdl2.cpp1197-1261

Mouse Capture Mode (SDL2, SDL3)

SDL backends provide mouse capture mode control for X11 systems at backends/imgui_impl_sdl3.h47-52:

enum ImGui_ImplSDL3_MouseCaptureMode {
    ImGui_ImplSDL3_MouseCaptureMode_Enabled,
    ImGui_ImplSDL3_MouseCaptureMode_EnabledAfterDrag,  // X11 default
    ImGui_ImplSDL3_MouseCaptureMode_Disabled
};

This addresses X11 debugger issues where breaking with mouse capture active can prevent regaining mouse control.

Sources: backends/imgui_impl_sdl3.cpp519-532 backends/imgui_impl_sdl3.h47-52

Alpha Compositing (Win32)

The Win32 backend provides transparency support at backends/imgui_impl_win32.h51:

ImGui_ImplWin32_EnableAlphaCompositing(hwnd)

This enables alpha compositing with the desktop, allowing transparent windows when combined with framebuffer alpha.

Sources: backends/imgui_impl_win32.cpp1069-1088

---

Platform Handler Functions

Platform backends set function pointers in ImGuiPlatformIO during initialization:

These handlers are called by Dear ImGui core when needed:

Handler	Purpose	Example Implementation
Platform_GetClipboardTextFn	Read clipboard text	GLFW: glfwGetClipboardString()
Platform_SetClipboardTextFn	Write clipboard text	SDL3: SDL_SetClipboardText()
Platform_SetImeDataFn	Position IME window	Win32: ImmSetCompositionWindow()
Platform_OpenInShellFn	Open URL in browser	SDL3: SDL_OpenURL()

Sources: backends/imgui_impl_glfw.cpp689-691 backends/imgui_impl_sdl3.cpp534-538 backends/imgui_impl_win32.cpp161-213

---

Shutdown and Cleanup

Platform backends clean up resources during shutdown:

Cleanup Examples

• GLFW at backends/imgui_impl_glfw.cpp746-778: Destroys cursors, removes context map entry, restores callbacks if installed
• SDL3 at backends/imgui_impl_sdl3.cpp616-649: Closes gamepads, destroys cursors, frees clipboard data
• Win32 at backends/imgui_impl_win32.cpp226-244: Unloads XInput DLL, clears backend pointers

Sources: backends/imgui_impl_glfw.cpp746-778 backends/imgui_impl_sdl3.cpp616-649 backends/imgui_impl_win32.cpp226-244