Vulkan Backend

Relevant source files

• backends/imgui_impl_dx10.cpp
• backends/imgui_impl_dx11.cpp
• backends/imgui_impl_dx12.cpp
• backends/imgui_impl_dx9.cpp
• backends/imgui_impl_metal.mm
• backends/imgui_impl_opengl2.cpp
• backends/imgui_impl_opengl3.cpp
• backends/imgui_impl_opengl3_loader.h
• backends/imgui_impl_vulkan.cpp
• backends/imgui_impl_vulkan.h
• backends/imgui_impl_wgpu.cpp
• examples/example_glfw_metal/main.mm
• examples/example_glut_opengl2/main.cpp
• examples/example_sdl2_vulkan/main.cpp
• examples/example_sdl3_vulkan/main.cpp
• examples/example_win32_opengl3/main.cpp
• examples/example_win32_vulkan/main.cpp

The Vulkan renderer backend translates Dear ImGui draw data into Vulkan command buffers. It is designed to work alongside a platform backend (e.g., GLFW, SDL, Win32) that handles windowing and input. For general backend architecture concepts, see Backend Architecture. For other renderer options, see Renderer Backends.

Architecture Overview

The Vulkan backend operates as a pure renderer, consuming ImDrawData produced by the Dear ImGui core and generating Vulkan commands. It manages its own vertex/index buffers, textures, descriptors, and pipeline state.

Diagram: Vulkan Backend Architecture

Sources: backends/imgui_impl_vulkan.h1-275 backends/imgui_impl_vulkan.cpp1-104

Key Data Structures

ImGui_ImplVulkan_InitInfo

Initialization structure passed to ImGui_ImplVulkan_Init(). Must be zero-cleared before use.

Field	Type	Description
ApiVersion	uint32_t	Vulkan API version (e.g., VK_API_VERSION_1_3)
Instance	VkInstance	Vulkan instance
PhysicalDevice	VkPhysicalDevice	Physical device
Device	VkDevice	Logical device
QueueFamily	uint32_t	Graphics queue family index
Queue	VkQueue	Graphics queue
DescriptorPool	VkDescriptorPool	Optional: descriptor pool for textures
DescriptorPoolSize	uint32_t	Optional: auto-create descriptor pool if > 0
MinImageCount	uint32_t	Minimum swapchain images (>= 2)
ImageCount	uint32_t	Actual swapchain images (>= MinImageCount)
PipelineInfoMain	ImGui_ImplVulkan_PipelineInfo	Pipeline configuration for main viewport
UseDynamicRendering	bool	Enable VK_KHR_dynamic_rendering
Allocator	const VkAllocationCallbacks*	Optional: allocation callbacks
CheckVkResultFn	void (*)(VkResult)	Optional: error handler
CustomShaderVertCreateInfo	VkShaderModuleCreateInfo	Optional: custom vertex shader
CustomShaderFragCreateInfo	VkShaderModuleCreateInfo	Optional: custom fragment shader

Sources: backends/imgui_impl_vulkan.h102-137

ImGui_ImplVulkan_Data

Internal backend state stored in io.BackendRendererUserData.

Diagram: Backend Data Structure Hierarchy

Sources: backends/imgui_impl_vulkan.cpp265-293 backends/imgui_impl_vulkan.cpp235-252

ImGui_ImplVulkan_Texture

Internal texture representation created by ImGui_ImplVulkan_UpdateTexture().

Field	Type	Description
Memory	VkDeviceMemory	Device memory for image
Image	VkImage	Vulkan image object
ImageView	VkImageView	Image view for sampling
DescriptorSet	VkDescriptorSet	Descriptor set for binding

Sources: backends/imgui_impl_vulkan.cpp254-262

Initialization and Lifecycle

Initialization Sequence

Diagram: Initialization Sequence

The initialization function performs the following:

1. Validate Parameters: Checks required fields in ImGui_ImplVulkan_InitInfo
2. Store Configuration: Deep-copies init info into backend data
3. Set Backend Capabilities:
   • ImGuiBackendFlags_RendererHasVtxOffset - Supports large meshes
   • ImGuiBackendFlags_RendererHasTextures - Supports dynamic texture updates
