GLFW Backend

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

The GLFW Backend (imgui_impl_glfw.cpp/h) is a platform backend that integrates Dear ImGui with GLFW (Graphics Library Framework), a cross-platform library for handling windows, input events, and OpenGL/Vulkan context creation. This backend handles OS-level concerns such as window management, keyboard/mouse/gamepad input, and clipboard operations.

The GLFW backend must be paired with a renderer backend (e.g., OpenGL, Vulkan, Metal, WebGPU) to form a complete integration. For information about renderer backends, see Renderer Backends. For example applications using GLFW, see GLFW Examples.

Requirements: GLFW 3.0+ (GLFW 3.3+/3.4+ recommended for full feature support)

Sources: backends/imgui_impl_glfw.cpp1-5 backends/imgui_impl_glfw.h1-5

Implemented Features

Feature	Status	Notes
Clipboard support	✓	Full support
Mouse support	✓	Can discriminate Mouse/TouchScreen/Pen (Windows only)
Keyboard support	✓	Using io.AddKeyEvent() API with ImGuiKey values
Gamepad support	✓	Enable with io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad
Mouse cursor shape/visibility	✓	Requires GLFW 3.1+; resizing cursors require GLFW 3.4+
Multiple ImGui contexts	✓	Supported
Touch event discrimination	⚠	Only accurate on Windows
Wait/Progress cursors	✗	Not available in GLFW

Sources: backends/imgui_impl_glfw.cpp6-15 backends/imgui_impl_glfw.h6-15

Architecture Overview

GLFW Backend in the ImGui Integration Pattern

The GLFW backend sits between GLFW (the windowing/input library) and Dear ImGui core. It translates GLFW-specific input events and window state into ImGui's platform-agnostic input API (io.AddKeyEvent(), io.AddMouseButtonEvent(), etc.). The backend does not handle rendering; that responsibility belongs to a separate renderer backend.

Sources: backends/imgui_impl_glfw.cpp100-102 backends/imgui_impl_glfw.h25-37

Backend Data Structure

Backend State Management

The ImGui_ImplGlfw_Data structure maintains all backend-specific state. It is stored in io.BackendPlatformUserData and retrieved via ImGui_ImplGlfw_GetBackendData(). This design allows multiple Dear ImGui contexts to coexist (though this is not well-tested).

For multi-context support, the backend maintains a g_ContextMap vector that maps GLFWwindow* to ImGuiContext*, since GLFW provides only a single user pointer per window.

Sources: backends/imgui_impl_glfw.cpp199-233 backends/imgui_impl_glfw.cpp185-189 backends/imgui_impl_glfw.cpp243-253

Initialization and Lifecycle

Initialization Functions

The backend provides three initialization functions for different graphics APIs:

• ImGui_ImplGlfw_InitForOpenGL(GLFWwindow*, bool install_callbacks) - For OpenGL contexts
• ImGui_ImplGlfw_InitForVulkan(GLFWwindow*, bool install_callbacks) - For Vulkan
• ImGui_ImplGlfw_InitForOther(GLFWwindow*, bool install_callbacks) - For other renderers (Metal, WebGPU)

The install_callbacks parameter controls whether the backend automatically installs GLFW callbacks. When true, the backend chains user callbacks; when false, the application must forward events manually.

Sources: backends/imgui_impl_glfw.cpp1165-1201 backends/imgui_impl_glfw.h33-35

Input Event Processing

Key Translation

The backend translates GLFW key codes to ImGui key codes using ImGui_ImplGlfw_KeyToImGuiKey(). This function handles the full range of keys including:

• Standard alphanumeric keys (A-Z, 0-9)
• Function keys (F1-F24)
• Navigation keys (arrows, home, end, page up/down)
• Modifier keys (Ctrl, Shift, Alt, Super)
• Keypad keys
• Special keys (tab, enter, escape, etc.)

Additionally, ImGui_ImplGlfw_TranslateUntranslatedKey() handles GLFW's "untranslation" behavior, converting untranslated key codes back to their translated forms to support lettered shortcuts properly.

Sources: backends/imgui_impl_glfw.cpp275-402 backends/imgui_impl_glfw.cpp447-478 backends/imgui_impl_glfw.cpp480-497

Modifier Key Handling

Modifier keys are handled specially due to platform quirks. On X11, GLFW doesn't include the currently pressed/released modifier in the mods flags, so the backend directly queries key states via glfwGetKey() in ImGui_ImplGlfw_UpdateKeyModifiers().

Sources: backends/imgui_impl_glfw.cpp404-412

Mouse Input

Mouse events are processed through multiple callbacks:

• ImGui_ImplGlfw_CursorPosCallback() - Updates mouse position
• ImGui_ImplGlfw_MouseButtonCallback() - Handles button clicks
• ImGui_ImplGlfw_ScrollCallback() - Handles scroll wheel
• ImGui_ImplGlfw_CursorEnterCallback() - Tracks when cursor enters/leaves window

The backend handles a workaround for X11 spurious leave/enter events by backing up and restoring mouse position.

