ocornut · BrutPitt · Oct 31, 2025 · Oct 31, 2025 · Oct 31, 2025 · Oct 31, 2025
diff --git a/backends/imgui_impl_wgpu.cpp b/backends/imgui_impl_wgpu.cpp
@@ -51,6 +51,9 @@
 
 #ifndef IMGUI_DISABLE
 #include "imgui_impl_wgpu.h"
+#include <limits.h>
+#include <stdio.h>
+#include <webgpu/webgpu.h>
 
 // One of IMGUI_IMPL_WEBGPU_BACKEND_DAWN or IMGUI_IMPL_WEBGPU_BACKEND_WGPU must be provided. See imgui_impl_wgpu.h for more details.
 #if defined(IMGUI_IMPL_WEBGPU_BACKEND_DAWN) == defined(IMGUI_IMPL_WEBGPU_BACKEND_WGPU)
@@ -63,9 +66,6 @@
 #define IMGUI_IMPL_WEBGPU_BACKEND_WGPU_EMSCRIPTEN
 #endif
 
-#include <limits.h>
-#include <webgpu/webgpu.h>
-
 #ifdef IMGUI_IMPL_WEBGPU_BACKEND_DAWN
 // Dawn renamed WGPUProgrammableStageDescriptor to WGPUComputeState (see: https://github.com/webgpu-native/webgpu-headers/pull/413)
 // Using type alias until WGPU adopts the same naming convention (#8369)
@@ -273,7 +273,7 @@ static WGPUProgrammableStageDescriptor ImGui_ImplWGPU_CreateShaderModule(const c
 #endif
 
     WGPUShaderModuleDescriptor desc = {};
-    desc.nextInChain = reinterpret_cast<WGPUChainedStruct*>(&wgsl_desc);
+    desc.nextInChain = (WGPUChainedStruct*)&wgsl_desc;
 
     WGPUProgrammableStageDescriptor stage_desc = {};
     stage_desc.module = wgpuDeviceCreateShaderModule(bd->wgpuDevice, &desc);
@@ -915,6 +915,173 @@ void ImGui_ImplWGPU_NewFrame()
             IM_ASSERT(0 && "ImGui_ImplWGPU_CreateDeviceObjects() failed!");
 }
 
