Custom Draw Commands

Relevant source files

• docs/CHANGELOG.txt
• imgui.cpp
• imgui.h
• imgui_demo.cpp
• imgui_draw.cpp
• imgui_internal.h
• imgui_tables.cpp
• imgui_widgets.cpp

Purpose and Scope

This page covers the custom draw command system in Dear ImGui, which allows you to inject custom rendering code into the ImGui draw stream using draw callbacks. This includes:

• Using ImDrawList::AddCallback() to insert custom rendering commands
• Accessing backend render state during callbacks
• Integrating ImGui rendering with existing rendering pipelines
• Advanced rendering techniques like custom clipping or shader changes

For information about the basic drawing API and primitives (rectangles, lines, text, etc.), see Draw System and Rendering Pipeline. For texture management, see Texture and Resource Management.

---

Overview

Custom draw commands allow you to execute arbitrary rendering code at specific points in the ImGui draw stream. This is accomplished through draw callbacks - function pointers stored in ImDrawCmd structures that backends invoke during rendering.

Key Concepts

Custom Draw Command Flow

Sources: imgui.h2677-2692 imgui_draw.cpp446-468 imgui_draw.cpp523-543 backends/imgui_impl_vulkan.cpp627-670

---

The ImDrawCmd Structure

Every rendering operation in ImGui is encoded as an ImDrawCmd structure. When you add a callback, you're inserting a special ImDrawCmd with a function pointer instead of regular draw data.

Field	Type	Purpose
UserCallback	ImDrawCallback	Function pointer for custom rendering (NULL for normal draws)
UserCallbackData	void*	User data passed to the callback
TexRef	ImTextureRef	Texture to use for this draw command
ClipRect	ImVec4	Clipping rectangle
VtxOffset	unsigned int	Start offset in vertex buffer
IdxOffset	unsigned int	Start offset in index buffer
ElemCount	unsigned int	Number of indices to draw

Sources: imgui.h2859-2889

---

Adding Draw Callbacks

Basic Usage

Use ImDrawList::AddCallback() to insert a callback into the draw stream:

The callback signature is:

Sources: imgui.h2677-2679 imgui_draw.cpp523-543

Callback Function Parameters

• parent_list: The ImDrawList that generated this command. Use this to access vertex/index buffers and state.
• cmd: The ImDrawCmd structure containing UserCallbackData and other context.

Sources: imgui.h2677-2679

---

Special Callback Values

ImGui defines two special callback values that are recognized by all standard backends:

ImDrawCallback_ResetRenderState

This special callback value ((ImDrawCallback)-1) instructs the backend to reset all render state to ImGui defaults. This is useful when your custom callback has modified render state and you want to ensure it's restored.

ImDrawCallback_ResizeDrawData

This is an internal callback value used by ImGui. User code should not use it.

Sources: imgui.h2681-2692 backends/imgui_impl_vulkan.cpp650-655 backends/imgui_impl_opengl3.cpp390-395

---

Accessing Backend Render State

Starting from version 1.92, backends expose selected render state through ImGuiPlatformIO::Renderer_RenderState. This allows callbacks to access backend-specific state like command buffers, render passes, and pipeline state.

Available Render State Structures

Each backend defines its own render state structure accessible through ImGuiPlatformIO::Renderer_RenderState:

Backend Render State Structures

Example: Accessing Vulkan Render State in Callback

Example: Accessing DirectX 11 Render State in Callback

Sources: backends/imgui_impl_vulkan.cpp127-136 backends/imgui_impl_dx11.cpp84-88 backends/imgui_impl_dx12.cpp123-131

---

Backend Implementation Details

How Backends Process Draw Commands

All renderer backends follow a similar pattern when processing ImDrawData:

Backend Draw Command Processing Sequence

Example: OpenGL3 Backend

The OpenGL3 backend processes callbacks in ImGui_ImplOpenGL3_RenderDrawData():

Example: Vulkan Backend

The Vulkan backend processes callbacks in ImGui_ImplVulkan_RenderDrawData():

Sources: backends/imgui_impl_opengl3.cpp377-450 backends/imgui_impl_vulkan.cpp627-700 backends/imgui_impl_dx11.cpp240-290 backends/imgui_impl_dx12.cpp370-440

---

Common Use Cases

Use Case 1: Custom Clipping

Modify the clipping rectangle for special rendering needs:

Use Case 2: Shader Changes

Switch shaders mid-stream for special effects:

Use Case 3: Integrating 3D Content

Render 3D content within an ImGui window:

Sources: imgui_demo.cpp9584-9650 (Custom Rendering section)

---

Interaction with Draw Channels

Draw callbacks interact with ImGui's channel splitting system (ImDrawListSplitter). When channels are used to reorder drawing (e.g., in tables or when manually splitting), callbacks are subject to the same channel ordering:

Draw Channels and Callback Ordering

Key Points:

• Callbacks in channel 0 execute before callbacks in channel 1
• ImDrawListSplitter::Merge() combines all channels in order
• Used internally by tables (ImGuiTable) to draw columns out of order
• Can be used manually via ImDrawList::ChannelsSplit() and ChannelsMerge()

Sources: imgui_internal.h1018-1044 imgui_draw.cpp1771-1873 imgui_tables.cpp1695-1780

---

Performance Considerations

Callback Overhead

• Each callback introduces a function call overhead
• Callbacks break batching - primitives before and after cannot be merged
• Minimize the number of callbacks in performance-critical paths

Best Practices

1. Batch state changes: Group multiple primitives that need the same custom state
2. Use callbacks sparingly: Only when absolutely necessary
3. Reset state properly: Always use ImDrawCallback_ResetRenderState or manually restore state
4. Avoid allocations: Callback execution is during the render loop - avoid dynamic allocations

Batching Example:

---

Implementation Architecture

AddCallback() Function Flow

ImDrawList::AddCallback() Internal Flow

AddCallback() Behavior:

1. Flush pending state changes: Calls _OnChangedClipRect() and _OnChangedTextureID() to ensure any pending primitives are finalized in a separate command
2. Remove empty commands: Calls PopUnusedDrawCmd() to remove the previous command if it has ElemCount == 0
3. Create new command: Pushes a new ImDrawCmd to CmdBuffer
4. Set callback fields:
   • UserCallback = your function pointer
   • UserCallbackData = your data pointer
   • ElemCount = 0 (no vertices/indices to draw)
5. Copy current state: Copies ClipRect, TexRef, and VtxOffset from current state

Sources: imgui_draw.cpp523-543 imgui_draw.cpp446-468

---

Limitations and Caveats

Backend Compatibility

Not all backends handle callbacks identically:

• Some backends may not expose render state
• Custom callbacks must be careful about backend-specific API usage
• Always test with your target backend

Thread Safety

• Callbacks are executed on the render thread
• The ImDrawList and ImDrawCmd are const during callback execution
• Do not modify ImGui state from callbacks (no ImGui::Text(), ImGui::Button(), etc.)

Clipping

• Callbacks must respect the ClipRect in ImDrawCmd
• Ignoring clipping will cause drawing outside window boundaries
• Use backend-specific scissor/viewport APIs to enforce clipping

Sources: imgui.h2681-2692 imgui_draw.cpp523-543

---

Demo Code References

The Dear ImGui demo includes examples of custom rendering:

Example: Custom Rendering Section

The demo window has a "Custom Rendering" section that demonstrates:

• Using GetWindowDrawList() and GetBackgroundDrawList()
• Drawing custom primitives
• Using draw callbacks for advanced effects

Located at imgui_demo.cpp9584-9650

Example: Canvas with Custom Clipping

The demo shows how to create a drawable canvas with custom clipping and mouse interaction.

Sources: imgui_demo.cpp9584-9650

---

Related Systems

• Draw System and Rendering Pipeline: Core rendering architecture
• Texture and Resource Management: Managing textures used in draw commands
• Backend System: How backends implement rendering

---

Summary

Custom draw commands via ImDrawList::AddCallback() provide a powerful mechanism to:

• Inject custom rendering code into the ImGui draw stream
• Access backend-specific render state during rendering
• Integrate ImGui rendering with existing rendering pipelines
• Implement advanced rendering techniques

Key points:

• Use callbacks sparingly due to performance overhead
• Always reset render state after custom rendering
• Access backend state through ImGuiPlatformIO::Renderer_RenderState
• Test thoroughly with your specific backend

Sources: imgui.h2677-2692 imgui_draw.cpp523-543 backends/imgui_impl_vulkan.cpp127-136 backends/imgui_impl_opengl3.cpp390-403