Sources: backends/imgui_impl_glfw.cpp419-429 backends/imgui_impl_glfw.cpp431-444 backends/imgui_impl_glfw.cpp509-540

Windows-Specific Touch/Pen Detection

On Windows, the backend installs a custom WndProc hook to distinguish mouse events from touch/pen input using GetMessageExtraInfo(). This information is passed to io.AddMouseSourceEvent().

Sources: backends/imgui_impl_glfw.cpp576-606

Callback Chaining Mechanism

Callback Installation

The backend can automatically install GLFW callbacks via ImGui_ImplGlfw_InstallCallbacks(), which:

1. Saves the user's previously installed callbacks in bd->PrevUserCallbackXXX fields
2. Installs ImGui's callbacks using glfwSetXXXCallback()
3. Sets bd->InstalledCallbacks = true

The backend's callbacks will chain-call the user's previous callbacks if:

• bd->CallbacksChainForAllWindows == true, OR
• The event is for bd->Window (the main window)

This chaining behavior can be controlled with ImGui_ImplGlfw_SetCallbacksChainForAllWindows().

Callbacks can be uninstalled via ImGui_ImplGlfw_RestoreCallbacks(), which restores the original user callbacks.

Sources: backends/imgui_impl_glfw.cpp608-623 backends/imgui_impl_glfw.cpp625-647 backends/imgui_impl_glfw.cpp414-417 backends/imgui_impl_glfw.cpp1255-1261

Manual Callback Forwarding

If install_callbacks=false during initialization, the application must manually forward GLFW events to the backend by calling:

• ImGui_ImplGlfw_WindowFocusCallback()
• ImGui_ImplGlfw_CursorEnterCallback()
• ImGui_ImplGlfw_CursorPosCallback()
• ImGui_ImplGlfw_MouseButtonCallback()
• ImGui_ImplGlfw_ScrollCallback()
• ImGui_ImplGlfw_KeyCallback()
• ImGui_ImplGlfw_CharCallback()
• ImGui_ImplGlfw_MonitorCallback()

Sources: backends/imgui_impl_glfw.h46-63

Frame Update Loop

ImGui_ImplGlfw_NewFrame() Responsibilities

This function is called once per frame before ImGui::NewFrame() and performs several critical updates:

1. Display Size: Queries window and framebuffer size to set io.DisplaySize and io.DisplayFramebufferScale
2. Delta Time: Calculates frame time using glfwGetTime()
3. Mouse Position: Updates mouse position for the focused window (fallback when not captured/hovered)
4. Mouse Cursor: Updates cursor shape and visibility based on ImGui::GetMouseCursor() and io.MouseDrawCursor
5. Gamepad State: Polls gamepad input via glfwGetGamepadState() (GLFW 3.3+)

Sources: backends/imgui_impl_glfw.cpp1284-1353

Platform-Specific Features

Wayland and X11 Detection

The backend detects whether it's running on Wayland or X11 at initialization time via ImGui_ImplGlfw_IsWayland(). This affects:

• Content scale reporting (always 1.0 on Wayland, always 1.0 for framebuffer on X11)
• Mouse cursor behavior

Sources: backends/imgui_impl_glfw.cpp256-272

DPI and Content Scale

Helper functions for DPI-aware applications:

• ImGui_ImplGlfw_GetContentScaleForWindow(GLFWwindow*) - Returns content scale for a window (uses glfwGetWindowContentScale())
• ImGui_ImplGlfw_GetContentScaleForMonitor(GLFWmonitor*) - Returns content scale for a monitor (uses glfwGetMonitorContentScale())

These functions return 1.0f on Emscripten, Android, and macOS (where scale is already baked into coordinates).

Sources: backends/imgui_impl_glfw.cpp1403-1445 backends/imgui_impl_glfw.h67-68

Emscripten/WebAssembly Support

For Emscripten, the backend provides:

• ImGui_ImplGlfw_InstallEmscriptenCallbacks() - Registers canvas selector and installs custom wheel event handler
• Custom wheel event handling via ImGui_ImplEmscripten_WheelCallback() to get accurate scroll values (GLFW's emulation is imprecise)

Two Emscripten GLFW implementations are supported:

1. Embedded GLFW 3.2.1 (syntax: -sUSE_GLFW=3) - Limited features, broken joystick
2. Contrib GLFW 3.4.0 (syntax: --use-port=contrib.glfw3) - Full-featured, fixes joystick

Sources: backends/imgui_impl_glfw.cpp25-28 backends/imgui_impl_glfw.cpp557-574 backends/imgui_impl_glfw.h40-43

Clipboard Integration

Clipboard operations are handled via ImGuiPlatformIO function pointers, set during initialization to use GLFW's clipboard functions:

• platform_io.Platform_GetClipboardTextFn → glfwGetClipboardString()
• platform_io.Platform_SetClipboardTextFn → glfwSetClipboardString()

Sources: backends/imgui_impl_glfw.cpp1217-1237

Sleep Helper

ImGui_ImplGlfw_Sleep(int milliseconds) is provided as a utility function since GLFW doesn't provide a sleep function. It uses platform-specific APIs (Sleep() on Windows, usleep() on Unix).

Sources: backends/imgui_impl_glfw.cpp1381-1401 backends/imgui_impl_glfw.h66

Multi-Context Support

Multi-Context Architecture

The backend supports multiple Dear ImGui contexts with multiple GLFW windows, though this is not well-tested and the docking branch with multi-viewports is strongly preferred.

Key mechanisms:

1. Context Mapping: g_ContextMap maps GLFWwindow* to ImGuiContext* since GLFW only provides one user pointer per window
2. Context Lookup: Callbacks use ImGui_ImplGlfw_ContextMap_Get(window) to find the correct context
3. Backend Data Retrieval: ImGui_ImplGlfw_GetBackendData(window) retrieves backend data for any window

Limitations:

• Shared resources (mouse cursor shape, gamepad) are not properly isolated between contexts
• Requires manual callback registration with install_callbacks=false and careful context switching

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

API Reference

Initialization and Shutdown

Function	Purpose
ImGui_ImplGlfw_InitForOpenGL(GLFWwindow*, bool)	Initialize for OpenGL renderer
ImGui_ImplGlfw_InitForVulkan(GLFWwindow*, bool)	Initialize for Vulkan renderer
ImGui_ImplGlfw_InitForOther(GLFWwindow*, bool)	Initialize for Metal/WebGPU/other renderers
ImGui_ImplGlfw_Shutdown()	Cleanup backend resources

The bool install_callbacks parameter determines whether to automatically install GLFW callbacks (recommended: true).

Sources: backends/imgui_impl_glfw.h33-36

Frame Management

Function	Purpose
ImGui_ImplGlfw_NewFrame()	Prepare for new frame (call before ImGui::NewFrame())

Sources: backends/imgui_impl_glfw.h37

Callback Management

Function	Purpose
ImGui_ImplGlfw_InstallCallbacks(GLFWwindow*)	Install GLFW callbacks and chain user callbacks
ImGui_ImplGlfw_RestoreCallbacks(GLFWwindow*)	Restore original user callbacks
ImGui_ImplGlfw_SetCallbacksChainForAllWindows(bool)	Control callback chaining for all windows vs main window only

Sources: backends/imgui_impl_glfw.h48-53

Individual Callbacks (for manual forwarding)

Function	GLFW Equivalent
ImGui_ImplGlfw_WindowFocusCallback()	glfwSetWindowFocusCallback()
ImGui_ImplGlfw_CursorEnterCallback()	glfwSetCursorEnterCallback()
ImGui_ImplGlfw_CursorPosCallback()	glfwSetCursorPosCallback()
ImGui_ImplGlfw_MouseButtonCallback()	glfwSetMouseButtonCallback()
ImGui_ImplGlfw_ScrollCallback()	glfwSetScrollCallback()
ImGui_ImplGlfw_KeyCallback()	glfwSetKeyCallback()
ImGui_ImplGlfw_CharCallback()	glfwSetCharCallback()
ImGui_ImplGlfw_MonitorCallback()	glfwSetMonitorCallback()

Sources: backends/imgui_impl_glfw.h56-63

Utility Functions

Function	Purpose
ImGui_ImplGlfw_Sleep(int milliseconds)	Cross-platform sleep utility
ImGui_ImplGlfw_GetContentScaleForWindow(GLFWwindow*)	Get window DPI scale
ImGui_ImplGlfw_GetContentScaleForMonitor(GLFWmonitor*)	Get monitor DPI scale

Sources: backends/imgui_impl_glfw.h66-68

Emscripten-Specific

Function	Purpose
ImGui_ImplGlfw_InstallEmscriptenCallbacks(GLFWwindow*, const char*)	Setup Emscripten canvas and install wheel handler

Sources: backends/imgui_impl_glfw.h41

Version Requirements and Feature Matrix

GLFW Version	Features Available
3.0	Basic support (minimum requirement as of 2025-11-06)
3.1+	Mouse cursor creation (glfwCreateCursor)
3.2+	glfwGetKeyName() for untranslated key handling
3.3+	Per-monitor DPI (glfwGetMonitorContentScale), Gamepad API (glfwGetGamepadState), Error handling (glfwGetError)
3.4+	Resizing cursors (NESW, NWSE, ALL), Platform detection (glfwGetPlatform)

Version detection macros:

• GLFW_HAS_CREATECURSOR - Cursor creation support
• GLFW_HAS_PER_MONITOR_DPI - DPI awareness
• GLFW_HAS_NEW_CURSORS - Resizing cursors
• GLFW_HAS_GAMEPAD_API - Gamepad support
• GLFW_HAS_GETKEYNAME - Key name retrieval
• GLFW_HAS_GETERROR - Error query
• GLFW_HAS_GETPLATFORM - Platform detection

Sources: backends/imgui_impl_glfw.cpp167-179