+//-------------------------------------------------------------------------
+// Internal Helpers
+// Those are currently used by our example applications.
+//-------------------------------------------------------------------------
+
+bool ImGui_ImplWGPU_IsSurfaceStatusError(WGPUSurfaceGetCurrentTextureStatus status)
+{
+#if defined(IMGUI_IMPL_WEBGPU_BACKEND_DAWN)
+    return (status == WGPUSurfaceGetCurrentTextureStatus_Error);
+#else
+    return (status == WGPUSurfaceGetCurrentTextureStatus_OutOfMemory || status == WGPUSurfaceGetCurrentTextureStatus_DeviceLost);
+#endif
+}
+
+bool ImGui_ImplWGPU_IsSurfaceStatusSubOptimal(WGPUSurfaceGetCurrentTextureStatus status)
+{
+#if defined(__EMSCRIPTEN__) && !defined(IMGUI_IMPL_WEBGPU_BACKEND_DAWN)
+    return (status == WGPUSurfaceGetCurrentTextureStatus_Timeout || status == WGPUSurfaceGetCurrentTextureStatus_Outdated || status == WGPUSurfaceGetCurrentTextureStatus_Lost);
+#else
+    return (status == WGPUSurfaceGetCurrentTextureStatus_Timeout || status == WGPUSurfaceGetCurrentTextureStatus_Outdated || status == WGPUSurfaceGetCurrentTextureStatus_Lost || status == WGPUSurfaceGetCurrentTextureStatus_SuccessSuboptimal);
+#endif
+}
+
+// Helpers to obtain a string
+#if defined(IMGUI_IMPL_WEBGPU_BACKEND_DAWN)
+const char* ImGui_ImplWGPU_GetErrorTypeName(WGPUErrorType type)
+{
+    switch (type)
+    {
+    case WGPUErrorType_Validation: return "Validation";
+    case WGPUErrorType_OutOfMemory: return "OutOfMemory";
+    case WGPUErrorType_Unknown: return "Unknown";
+    case WGPUErrorType_Internal: return "Internal";
+    default: return "Unknown";
+    }
+}
+const char* ImGui_ImplWGPU_GetDeviceLostReasonName(WGPUDeviceLostReason type)
+{
+    switch (type)
+    {
+    case WGPUDeviceLostReason_Unknown: return "Unknown";
+    case WGPUDeviceLostReason_Destroyed: return "Destroyed";
+    case WGPUDeviceLostReason_CallbackCancelled: return "CallbackCancelled";
+    case WGPUDeviceLostReason_FailedCreation: return "FailedCreation";
+    default: return "Unknown";
+    }
+}
+#elif !defined(__EMSCRIPTEN__)
+const char* ImGui_ImplWGPU_GetLogLevelName(WGPULogLevel level)
+{
+    switch (level)
+    {
+    case WGPULogLevel_Error: return "Error"; 
+    case WGPULogLevel_Warn: return "Warn";
+    case WGPULogLevel_Info: return "Info";
+    case WGPULogLevel_Debug: return "Debug";
+    case WGPULogLevel_Trace: return "Trace";
+    default: return "Unknown";
+    }
+}
+#endif
+
+const char* ImGui_ImplWGPU_GetBackendTypeName(WGPUBackendType type)
+{
+    switch (type)
+    {
+    case WGPUBackendType_WebGPU: return "WebGPU";
+    case WGPUBackendType_D3D11: return "D3D11";
+    case WGPUBackendType_D3D12: return "D3D12";
+    case WGPUBackendType_Metal: return "Metal";
+    case WGPUBackendType_Vulkan: return "Vulkan";
+    case WGPUBackendType_OpenGL: return "OpenGL";
+    case WGPUBackendType_OpenGLES: return "OpenGLES";
+    default: return "Unknown";
+    }
+}
+
+const char* ImGui_ImplWGPU_GetAdapterTypeName(WGPUAdapterType type)
+{
+    switch (type)
+    {
+    case WGPUAdapterType_DiscreteGPU: return "DiscreteGPU";
+    case WGPUAdapterType_IntegratedGPU: return "IntegratedGPU";
+    case WGPUAdapterType_CPU: return "CPU";
+    default: return "Unknown";
+    }
+}
+
+void ImGui_ImplWGPU_DebugPrintAdapterInfo(const WGPUAdapter& adapter)
+{
+    WGPUAdapterInfo info = {};
+    wgpuAdapterGetInfo(adapter, &info);
+    printf("description: \"%.*s\"\n", (int)info.description.length, info.description.data);
+    printf("vendor: \"%.*s\", vendorID: %x\n", (int)info.vendor.length, info.vendor.data, info.vendorID);
+    printf("architecture: \"%.*s\"\n", (int) info.architecture.length, info.architecture.data);
+    printf("device: \"%.*s\", deviceID: %x\n", (int)info.device.length, info.device.data, info.deviceID);
+    printf("backendType: \"%s\"\n", ImGui_ImplWGPU_GetBackendTypeName(info.backendType));
+    printf("adapterType: \"%s\"\n", ImGui_ImplWGPU_GetAdapterTypeName(info.adapterType));
+    wgpuAdapterInfoFreeMembers(info);
+}
+
+#if defined(IMGUI_IMPL_WEBGPU_BACKEND_WGPU) || defined(IMGUI_IMPL_WEBGPU_BACKEND_DAWN) && !defined(__EMSCRIPTEN__)
+
+#if defined(__APPLE__)
+// MacOS specific: is necessary to compile with "-x objective-c++" flags
+// (e.g. using cmake: set_source_files_properties(${IMGUI_DIR}/backends/imgui_impl_wgpu.cpp PROPERTIES COMPILE_FLAGS "-x objective-c++") )
+#include <Cocoa/Cocoa.h>
+#include <QuartzCore/CAMetalLayer.h>
+#endif
+
+WGPUSurface ImGui_ImplWGPU_CreateWGPUSurfaceHelper(ImGui_ImplWGPU_CreateSurfaceInfo* info)
+{
+    WGPUSurfaceDescriptor surface_descriptor = {};
+    WGPUSurface surface = {};
+#if defined(__APPLE__)
+    if (strcmp(info->System, "cocoa") == 0)
+    {
+        IM_ASSERT(info->RawWindow != nullptr);
+        NSWindow* ns_window = (NSWindow*)info->RawWindow;
+        id metal_layer = [CAMetalLayer layer];
+        [ns_window.contentView setWantsLayer : YES] ;
+        [ns_window.contentView setLayer : metal_layer] ;
+        WGPUSurfaceSourceMetalLayer surface_src_metal = {};
+        surface_src_metal.chain.sType = WGPUSType_SurfaceSourceMetalLayer;
+        surface_src_metal.layer = metal_layer;
+        surface_descriptor.nextInChain = &surface_src_metal.chain;
+        surface = wgpuInstanceCreateSurface(info->Instance, &surface_descriptor);
+    }
+#elif defined(__linux__) || defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__NetBSD__) || defined(__DragonFly__)
+    if (strcmp(info->System, "wayland") == 0)
+    {
+        IM_ASSERT(info->RawDisplay != nullptr && info->RawSurface != nullptr);
+        WGPUSurfaceSourceWaylandSurface surface_src_wayland = {};
+        surface_src_wayland.chain.sType = WGPUSType_SurfaceSourceWaylandSurface;
+        surface_src_wayland.display = info->RawDisplay;
+        surface_src_wayland.surface = info->RawSurface;
+        surface_descriptor.nextInChain = &surface_src_wayland.chain;
+        surface = wgpuInstanceCreateSurface(info->Instance, &surface_descriptor);
+    }
+    else if (strcmp(info->System, "x11") == 0)
+    {
+        IM_ASSERT(info->RawDisplay != nullptr && info->RawWindow != nullptr);
+        WGPUSurfaceSourceXlibWindow surface_src_xlib = {};
+        surface_src_xlib.chain.sType = WGPUSType_SurfaceSourceXlibWindow;
+        surface_src_xlib.display = info->RawDisplay;
+        surface_src_xlib.window = (uint64_t)info->RawWindow;
+        surface_descriptor.nextInChain = &surface_src_xlib.chain;
+        surface = wgpuInstanceCreateSurface(info->Instance, &surface_descriptor);
+    }
+#elif defined(_WIN32)
+    if (strcmp(info->System, "win32") == 0)
+    {
+        IM_ASSERT(info->RawWindow != nullptr && info->RawInstance != nullptr);
+        WGPUSurfaceSourceWindowsHWND surface_src_hwnd = {};
+        surface_src_hwnd.chain.sType = WGPUSType_SurfaceSourceWindowsHWND;
+        surface_src_hwnd.hinstance = info->RawInstance;
+        surface_src_hwnd.hwnd = info->RawWindow;
+        surface_descriptor.nextInChain = &surface_src_hwnd.chain;
+        surface = wgpuInstanceCreateSurface(info->Instance, &surface_descriptor);
+    }
+#else
+#error "Unsupported WebGPU native platform!"
+#endif
+    return surface;
+}
+#endif
+
 //-----------------------------------------------------------------------------
 
 #endif // #ifndef IMGUI_DISABLE
