Backends: Vulkan: SwapChainImageUsage assume VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT which is added automatically. (#8946, #8110, #8111, #8686)

ocornut · ocornut · commit bad3c14ff6f6 · 2025-09-29T14:57:03.000+02:00
Amend e4e3c2c.
diff --git a/backends/imgui_impl_vulkan.cpp b/backends/imgui_impl_vulkan.cpp
@@ -1683,7 +1683,7 @@ void ImGui_ImplVulkanH_CreateWindowSwapChain(VkPhysicalDevice physical_device, V
         info.imageFormat = wd->SurfaceFormat.format;
         info.imageColorSpace = wd->SurfaceFormat.colorSpace;
         info.imageArrayLayers = 1;
-        info.imageUsage = (image_usage != 0) ? image_usage : VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
+        info.imageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT | image_usage;
         info.imageSharingMode = VK_SHARING_MODE_EXCLUSIVE;           // Assume that graphics family == present family
         info.preTransform = (cap.supportedTransforms & VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR) ? VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR : cap.currentTransform;
         info.compositeAlpha = VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR;
diff --git a/backends/imgui_impl_vulkan.h b/backends/imgui_impl_vulkan.h
@@ -78,7 +78,7 @@ struct ImGui_ImplVulkan_PipelineInfo
 #endif
 
     // For Secondary viewports only (created/managed by backend)
-    VkImageUsageFlags               SwapChainImageUsage;            // 0 defaults to VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT. Add e.g. VK_IMAGE_USAGE_TRANSFER_SRC_BIT if you need to capture from viewports.
+    VkImageUsageFlags               SwapChainImageUsage;            // Extra flags for vkCreateSwapchainKHR() calls for secondary viewports. We automatically add VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT. You can add e.g. VK_IMAGE_USAGE_TRANSFER_SRC_BIT if you need to capture from viewports.
 };
 
 // Initialization data, for ImGui_ImplVulkan_Init()
diff --git a/docs/CHANGELOG.txt b/docs/CHANGELOG.txt
@@ -56,10 +56,10 @@ Breaking Changes:
   (introduced very recently and only used by `ImGui_ImplVulkan_CreateMainPipeline()`
   so it should not affect many users). (#8110, #8111)
 - Backends: Vulkan: helper ImGui_ImplVulkanH_CreateOrResizeWindow() added a
-  `VkImageUsageFlags image_usage` argument.
-  It was previously hardcoded to `VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT` and defaults
-  to that when the value is 0. In theory the function is an internal helper but
-  since it's used by our examples some may have used it. (#8946, #8111, #8686)
+  `VkImageUsageFlags image_usage` argument to specific extra flags for calls to
+  vkCreateSwapchainKHR() done for secondary viewports. We automatically add
+  `VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT`. In theory the function is an internal
+  helper but since it's used by our examples some may have used it. (#8946, #8111, #8686)
 
 Other Changes:
 
diff --git a/examples/example_glfw_vulkan/main.cpp b/examples/example_glfw_vulkan/main.cpp
@@ -54,7 +54,6 @@ static VkDescriptorPool         g_DescriptorPool = VK_NULL_HANDLE;
 static ImGui_ImplVulkanH_Window g_MainWindowData;
 static uint32_t                 g_MinImageCount = 2;
 static bool                     g_SwapChainRebuild = false;
-static VkImageUsageFlags        g_SwapChainImageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
 
 static void glfw_error_callback(int error, const char* description)
 {
@@ -240,7 +239,7 @@ static void SetupVulkanWindow(ImGui_ImplVulkanH_Window* wd, VkSurfaceKHR surface
 
     // Create SwapChain, RenderPass, Framebuffer, etc.
     IM_ASSERT(g_MinImageCount >= 2);
-    ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, g_SwapChainImageUsage);
+    ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, 0);
 }
 
 static void CleanupVulkan()
@@ -470,7 +469,7 @@ int main(int, char**)
         if (fb_width > 0 && fb_height > 0 && (g_SwapChainRebuild || g_MainWindowData.Width != fb_width || g_MainWindowData.Height != fb_height))
         {
             ImGui_ImplVulkan_SetMinImageCount(g_MinImageCount);
-            ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, g_SwapChainImageUsage);
+            ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, 0);
             g_MainWindowData.FrameIndex = 0;
             g_SwapChainRebuild = false;
         }
