Custom Backend Development

Relevant source files

• backends/imgui_impl_allegro5.cpp
• backends/imgui_impl_android.cpp
• backends/imgui_impl_android.h
• backends/imgui_impl_dx10.cpp
• backends/imgui_impl_dx11.cpp
• backends/imgui_impl_dx12.cpp
• backends/imgui_impl_dx9.cpp
• backends/imgui_impl_glfw.cpp
• backends/imgui_impl_glfw.h
• backends/imgui_impl_glut.cpp
• backends/imgui_impl_glut.h
• backends/imgui_impl_metal.mm
• backends/imgui_impl_opengl2.cpp
• backends/imgui_impl_opengl3.cpp
• backends/imgui_impl_opengl3_loader.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_vulkan.cpp
• backends/imgui_impl_wgpu.cpp
• backends/imgui_impl_win32.cpp
• backends/imgui_impl_win32.h
• docs/BACKENDS.md
• docs/EXAMPLES.md
• examples/imgui_examples.sln

This page provides a guide for implementing custom platform and renderer backends for Dear ImGui. It covers the required and optional functions, data structures, and integration patterns needed to create backends for new platforms or rendering APIs not already supported by the standard backends.

Related pages: For an overview of the backend architecture and how backends work, see Backend Architecture Overview. For examples of existing platform backends, see Platform Backends. For examples of existing renderer backends, see Renderer Backends.

---

When to Write a Custom Backend

You need to write a custom backend when:

• Your platform/windowing library is not among the standard backends (GLFW, SDL2/3, Win32, OSX, etc.)
• Your rendering API is not among the standard backends (Vulkan, DirectX, OpenGL, Metal, WebGPU, etc.)
• You have a custom engine with proprietary windowing or rendering systems
• You need to integrate ImGui into a specialized environment (embedded systems, game consoles, etc.)

Important: Before writing a custom backend, check if your use case can be covered by existing backends. The standard backends in backends/ cover most common scenarios and are well-tested.

Sources: docs/BACKENDS.md12-16 docs/BACKENDS.md193-243

---

Backend Architecture Overview

Dear ImGui uses a two-backend architecture that separates platform concerns (input/windowing) from rendering concerns (GPU):

Backend Architecture: Function Call Flow

Platform Backend responsibilities:

• Implementing Init(), Shutdown(), NewFrame(), ProcessEvent() functions
• Storing platform state in ImGuiIO::BackendPlatformUserData
• Calling io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddKeyEvent(), etc.
• Setting io.DisplaySize, io.DeltaTime, io.DisplayFramebufferScale
• Setting ImGuiBackendFlags_HasMouseCursors, ImGuiBackendFlags_HasSetMousePos, ImGuiBackendFlags_HasGamepad

Renderer Backend responsibilities:

• Implementing Init(), Shutdown(), NewFrame(), RenderDrawData() functions
• Storing renderer state in ImGuiIO::BackendRendererUserData
• Creating GPU resources (shaders, pipelines, buffers)
• Rendering ImDrawData by iterating through CmdLists[] and issuing draw calls
• Setting ImGuiBackendFlags_RendererHasVtxOffset, ImGuiBackendFlags_RendererHasTextures

Sources: docs/BACKENDS.md25-42 backends/imgui_impl_glfw.cpp512-606 backends/imgui_impl_vulkan.cpp1146-1253

---

Backend Data Storage Pattern

All backends follow a consistent pattern for storing backend-specific data using the BackendPlatformUserData or BackendRendererUserData fields:

Example from GLFW backend:

This pattern allows:

• Multiple Dear ImGui contexts (advanced usage)
• Clean separation of backend state from core library
• Type-safe access to backend data

Sources: backends/imgui_impl_glfw.cpp188-236 backends/imgui_impl_vulkan.cpp398-404 backends/imgui_impl_opengl3.cpp259-264

---

Platform Backend Implementation

Required Functions

Every platform backend must implement four core functions:

Function	Purpose	Called By
ImGui_Impl[Platform]_Init()	Initialize backend, allocate resources	Application during startup
ImGui_Impl[Platform]_Shutdown()	Cleanup backend, free resources	Application during shutdown
ImGui_Impl[Platform]_NewFrame()	Update display size, time delta, input state	Application each frame before ImGui::NewFrame()
ImGui_Impl[Platform]_ProcessEvent()	Process platform events (optional but recommended)	Application event loop