diff --git a/backends/imgui_impl_wgpu.h b/backends/imgui_impl_wgpu.h
@@ -41,6 +41,11 @@
 #endif
 
 #include <webgpu/webgpu.h>
+#if defined(IMGUI_IMPL_WEBGPU_BACKEND_DAWN)
+#include <webgpu/webgpu_cpp.h>  // for wgpu::Device, wgpu::DeviceLostReason, wgpu::ErrorType used by validation layer callbacks.
+#elif !defined(__EMSCRIPTEN__)
+#include <webgpu/wgpu.h>        // WGPULogLevel
+#endif
 
 // Initialization data, for ImGui_ImplWGPU_Init()
 struct ImGui_ImplWGPU_InitInfo
@@ -81,4 +86,38 @@ struct ImGui_ImplWGPU_RenderState
     WGPURenderPassEncoder       RenderPassEncoder;
 };
 
+//-------------------------------------------------------------------------
+// Internal Helpers
+// Those are currently used by our example applications.
+//-------------------------------------------------------------------------
+
+// (Optional) Helper to wrap some of the Dawn/WGPU/Emscripten quirks
+bool        ImGui_ImplWGPU_IsSurfaceStatusError(WGPUSurfaceGetCurrentTextureStatus status);
+bool        ImGui_ImplWGPU_IsSurfaceStatusSubOptimal(WGPUSurfaceGetCurrentTextureStatus status);    // Return whether the texture is suboptimal and may need to be recreated.
+
+// (Optional) Helper for debugging/logging
+void        ImGui_ImplWGPU_DebugPrintAdapterInfo(const WGPUAdapter& adapter);
+const char* ImGui_ImplWGPU_GetBackendTypeName(WGPUBackendType type);
+const char* ImGui_ImplWGPU_GetAdapterTypeName(WGPUAdapterType type);
+#if defined(IMGUI_IMPL_WEBGPU_BACKEND_DAWN)
+const char* ImGui_ImplWGPU_GetDeviceLostReasonName(WGPUDeviceLostReason type);
+const char* ImGui_ImplWGPU_GetErrorTypeName(WGPUErrorType type);
+#elif defined(IMGUI_IMPL_WEBGPU_BACKEND_WGPU) && !defined(__EMSCRIPTEN__)
+const char* ImGui_ImplWGPU_GetLogLevelName(WGPULogLevel level);
+#endif
+
+// (Optional) Helper to create a surface on macOS/Wayland/X11/Window
+#if defined(IMGUI_IMPL_WEBGPU_BACKEND_WGPU) || defined(IMGUI_IMPL_WEBGPU_BACKEND_DAWN) && !defined(__EMSCRIPTEN__)
+struct ImGui_ImplWGPU_CreateSurfaceInfo
+{
+    WGPUInstance    Instance;
+    const char*     System;      // "cocoa"   | "wayland"   | "x11"     | "win32"
+    void*           RawWindow;   // NSWindow* | 0           | Window    | HWND
+    void*           RawDisplay;  // 0         | wl_display* | Display*  | 0
+    void*           RawSurface;  //           | wl_surface* | 0         | 0
+    void*           RawInstance; // 0         | 0           | 0         | HINSTANCE
+};
+WGPUSurface ImGui_ImplWGPU_CreateWGPUSurfaceHelper(ImGui_ImplWGPU_CreateSurfaceInfo* info);
+#endif
+
 #endif // #ifndef IMGUI_DISABLE