4. Create Descriptor Pool: If DescriptorPoolSize > 0, creates an internal pool
5. Create Pipeline: Calls ImGui_ImplVulkan_CreateDeviceObjects() if RenderPass or dynamic rendering is configured

Sources: backends/imgui_impl_vulkan.cpp883-1007 backends/imgui_impl_vulkan.cpp1009-1019

Device Object Creation

The ImGui_ImplVulkan_CreateDeviceObjects() function creates all Vulkan resources:

Diagram: Device Object Creation Flow

Sources: backends/imgui_impl_vulkan.cpp719-881

Shader Code

The backend embeds default SPIR-V shaders compiled from GLSL:

Vertex Shader (lines 302-361): Transforms vertices using push constants containing MVP matrix, passes through UV and color.

Fragment Shader (lines 366-402): Samples texture and multiplies by vertex color.

Custom shaders can be provided via CustomShaderVertCreateInfo and CustomShaderFragCreateInfo fields in ImGui_ImplVulkan_InitInfo.

Sources: backends/imgui_impl_vulkan.cpp299-402

Shutdown

Diagram: Shutdown Sequence

Sources: backends/imgui_impl_vulkan.cpp1021-1059

Frame Rendering

Render Flow

The ImGui_ImplVulkan_RenderDrawData() function is the heart of the backend, called each frame after ImGui::Render().

Diagram: Frame Rendering Flow

Sources: backends/imgui_impl_vulkan.cpp523-698

Render State Setup

The ImGui_ImplVulkan_SetupRenderState() function configures the pipeline state:

1. Bind Pipeline: Uses the main pipeline or custom pipeline passed to RenderDrawData()
2. Bind Vertex/Index Buffers: From per-frame render buffers
3. Set Viewport: Full framebuffer size
4. Push Constants: 2D orthographic projection matrix (4 floats: scale.x, scale.y, translate.x, translate.y)

Push constant layout:

struct {
    vec2 scale;      // 2.0f / DisplaySize
    vec2 translate;  // -1.0f - DisplayPos * scale
}

Sources: backends/imgui_impl_vulkan.cpp478-520

Frame Buffering

The backend uses a circular buffer of frame resources indexed by ImageCount:

Diagram: Frame Render Buffer Rotation

This ensures that buffers are not reused until the GPU has finished with them.

Sources: backends/imgui_impl_vulkan.cpp543-554

Texture Management

Texture Lifecycle

The backend supports dynamic texture updates through the ImGuiBackendFlags_RendererHasTextures flag.

Diagram: Texture State Machine

Sources: backends/imgui_impl_vulkan.cpp1199-1302

Texture Creation and Upload

The ImGui_ImplVulkan_UpdateTexture() function handles texture creation and updates:

Diagram: Texture Update Flow

The upload process uses a staging buffer and command buffer for GPU transfers. The backend maintains a persistent command pool and command buffer specifically for texture operations to avoid creating/destroying these resources frequently.

Sources: backends/imgui_impl_vulkan.cpp1199-1302

User Texture Binding

Applications can register custom textures using ImGui_ImplVulkan_AddTexture():

This function:

1. Allocates a VkDescriptorSet from the backend's descriptor pool
2. Updates the descriptor set with the provided sampler and image view
3. Returns the descriptor set handle, which can be cast to ImTextureID for use in ImGui::Image(), etc.

The descriptor set remains valid until explicitly removed with ImGui_ImplVulkan_RemoveTexture().

Sources: backends/imgui_impl_vulkan.cpp1304-1331 backends/imgui_impl_vulkan.cpp1333-1347

Pipeline Management

Pipeline Creation

The ImGui_ImplVulkan_CreateMainPipeline() function creates the graphics pipeline:

Diagram: Pipeline Creation Process

The pipeline is configured for Dear ImGui's specific rendering requirements:

• Vertex Format: 2D position, UV coordinates, RGBA color (20 bytes per vertex)
• Topology: Triangle list
• Culling: None (UI elements need back faces)
• Blending: Source alpha, one minus source alpha (preserves alpha in output)
• Dynamic State: Viewport and scissor (set per draw call)

Sources: backends/imgui_impl_vulkan.cpp1125-1197

Custom Shaders

Custom shaders can be provided in ImGui_ImplVulkan_InitInfo:

Custom shaders must:

• Accept the same vertex input layout (position, UV, color)
• Use the same push constant layout (4 floats)
• Sample from binding (set=0, binding=0) for the sampler and (set=0, binding=1) for the texture

Sources: backends/imgui_impl_vulkan.h132-136 backends/imgui_impl_vulkan.cpp769-786

Dynamic Rendering Support

When using VK_KHR_dynamic_rendering (Vulkan 1.3+), set:

The backend loads the appropriate function pointers (vkCmdBeginRenderingKHR or vkCmdBeginRendering) based on the API version.

Sources: backends/imgui_impl_vulkan.h89-92 backends/imgui_impl_vulkan.cpp228-231

Descriptor Management

Descriptor Pool Requirements

The backend requires a descriptor pool with:

• Type: VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
• Minimum count: IMGUI_IMPL_VULKAN_MINIMUM_IMAGE_SAMPLER_POOL_SIZE (8) per font atlas
• Additional count: One per ImGui_ImplVulkan_AddTexture() call
• Flag: VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT (for RemoveTexture support)

Alternatively, set DescriptorPoolSize to have the backend create a pool automatically:

Sources: backends/imgui_impl_vulkan.h81 backends/imgui_impl_vulkan.cpp902-934

Descriptor Set Layout

The backend creates a single descriptor set layout with two bindings:

Binding	Type	Stage	Description
0	VK_DESCRIPTOR_TYPE_SAMPLER	Fragment	Texture sampler
1	VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE	Fragment	Texture image

This layout allows flexible texture binding while using a shared sampler.

Sources: backends/imgui_impl_vulkan.cpp729-745

Helper Functions (ImGui_ImplVulkanH_*)

The backend provides helper functions prefixed with ImGui_ImplVulkanH_* used by example applications. These are not required for integration and are primarily for demonstration purposes.

Window Management Helpers

Diagram: Window Helper Functions

Key helper functions:

• ImGui_ImplVulkanH_CreateOrResizeWindow() - Creates or resizes swapchain and associated resources
• ImGui_ImplVulkanH_DestroyWindow() - Destroys window resources (but not VkSurfaceKHR, which is caller's responsibility)
• ImGui_ImplVulkanH_SelectPhysicalDevice() - Selects first suitable GPU
• ImGui_ImplVulkanH_SelectQueueFamilyIndex() - Finds graphics queue family
• ImGui_ImplVulkanH_GetMinImageCountFromPresentMode() - Gets minimum images for present mode

Sources: backends/imgui_impl_vulkan.cpp1475-1554 backends/imgui_impl_vulkan.cpp1556-1585

ImGui_ImplVulkanH_Window Structure

This structure encapsulates all per-window Vulkan resources for multi-window support.

Sources: backends/imgui_impl_vulkan.h228-268

Integration Example

A minimal integration (without platform backend for brevity):

For complete examples, see:

• example_sdl2_vulkan - SDL2 + Vulkan
• example_sdl3_vulkan - SDL3 + Vulkan
• example_glfw_vulkan - GLFW + Vulkan
• example_win32_vulkan - Win32 + Vulkan

Sources: examples/example_sdl2_vulkan/main.cpp1-386 examples/example_sdl3_vulkan/main.cpp1-386 examples/example_win32_vulkan/main.cpp1-422

Advanced Topics

Custom Function Loading

For custom Vulkan loaders (e.g., when using Volk):

Sources: backends/imgui_impl_vulkan.h44-51 backends/imgui_impl_vulkan.cpp1061-1123

Render State Access

During draw callbacks, render state is available through platform_io.Renderer_RenderState:

Sources: backends/imgui_impl_vulkan.h167-172 backends/imgui_impl_vulkan.cpp596-601

Memory Alignment

The backend handles Vulkan's nonCoherentAtomSize alignment requirement for mapped memory and BufferMemoryAlignment for buffer creation. These are automatically determined from device properties.

Sources: backends/imgui_impl_vulkan.cpp268-269 backends/imgui_impl_vulkan.cpp439-442

Pipeline Cache

The PipelineCache field in ImGui_ImplVulkan_InitInfo can be used to accelerate pipeline creation across application runs.

Sources: backends/imgui_impl_vulkan.h114