Initialization Pattern:

Example from Win32 backend initialization:

The Win32 backend shows the typical initialization structure at backends/imgui_impl_win32.cpp159-211 Key steps:

1. Allocate backend data structure
2. Set io.BackendPlatformUserData
3. Set io.BackendPlatformName = "imgui_impl_win32"
4. Set backend capability flags (e.g., ImGuiBackendFlags_HasMouseCursors)
5. Initialize platform-specific resources (window handle, timing, XInput DLL)
6. Set viewport PlatformHandle for the main window

Sources: backends/imgui_impl_win32.cpp159-211 backends/imgui_impl_glfw.cpp512-581

Backend Capability Flags

Platform backends should set appropriate flags in io.BackendFlags during initialization:

Flag	Meaning	Set By	Requirements
ImGuiBackendFlags_HasMouseCursors	Backend can change mouse cursor shape	Platform	Call glfwCreateStandardCursor() or SDL_CreateSystemCursor() or LoadCursor()
ImGuiBackendFlags_HasSetMousePos	Backend can reposition mouse	Platform	Handle io.WantSetMousePos via glfwSetCursorPos() or SDL_WarpMouseInWindow()
ImGuiBackendFlags_HasGamepad	Backend provides gamepad input	Platform	Update io via io.AddKeyAnalogEvent() for gamepad axes/buttons

Example from Win32 backend initialization:

Example from GLFW backend initialization:

Sources: backends/imgui_impl_win32.cpp175-178 backends/imgui_impl_glfw.cpp542-551

Input Event Handling

Platform backends feed input to ImGui through the ImGuiIO API. The pattern is to process platform-specific events and translate them to ImGui events.

Input Event Translation: Platform Events to ImGuiIO API

Example: SDL3 Mouse Motion Event Processing

Example: GLFW Key Callback Translation

Complete ImGuiIO Input API:

Function	Purpose	Example
io.AddMousePosEvent(x, y)	Mouse position in window coordinates	io.AddMousePosEvent(event->motion.x, event->motion.y)
io.AddMouseButtonEvent(button, down)	Mouse button press/release (0-4)	io.AddMouseButtonEvent(0, action == GLFW_PRESS)
io.AddMouseWheelEvent(x, y)	Mouse wheel scroll delta	io.AddMouseWheelEvent(xoffset, yoffset)
io.AddMouseSourceEvent(source)	Discriminate Mouse/Touch/Pen	io.AddMouseSourceEvent(ImGuiMouseSource_TouchScreen)
io.AddKeyEvent(key, down)	Keyboard key press/release	io.AddKeyEvent(ImGuiKey_Space, true)
io.AddInputCharacter(c)	Unicode text input	io.AddInputCharacter(event->text.text[0])
io.AddFocusEvent(focused)	Window gained/lost focus	io.AddFocusEvent(event->type == SDL_EVENT_WINDOW_FOCUS_GAINED)
io.SetKeyEventNativeData(key, native_keycode, scancode)	Store native key data for legacy compatibility	io.SetKeyEventNativeData(key, keycode, scancode, scancode)

Sources: backends/imgui_impl_sdl3.cpp380-483 backends/imgui_impl_glfw.cpp419-486 backends/imgui_impl_win32.cpp595-841

NewFrame Implementation

NewFrame() must update timing and display information each frame:

Required updates:

1. Display size: io.DisplaySize = ImVec2(width, height)
2. Framebuffer scale: io.DisplayFramebufferScale = ImVec2(scale_x, scale_y) (for retina/high-DPI)
3. Delta time: io.DeltaTime = time_elapsed_since_last_frame
4. Mouse state updates if not using ProcessEvent pattern

Example from GLFW backend:

The GLFW backend's NewFrame at backends/imgui_impl_glfw.cpp866-925 shows:

1. Query window size and framebuffer size
2. Calculate display scale
3. Update time delta using high-resolution timer
4. Update mouse cursor if needed
5. Update gamepad input if enabled

Sources: backends/imgui_impl_glfw.cpp866-925 backends/imgui_impl_sdl3.cpp729-800 backends/imgui_impl_win32.cpp426-504