diff --git a/docs/CHANGELOG.txt b/docs/CHANGELOG.txt
@@ -82,16 +82,28 @@ Other Changes:
     was unused in core but might be used by a direct caller). (#9027) [@achabense]
   - Vulkan: added IMGUI_IMPL_VULKAN_VOLK_FILENAME to configure path to
     Volk (default to "volk.h"). (#9008, #7722, #6582, #4854) [@mwlasiuk]
+  - WebGPU: added various internal/optional helpers to wrap some of the
+    Dawn/WGPU/Emscripten debacle quirks: (#8381) [@brutpitt]
+     - ImGui_ImplWGPU_CreateWGPUSurfaceHelper().
+     - ImGui_ImplWGPU_IsSurfaceStatusError(), ImGui_ImplWGPU_IsSurfaceStatusSubOptimal().
+     - ImGui_ImplWGPU_DebugPrintAdapterInfo(),
+     - ImGui_ImplWGPU_GetBackendTypeName(), ImGui_ImplWGPU_GetAdapterTypeName(),
+       ImGui_ImplWGPU_GetDeviceLostReasonName(), ImGui_ImplWGPU_GetErrorTypeName(),
+       ImGui_ImplWGPU_GetLogLevelName().
   - WebGPU: update to compile with Dawn and Emscripten's 4.0.10+
-    '--use-port=emdawnwebgpu' ports. (#8381, #8898) [@brutpitt, @trbabb]
+    '--use-port=emdawnwebgpu' ports. (#8381, #8898, #7435) [@brutpitt, @trbabb]
     When using Emscripten 4.0.10+, backend now defaults to IMGUI_IMPL_WEBGPU_BACKEND_DAWN
     instead of IMGUI_IMPL_WEBGPU_BACKEND_WGPU, if neither are specified.
     (note: examples application were not updated yet)
   - Win32: Revert 1.92.4 change of comparing dwPacketNumber, which prevents
     refreshing accurate gamepad info after focus-out + io.ClearInputKeys(). (#8556)
 - Examples:
+  - GLFW+WebGPU: update example for latest specs, to work on Emscripten 4.0.10+,
+    latest Dawn-Native and WGPU-Native. (#8381, #8567, #8191, #7435) [@brutpitt]
   - GLFW+WebGPU: removed unnecessary ImGui_ImplWGPU_InvalidateDeviceObjects() call
     during surface resize. (#8381)
+  - SDL2+WebGPU: added new example (Emscripten + native Dawn/WGPU). (#8381) [@brutpitt]
+  - SDL3+WebGPU: added new example (Emscripten + native Dawn/WGPU). (#8381) [@brutpitt]
 
 
 -----------------------------------------------------------------------