diff --git a/examples/example_sdl2_vulkan/main.cpp b/examples/example_sdl2_vulkan/main.cpp
@@ -49,7 +49,6 @@ static VkDescriptorPool         g_DescriptorPool = VK_NULL_HANDLE;
 static ImGui_ImplVulkanH_Window g_MainWindowData;
 static uint32_t                 g_MinImageCount = 2;
 static bool                     g_SwapChainRebuild = false;
-static VkImageUsageFlags        g_SwapChainImageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
 
 static void check_vk_result(VkResult err)
 {
@@ -231,7 +230,7 @@ static void SetupVulkanWindow(ImGui_ImplVulkanH_Window* wd, VkSurfaceKHR surface
 
     // Create SwapChain, RenderPass, Framebuffer, etc.
     IM_ASSERT(g_MinImageCount >= 2);
-    ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, g_SwapChainImageUsage);
+    ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, 0);
 }
 
 static void CleanupVulkan()
@@ -490,7 +489,7 @@ int main(int, char**)
         if (fb_width > 0 && fb_height > 0 && (g_SwapChainRebuild || g_MainWindowData.Width != fb_width || g_MainWindowData.Height != fb_height))
         {
             ImGui_ImplVulkan_SetMinImageCount(g_MinImageCount);
-            ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, g_SwapChainImageUsage);
+            ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, 0);
             g_MainWindowData.FrameIndex = 0;
             g_SwapChainRebuild = false;
         }
diff --git a/examples/example_sdl3_vulkan/main.cpp b/examples/example_sdl3_vulkan/main.cpp
@@ -51,7 +51,6 @@ static VkDescriptorPool         g_DescriptorPool = VK_NULL_HANDLE;
 static ImGui_ImplVulkanH_Window g_MainWindowData;
 static uint32_t                 g_MinImageCount = 2;
 static bool                     g_SwapChainRebuild = false;
-static VkImageUsageFlags        g_SwapChainImageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
 
 static void check_vk_result(VkResult err)
 {
@@ -233,7 +232,7 @@ static void SetupVulkanWindow(ImGui_ImplVulkanH_Window* wd, VkSurfaceKHR surface
 
     // Create SwapChain, RenderPass, Framebuffer, etc.
     IM_ASSERT(g_MinImageCount >= 2);
-    ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, g_SwapChainImageUsage);
+    ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, 0);
 }
 
 static void CleanupVulkan()
@@ -492,7 +491,7 @@ int main(int, char**)
         if (fb_width > 0 && fb_height > 0 && (g_SwapChainRebuild || g_MainWindowData.Width != fb_width || g_MainWindowData.Height != fb_height))
         {
             ImGui_ImplVulkan_SetMinImageCount(g_MinImageCount);
-            ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_height, fb_height, g_MinImageCount, g_SwapChainImageUsage);
+            ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_height, fb_height, g_MinImageCount, 0);
             g_MainWindowData.FrameIndex = 0;
             g_SwapChainRebuild = false;
         }
diff --git a/examples/example_win32_vulkan/main.cpp b/examples/example_win32_vulkan/main.cpp
@@ -47,7 +47,6 @@ static VkDescriptorPool         g_DescriptorPool = VK_NULL_HANDLE;
 static ImGui_ImplVulkanH_Window g_MainWindowData;
 static uint32_t                 g_MinImageCount = 2;
 static bool                     g_SwapChainRebuild = false;
-static VkImageUsageFlags        g_SwapChainImageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
 
 static void check_vk_result(VkResult err)
 {
@@ -229,7 +228,7 @@ static void SetupVulkanWindow(ImGui_ImplVulkanH_Window* wd, VkSurfaceKHR surface
 
     // Create SwapChain, RenderPass, Framebuffer, etc.
     IM_ASSERT(g_MinImageCount >= 2);
-    ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, g_SwapChainImageUsage);
+    ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, 0);
 }
 
 static void CleanupVulkan()