Shutdown Implementation

Shutdown() must clean up all resources allocated during Init():

Typical cleanup steps:

1. Retrieve backend data from io.BackendPlatformUserData
2. Release platform-specific resources (cursors, input context, etc.)
3. Clear io.BackendPlatformName and io.BackendPlatformUserData
4. Clear backend flags from io.BackendFlags
5. Call platform_io.ClearPlatformHandlers()
6. Free backend data structure

Example pattern:

Sources: backends/imgui_impl_glfw.cpp593-606 backends/imgui_impl_win32.cpp224-242 backends/imgui_impl_sdl3.cpp599-620

Optional Platform Features

Clipboard Support:

Implement clipboard by setting handlers in ImGuiPlatformIO:

Mouse Cursor Shape:

If supporting ImGuiBackendFlags_HasMouseCursors, update cursor in NewFrame():

• Read ImGui::GetMouseCursor() to get desired cursor
• Map to platform cursor shape
• Set platform cursor if changed

IME (Input Method Editor) Support:

For text input in CJK languages, implement IME callback:

The callback receives ImGuiPlatformImeData with input position and should show/hide the IME candidate window accordingly.

Sources: backends/imgui_impl_glfw.cpp554-562 backends/imgui_impl_sdl3.cpp169-207 backends/imgui_impl_win32.cpp860-894

---

Renderer Backend Implementation

Required Functions

Every renderer backend must implement four core functions:

Function	Purpose	Called By
ImGui_Impl[Renderer]_Init()	Initialize rendering resources (shaders, pipeline, etc.)	Application during startup
ImGui_Impl[Renderer]_Shutdown()	Cleanup rendering resources	Application during shutdown
ImGui_Impl[Renderer]_NewFrame()	Prepare for new frame (optional, used for per-frame setup)	Application each frame before ImGui::NewFrame()
ImGui_Impl[Renderer]_RenderDrawData(ImDrawData*)	Render ImGui draw commands to screen	Application after ImGui::Render()

Backend Capability Flags

Renderer backends should set appropriate flags in io.BackendFlags during initialization:

Flag	Meaning	Requirements
ImGuiBackendFlags_RendererHasVtxOffset	Supports large meshes (64k+ vertices) with 16-bit indices	Use ImDrawCmd::VtxOffset when rendering
ImGuiBackendFlags_RendererHasTextures	Supports dynamic texture creation/updates	Implement texture management functions

The RendererHasVtxOffset flag is critical for rendering large meshes efficiently. When set, ImGui can use 16-bit indices even for meshes with 64k+ vertices by using a vertex offset.

Sources: backends/imgui_impl_vulkan.cpp1197-1198 backends/imgui_impl_opengl3.cpp368-371

Initialization Pattern

Renderer backend initialization typically involves creating rendering pipeline state:

Example from Vulkan backend:

The Vulkan backend initialization at backends/imgui_impl_vulkan.cpp1146-1235 shows:

1. Allocate backend data
2. Store init parameters (device, queues, render pass, etc.)
3. Set backend name and flags
4. Create shader modules from embedded SPIR-V
5. Create descriptor set layouts
6. Create pipeline layout
7. Create graphics pipeline
8. Create texture sampler
9. Initialize texture management resources

Example from OpenGL3 backend:

The OpenGL3 backend initialization at backends/imgui_impl_opengl3.cpp306-418 shows:

1. Initialize OpenGL loader if needed
2. Query OpenGL version and capabilities
3. Store GLSL version string
4. Set backend flags based on GL version
5. Set max texture size in platform_io.Renderer_TextureMaxWidth/Height

Sources: backends/imgui_impl_vulkan.cpp1146-1235 backends/imgui_impl_opengl3.cpp306-418 backends/imgui_impl_dx12.cpp741-899

RenderDrawData Implementation

RenderDrawData() is the core rendering function that translates ImDrawData into graphics API commands. This is where most of the backend complexity lies.

ImDrawData Structure: Memory Layout and Key Fields

RenderDrawData Implementation Steps:

Key Implementation Details:

1. Framebuffer Size Calculation:

2. Projection Matrix Setup (Orthographic):

3. Clipping Rectangle Calculation:

4. Texture Binding: Always use pcmd->GetTexID() instead of pcmd->TextureId:

5. Drawing with VtxOffset:

Example: Vulkan RenderDrawData Structure

The Vulkan backend demonstrates the complete flow at backends/imgui_impl_vulkan.cpp523-676:

Example from OpenGL3 backend:

The OpenGL3 rendering at backends/imgui_impl_opengl3.cpp524-704 demonstrates:

1. Save current OpenGL state
2. Setup render state (blend, depth, scissors, viewport)
3. Compile shaders if not already done
4. Upload vertex/index data
5. Setup projection matrix
6. Iterate through draw commands
7. Restore previous OpenGL state

Sources: backends/imgui_impl_vulkan.cpp513-676 backends/imgui_impl_opengl3.cpp524-704 backends/imgui_impl_dx12.cpp241-457

Special Draw Callbacks

Some ImDrawCmd entries have special UserCallback values that must be handled:

Draw Callback Handling Logic

Example from Vulkan backend:

Example from OpenGL3 backend:

Callback Types:

Callback Value	Purpose	Handler Action
nullptr	Normal draw command	Execute scissor, bind texture, issue draw call
ImDrawCallback_ResetRenderState	Reset all render state	Call SetupRenderState() function to restore pipeline/viewport/etc.
Custom function pointer	User-defined callback	Execute pcmd->UserCallback(draw_list, pcmd)

Sources: backends/imgui_impl_vulkan.cpp608-626 backends/imgui_impl_opengl3.cpp657-677

Texture Management (RendererHasTextures)

Backends supporting ImGuiBackendFlags_RendererHasTextures must implement three handler functions for dynamic texture management.

Texture Lifecycle State Machine

Required Handler Functions:

Register these handlers during Init():

Required Handler Functions:

Register these handlers during Init():

1. Renderer_CreateTexture Handler:

Called when ImTextureData::Status == ImTextureStatus_WantCreate.

2. Renderer_UpdateTexture Handler:

Called when ImTextureData::Status == ImTextureStatus_WantUpdate.

3. Renderer_DestroyTexture Handler:

Called when ImTextureData::Status == ImTextureStatus_WantDestroy.

RenderDrawData Integration:

Process texture updates at the start of RenderDrawData():

This ensures all textures are created/updated before they're referenced in draw commands.

Key ImTextureData Fields:

Field	Type	Purpose
Status	ImTextureStatus	Current state (WantCreate/OK/WantUpdate/WantDestroy)
Width, Height	int	Texture dimensions in pixels
PixelsRGBA32	unsigned int*	RGBA32 pixel data (width * height * 4 bytes)
UpdateRegion	ImRect	Optional: Region to update (for partial updates)
RendererData	void*	Backend-specific texture data (e.g., ImGui_ImplVulkan_Texture*)
TextureID	ImTextureID	Texture identifier for ImDrawCmd::GetTexID() (e.g., VkDescriptorSet)

Sources: backends/imgui_impl_vulkan.cpp873-1064 backends/imgui_impl_opengl3.cpp766-927 backends/imgui_impl_dx12.cpp518-734

NewFrame Implementation (Optional)

Some renderer backends use NewFrame() for per-frame setup:

• Recreating device objects if they were destroyed
• Updating dynamic resources
• Preparing command buffers

Example from OpenGL3:

This ensures shaders are compiled on-demand if they were destroyed.

Sources: backends/imgui_impl_opengl3.cpp441-451

Shutdown Implementation

Shutdown() must release all rendering resources:

Typical cleanup steps:

1. Wait for GPU to finish (important!)
2. Destroy pipeline state objects
3. Destroy shaders
4. Destroy buffers
5. Destroy samplers
6. Release descriptor pools/heaps
7. Clear backend data and flags
8. Call platform_io.ClearRendererHandlers()

Example pattern:

Sources: backends/imgui_impl_vulkan.cpp1237-1253 backends/imgui_impl_opengl3.cpp421-439

---

Complete Lifecycle Example

Here's the complete sequence for integrating ImGui with custom backends:

Sources: Diagram 5 from high-level context, docs/EXAMPLES.md20-36

---

Best Practices and Guidelines

Multi-Context Support

To support multiple ImGui contexts (advanced usage):

1. Never use global variables for backend state
2. Store all state in the backend data structure
3. Retrieve context via ImGui::GetCurrentContext()
4. Check for null context in every backend function:

Note: Platform backends have additional complexity with multi-context support because platform events (like GLFW callbacks) are global and don't know which ImGui context they belong to. Consider using ImGuiContext mapping if supporting multiple windows.

Sources: backends/imgui_impl_glfw.cpp175-179 backends/imgui_impl_glfw.cpp226-232

State Management

Renderer State Isolation:

• Back up relevant graphics API state before rendering
• Restore state after rendering (optional but recommended)
• Users can disable restoration with ImGuiConfigFlags_DebugNoDefaultClipboard if they handle it themselves

Example from DirectX11: The DX11 backend backs up extensive state at backends/imgui_impl_dx11.cpp164-220 including:

• Rasterizer state, blend state, depth-stencil state
• Shader resources, samplers, shaders
• Vertex buffers, index buffers, topology
• Viewports, scissor rects

This ensures ImGui rendering doesn't corrupt the application's rendering state.

Sources: backends/imgui_impl_dx11.cpp164-220 backends/imgui_impl_opengl3.cpp524-579

Performance Considerations

1. Buffer Management:

   • Reuse vertex/index buffers across frames
   • Grow buffers when needed, don't shrink unnecessarily
   • Consider orphaning/mapping buffers efficiently

2. Minimize State Changes:

   • Batch similar commands together
   • Cache pipeline/shader state
   • Avoid redundant texture binds

3. Texture Updates:

   • Only update changed regions (use tex->UpdateRegion)
   • Use efficient upload methods (staging buffers, etc.)
   • Consider asynchronous uploads for large textures

Sources: backends/imgui_impl_vulkan.cpp434-466 backends/imgui_impl_dx12.cpp1183-1263

Error Handling

Always validate:

• Backend data pointer is not null
• Graphics API calls succeed
• Resources are created successfully
• Display size is valid (> 0) before rendering

Example pattern:

Sources: backends/imgui_impl_vulkan.cpp513-519 backends/imgui_impl_opengl3.cpp524-531

Backend Naming Conventions

Follow these conventions for consistency:

• File names: imgui_impl_[platform/renderer].cpp/h
• Function prefix: ImGui_Impl[Name]_
• Backend name: "imgui_impl_[name]" stored in io.BackendPlatformName or io.BackendRendererName
• Data struct: ImGui_Impl[Name]_Data
• Getter function: ImGui_Impl[Name]_GetBackendData()

Sources: backends/imgui_impl_glfw.cpp1-4 backends/imgui_impl_vulkan.cpp1-2

Documentation

Provide clear documentation in the header file:

• Implemented features section listing capabilities
• Required steps for integration
• Optional features and how to enable them
• Changelog for tracking API changes
• Links to Dear ImGui documentation

Example header template:

Sources: backends/imgui_impl_glfw.h1-16 backends/imgui_impl_vulkan.cpp1-27

---

Testing Your Backend

To verify your backend implementation:

1. Run imgui_demo.cpp: All widgets should display and respond correctly
2. Test input handling: Mouse, keyboard, gamepad should work
3. Test clipping: Nested windows should clip correctly
4. Test large meshes: Render windows with many vertices (>65k)
5. Test texture updates: Dynamic font atlas should update correctly
6. Test state restoration: Your app's rendering shouldn't be affected
7. Stress test: Many windows, high vertex counts, rapid updates

Use ImGui::ShowDemoWindow() as a comprehensive test case - it exercises all major features.

Sources: docs/EXAMPLES.md10 docs/BACKENDS.md21-23

---

Reference Material

Key files to study:

• backends/imgui_impl_glfw.cpp - Well-documented platform backend
• backends/imgui_impl_vulkan.cpp - Modern renderer backend with all features
• backends/imgui_impl_opengl3.cpp - Widely-used renderer backend
• docs/BACKENDS.md - Official backend documentation

ImGui core header references:

• imgui.h - Core API including ImGuiIO and input functions
• imgui_internal.h - Internal structures (not typically needed for backends)

Example applications:

• examples/ folder contains complete integration examples

Sources: docs/BACKENDS.md1-243 docs/EXAMPLES.md1-188