@@ -583,7 +582,7 @@ LRESULT WINAPI WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam)
             if (fb_width > 0 && fb_height > 0 && (g_SwapChainRebuild || g_MainWindowData.Width != fb_width || g_MainWindowData.Height != fb_height))
             {
                 ImGui_ImplVulkan_SetMinImageCount(g_MinImageCount);
-                ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, &g_MainWindowData, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, g_SwapChainImageUsage);
+                ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, &g_MainWindowData, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, 0);
                 g_MainWindowData.FrameIndex = 0;
                 g_SwapChainRebuild = false;
             }

Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,6 @@ static VkDescriptorPool g_DescriptorPool = VK_NULL_HANDLE;`
`54`	`54`	`static ImGui_ImplVulkanH_Window g_MainWindowData;`
`55`	`55`	`static uint32_t g_MinImageCount = 2;`
`56`	`56`	`static bool g_SwapChainRebuild = false;`
`57`		`-static VkImageUsageFlags g_SwapChainImageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;`
`58`	`57`
`59`	`58`	`static void glfw_error_callback(int error, const char* description)`
`60`	`59`	`{`
`@@ -240,7 +239,7 @@ static void SetupVulkanWindow(ImGui_ImplVulkanH_Window* wd, VkSurfaceKHR surface`
`240`	`239`
`241`	`240`	`// Create SwapChain, RenderPass, Framebuffer, etc.`
`242`	`241`	`IM_ASSERT(g_MinImageCount >= 2);`
`243`		`- ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, g_SwapChainImageUsage);`
	`242`	`+ ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, 0);`
`244`	`243`	`}`
`245`	`244`
`246`	`245`	`static void CleanupVulkan()`
`@@ -470,7 +469,7 @@ int main(int, char**)`
`470`	`469`	`if (fb_width > 0 && fb_height > 0 && (g_SwapChainRebuild \|\| g_MainWindowData.Width != fb_width \|\| g_MainWindowData.Height != fb_height))`
`471`	`470`	`{`
`472`	`471`	`ImGui_ImplVulkan_SetMinImageCount(g_MinImageCount);`
`473`		`- ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, g_SwapChainImageUsage);`
	`472`	`+ ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, 0);`
`474`	`473`	`g_MainWindowData.FrameIndex = 0;`
`475`	`474`	`g_SwapChainRebuild = false;`
`476`	`475`	`}`
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,6 @@ static VkDescriptorPool g_DescriptorPool = VK_NULL_HANDLE;`
`49`	`49`	`static ImGui_ImplVulkanH_Window g_MainWindowData;`
`50`	`50`	`static uint32_t g_MinImageCount = 2;`
`51`	`51`	`static bool g_SwapChainRebuild = false;`
`52`		`-static VkImageUsageFlags g_SwapChainImageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;`
`53`	`52`
`54`	`53`	`static void check_vk_result(VkResult err)`
`55`	`54`	`{`
`@@ -231,7 +230,7 @@ static void SetupVulkanWindow(ImGui_ImplVulkanH_Window* wd, VkSurfaceKHR surface`
`231`	`230`
`232`	`231`	`// Create SwapChain, RenderPass, Framebuffer, etc.`
`233`	`232`	`IM_ASSERT(g_MinImageCount >= 2);`
`234`		`- ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, g_SwapChainImageUsage);`
	`233`	`+ ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, 0);`
`235`	`234`	`}`
`236`	`235`
`237`	`236`	`static void CleanupVulkan()`
`@@ -490,7 +489,7 @@ int main(int, char**)`
`490`	`489`	`if (fb_width > 0 && fb_height > 0 && (g_SwapChainRebuild \|\| g_MainWindowData.Width != fb_width \|\| g_MainWindowData.Height != fb_height))`
`491`	`490`	`{`
`492`	`491`	`ImGui_ImplVulkan_SetMinImageCount(g_MinImageCount);`
`493`		`- ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, g_SwapChainImageUsage);`
	`492`	`+ ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, 0);`
`494`	`493`	`g_MainWindowData.FrameIndex = 0;`
`495`	`494`	`g_SwapChainRebuild = false;`
`496`	`495`	`}`
Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,6 @@ static VkDescriptorPool g_DescriptorPool = VK_NULL_HANDLE;`
`51`	`51`	`static ImGui_ImplVulkanH_Window g_MainWindowData;`
`52`	`52`	`static uint32_t g_MinImageCount = 2;`
`53`	`53`	`static bool g_SwapChainRebuild = false;`
`54`		`-static VkImageUsageFlags g_SwapChainImageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;`
`55`	`54`
`56`	`55`	`static void check_vk_result(VkResult err)`
`57`	`56`	`{`
`@@ -233,7 +232,7 @@ static void SetupVulkanWindow(ImGui_ImplVulkanH_Window* wd, VkSurfaceKHR surface`
`233`	`232`
`234`	`233`	`// Create SwapChain, RenderPass, Framebuffer, etc.`
`235`	`234`	`IM_ASSERT(g_MinImageCount >= 2);`
`236`		`- ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, g_SwapChainImageUsage);`
	`235`	`+ ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, 0);`
`237`	`236`	`}`
`238`	`237`
`239`	`238`	`static void CleanupVulkan()`
`@@ -492,7 +491,7 @@ int main(int, char**)`
`492`	`491`	`if (fb_width > 0 && fb_height > 0 && (g_SwapChainRebuild \|\| g_MainWindowData.Width != fb_width \|\| g_MainWindowData.Height != fb_height))`
`493`	`492`	`{`
`494`	`493`	`ImGui_ImplVulkan_SetMinImageCount(g_MinImageCount);`
`495`		`- ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_height, fb_height, g_MinImageCount, g_SwapChainImageUsage);`
	`494`	`+ ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, fb_height, fb_height, g_MinImageCount, 0);`
`496`	`495`	`g_MainWindowData.FrameIndex = 0;`
`497`	`496`	`g_SwapChainRebuild = false;`
`498`	`497`	`}`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,6 @@ static VkDescriptorPool g_DescriptorPool = VK_NULL_HANDLE;`
`47`	`47`	`static ImGui_ImplVulkanH_Window g_MainWindowData;`
`48`	`48`	`static uint32_t g_MinImageCount = 2;`
`49`	`49`	`static bool g_SwapChainRebuild = false;`
`50`		`-static VkImageUsageFlags g_SwapChainImageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;`
`51`	`50`
`52`	`51`	`static void check_vk_result(VkResult err)`
`53`	`52`	`{`
`@@ -229,7 +228,7 @@ static void SetupVulkanWindow(ImGui_ImplVulkanH_Window* wd, VkSurfaceKHR surface`
`229`	`228`
`230`	`229`	`// Create SwapChain, RenderPass, Framebuffer, etc.`
`231`	`230`	`IM_ASSERT(g_MinImageCount >= 2);`
`232`		`- ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, g_SwapChainImageUsage);`
	`231`	`+ ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, wd, g_QueueFamily, g_Allocator, width, height, g_MinImageCount, 0);`
`233`	`232`	`}`
`234`	`233`
`235`	`234`	`static void CleanupVulkan()`
`@@ -583,7 +582,7 @@ LRESULT WINAPI WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam)`
`583`	`582`	`if (fb_width > 0 && fb_height > 0 && (g_SwapChainRebuild \|\| g_MainWindowData.Width != fb_width \|\| g_MainWindowData.Height != fb_height))`
`584`	`583`	`{`
`585`	`584`	`ImGui_ImplVulkan_SetMinImageCount(g_MinImageCount);`
`586`		`- ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, &g_MainWindowData, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, g_SwapChainImageUsage);`
	`585`	`+ ImGui_ImplVulkanH_CreateOrResizeWindow(g_Instance, g_PhysicalDevice, g_Device, &g_MainWindowData, g_QueueFamily, g_Allocator, fb_width, fb_height, g_MinImageCount, 0);`
`587`	`586`	`g_MainWindowData.FrameIndex = 0;`
`588`	`587`	`g_SwapChainRebuild = false;`
`589`	`588`	`}`