Dear ImGui SDL3 WebGPU 示例Dawn、WGPU-Native 与 Emscripten 三种构建路线完整指南【免费下载链接】imguiDear ImGui: Bloat-free Graphical User interface for C with minimal dependencies项目地址: https://gitcode.com/GitHub_Trending/im/imgui本文围绕 Dear ImGui 仓库中的 example_sdl3_wgpu 官方示例展开系统讲解其桌面端Google Dawn / WGPU-Native / WGVK与 Web 端Emscripten的完整构建流程、CMake 关键选项与 Makefile 编译方式并结合 CMakeLists.txt、Makefile.emscripten 和 main.cpp 的源码深入剖析后端宏选择、Surface 创建与每帧渲染管线的实现细节帮助读者掌握在三种 WebGPU 运行时之间切换构建 ImGui 图形界面的实操方案。一、示例定位与文件构成example_sdl3_wgpu是 Dear ImGui 官方示例之一组合了SDL3 平台后端与WebGPU 渲染后端用于演示如何在桌面或浏览器中通过 WebGPU 渲染 ImGui 界面。它包含 4 个核心文件文件职责main.cpp示例主程序SDL 窗口创建、WebGPU 设备/表面初始化、ImGui 主循环与每帧提交CMakeLists.txt统一构建脚本负责桌面Dawn/WGPU/WGVK与 Emscripten 两条路线的全部配置Makefile.emscripten不依赖 CMake 的 Emscripten 构建脚本产出web/index.html、web/index.js、web/index.wasm三件套README.md官方构建/运行说明本文主体参考文档从源码构成看该示例编译的核心源码为main.cpp、backends/imgui_impl_sdl3.cpp、backends/imgui_impl_wgpu.cpp以及五个核心库文件imgui.cpp、imgui_draw.cpp、imgui_demo.cpp、imgui_tables.cpp、imgui_widgets.cpp见 CMakeLists.txt。WebGPU 后端必须在编译期三选一IMGUI_IMPL_WEBGPU_BACKEND_DAWN、IMGUI_IMPL_WEBGPU_BACKEND_WGPU、IMGUI_IMPL_WEBGPU_BACKEND_WGVK。imgui_impl_wgpu.cpp 中有硬性校验一个都没定义则直接#error在 Emscripten 环境下定义 WGPU即旧版-sUSE_WEBGPU1同样触发#error因为 Emscripten 4.0.10 的旧方案已不再受支持。二、桌面端路线一CMake Google Dawn官方推荐官方文档给出的三步命令为# 1. 获取 Dawn 源码clone 到当前目录下的 dawn/ 文件夹 # 2. 生成构建系统通过 IMGUI_DAWN_DIR 指定 Dawn 目录 cmake -B build -DIMGUI_DAWN_DIRdawn # 3. 构建 cmake --build build产物位置为build/example_sdl3_wgpu[.exe]或build/Debug/example_sdl3_wgpu[.exe]。从 CMakeLists.txt 的源码可以确认几个关键前提CMake 3.22cmake_minimum_required(VERSION 3.22)注释明确说明是 Dawn 的要求C 标准为 C20set(CMAKE_CXX_STANDARD 20)同样是 Dawn 的要求未指定构建类型时默认 Debugif(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Debug ...)。当指定了IMGUI_DAWN_DIR时CMake 会先通过find_package(Dawn)尝试寻找已安装好的 Dawn若未找到则回退到add_subdirectory将 Dawn 作为子项目直接源码构建并预设了一组裁剪选项以加速编译见 CMakeLists.txtDAWN_USE_GLFWOFF禁用 Dawn 自带的 GLFW本示例使用 SDL3DAWN_BUILD_MONOLITHIC_LIBRARYSTATIC构建静态单库关闭DAWN_BUILD_SAMPLES、TINT_BUILD_CMD_TOOLS、TINT_BUILD_DOCS、TINT_BUILD_TESTS等无关组件Linux 下自动检测XDG_SESSION_TYPE若当前会话是 Wayland 则打开DAWN_USE_WAYLAND可用-DDAWN_USE_WAYLANDX覆盖。构建成功后 CMake 会打印Dawn Installation has been found!并最终链接webgpu_dawn目标。三、桌面端路线二CMake WGPU-Native 预编译模块如果不想从零编译 Dawn首次源码编译 Dawn 耗时较长可以改用 gfx-rs 提供的WGPU-Native自动生成的预编译二进制模块# 1. 下载 WGPU-Native 对应平台/编译器的预编译模块来自 gfx-rs/wgpu-native 的 Releases 页 # 2. 解压到自选目录 your_preferred_folder # 3. 生成路径支持绝对路径也支持相对当前目录的相对路径 cmake -B build -DIMGUI_WGPU_DIRyour_preferred_folder # 4. 构建 cmake --build build从 CMakeLists.txt 看IMGUI_WGPU_DIR路线会在${IMGUI_WGPU_DIR}/lib下用find_library查找libwgpu_native.a/wgpu_native.lib/wgpu_native之一REQUIRED找不到直接失败按平台追加系统库Windows 链接d3dcompiler ws2_32 userenv bcrypt ntdll opengl32 Propsys RuntimeObjectLinux 追加-lm -ldl定义IMGUI_IMPL_WEBGPU_BACKEND_WGPU并把${IMGUI_WGPU_DIR}/include加入头文件搜索路径CMakeLists.txt。源码中更新的第三条路线WGVK值得注意的一点是当前仓库的 CMakeLists.txt 头部注释中还收录了 README 尚未覆盖的第三条桌面路线——WGVK并且被标注为 “MUCH EASIER”更简单# 1. git clone WGVK 仓库到 wgvk/ 目录 # 2. cmake -B build -DIMGUI_WGVK_DIRwgvk # 3. cmake --build build从源码看WGVK 路线要求系统已安装 Vulkanfind_package(Vulkan REQUIRED)会把${IMGUI_WGVK_DIR}/src/wgvk.c直接编入示例目标定义IMGUI_IMPL_WEBGPU_BACKEND_WGVK并按平台注入SUPPORT_WIN32_SURFACE/SUPPORT_METAL_SURFACE/SUPPORT_WAYLAND_SURFACE/SUPPORT_XLIB_SURFACE宏CMakeLists.txt。这与 imgui_impl_wgpu.cpp 变更日志一致WGVK 后端于 2026-03-25 加入且支持在 WGSL 不可用时回退到 SPIR-V 着色器。三条路线互斥IMGUI_DAWN_DIR、IMGUI_WGPU_DIR、IMGUI_WGVK_DIR只能指定其一同时指定会触发FATAL_ERRORCMakeLists.txt。四、Web 端路线Emscripten 构建 WASMCMake 方式官方文档的步骤按 Emscripten 官方说明安装 Emscripten SDK安装 Ninja 构建系统emcmake cmake -G Ninja -B build可选追加-DIMGUI_EMSCRIPTEN_WEBGPU_FLAG--use-portpath/to/emdawnwebgpu_package/emdawnwebgpu.port.pycmake --build build。从 CMakeLists.txt 的源码实现看EMSCRIPTEN分支有几个硬性约束和默认值版本门槛EMSCRIPTEN_VERSION低于4.0.15直接FATAL_ERRORSDL3 的 Emscripten port 要求此最低版本README 中 “ems 4.0.10 才启用--use-portemdawnwebgpu” 的说明与此兼容——4.0.15 已满足 4.0.10 的前提默认 WebGPU flagIMGUI_EMSCRIPTEN_WEBGPU_FLAG缓存变量默认值为--use-portemdawnwebgpuEmscripten 4.0.10 引入的该 port 会把 Dawn 打进 WASM 运行时同时定义IMGUI_IMPL_WEBGPU_BACKEND_DAWN并附加-sDISABLE_EXCEPTION_CATCHING1 -DIMGUI_DISABLE_FILE_FUNCTIONS1。Emscripten 链接参数完整列表见 CMakeLists.txt关键项含义选项作用--use-portemdawnwebgpu使用 Dawn 作为 WebGPU 实现可用IMGUI_EMSCRIPTEN_WEBGPU_FLAG覆盖-sUSE_SDL3引入 Emscripten 的 SDL3 port-sWASM1产出真 WASM-sASYNCIFY1异步转换WebGPU 的 Promise 式 API 需要-sALLOW_MEMORY_GROWTH1允许堆增长-sNO_EXIT_RUNTIME0允许exit终止运行时-sASSERTIONS1开启断言便于调试--shell-file.../shell_minimal.html使用仓库自带的精简 HTML 壳 shell_minimal.htmlOUTPUT_NAME index最终产物为index.html配合.js/.wasm同步 Emscripten 到最新 DawnREADME 还说明若希望 Emscripten 构建使用最新版本的 Dawn需下载 Google 每日发布的port-emdawnwgpu-package来自 dawn 的 Releases解压后将步骤 3 替换为emcmake cmake -DIMGUI_EMSCRIPTEN_WEBGPU_FLAG--use-portpath/to/emdawnwebgpu_package/emdawnwebgpu.port.py -G Ninja -B build文档特别提示N.B.Emscripten 产出的 WASM 要正确工作还需要对应版本或更新的 Google Canary面向开发者的 nightly 构建浏览器内核以包含最新的 WebGPU 变更。外部 WebGPU 库方案IMGUI_EMSCRIPTEN_WEBGPU_FLAG指向本地 port同样要求 Emscripten 4.0.10 或该包声明的最低要求。逐步 CMake 命令速查对应 README 的 “CMake by step” 小节四种生成方式汇总如下场景命令效果Dawn 源码构建cmake -G Ninja -DIMGUI_DAWN_DIRpath_to_sdk_dir -B build_dir定义IMGUI_IMPL_WEBGPU_BACKEND_DAWNWGPU-Nativecmake -G Ninja -DIMGUI_WGPU_DIRpath_to_sdk_dir -B build_dir定义IMGUI_IMPL_WEBGPU_BACKEND_WGPUWGVK源码新增cmake -G Ninja -DIMGUI_WGVK_DIRpath_to_wgvk -B build_dir定义IMGUI_IMPL_WEBGPU_BACKEND_WGVKEmscriptenemcmake cmake -G Ninja -B build_dirEMS 4.0.10 自动用--use-portemdawnwebgpu更低版本直接中止旧-sUSE_WEBGPU1已不支持Emscripten 外部 WebGPU 包emcmake cmake -G Ninja -DIMGUI_EMSCRIPTEN_WEBGPU_FLAG--use-portpath_to_emdawnwebgpu_pkg -B build_dir定义IMGUI_IMPL_WEBGPU_BACKEND_DAWN生成之后的构建命令永远相同cmake --build build_dir # 由 CMake 调用生成阶段选定的构建器 # 或显式调用构建器 cd build_dir ninja常用 CMake 选项README “CMake useful options” 全量继承生成器类型-G——Ninja 之外的替代构建器-G Ninjaninja 构建器-G Unix Makefilesmake 构建器-G Visual Studio 17 2022 -A x64生成 VS 2022 解决方案仅 Windows仅原生构建且 Dawn 并非官方支持该方式构建。示例——用 make 替代 ninjacmake -G Unix Makefiles -DIMGUI_DAWN_DIRpath_to_sdk_dir -B where_to_build_dir注意语法大小写敏感生成器名含空格时必须加。目录SDK 路径可为绝对路径或相对当前目录的路径不同生成配置必须使用不同的where_to_build_dir。构建类型默认Debug可改为-DCMAKE_BUILD_TYPERelease -DCMAKE_BUILD_TYPEMinSizeRel -DCMAKE_BUILD_TYPERelWithDebInfo示例——构建 Releasecmake -G Ninja -DIMGUI_WGPU_DIRpath_to_sdk_dir -DCMAKE_BUILD_TYPERelease -B where_to_build_dirSDL3含 GLFW/SDL2依赖查找与包管理器头文件与库默认在系统/编译器路径环境变量中查找可直接把开发工具路径加入环境变量而无需修改CMakeLists.txt。例如 Clang 的搜索环境变量头文件CPATH、C_INCLUDE_PATH、CPLUS_INCLUDE_PATH库文件LIBRARY_PATH。使用 vcpkg / conan 等包管理器时追加-DCMAKE_TOOLCHAIN_FILEpath/to/package_manager.cmake以 vcpkg 为例的完整命令cmake -G Ninja -DIMGUI_DAWN_DIRpath_to_sdk_dir \ -DCMAKE_TOOLCHAIN_FILEvcpkg_root_dir/scripts/buildsystems/vcpkg.cmake \ -B where_to_build_dir对应 CMake 侧的查找逻辑是find_package(SDL3 REQUIRED CONFIG REQUIRED COMPONENTS SDL3)CMakeLists.txt头文件目录经target_include_directories注入示例目标。五、不用 CMakemake -f Makefile.emscriptenMakefile.emscripten 提供了一条纯 Emscripten 路径前提同样是已安装 Emscripten SDK 并加载其环境变量Windows 上可能需要先执行emsdk/emsdk_env.bat。在example_sdl3_wgpu/目录下执行make -f Makefile.emscripten会产出web/index.html、web/index.js、web/index.wasm三个文件三者缺一不可。该 Makefile 的关键变量与选项编译/链接均使用emcc/em编译告警级别-Wall -Wformat -OsEMS -s USE_SDL3 -s DISABLE_EXCEPTION_CATCHING1并同时附加--use-portemdawnwebgpu要求 Emscripten 4.0.10注释见 Makefile.emscripten链接期追加-s WASM1、-s ALLOW_MEMORY_GROWTH1、-s ASYNCIFY1、-s NO_EXIT_RUNTIME0、-s ASSERTIONS1并指定--shell-file ../libs/emscripten/shell_minimal.htmlUSE_FILE_SYSTEM ? 0开关默认 0 时追加-s NO_FILESYSTEM1并定义IMGUI_DISABLE_FILE_FUNCTIONS关闭文件访问置 1 时启用文件系统并把misc/fonts/以--preload-file ../../misc/fonts/fonts预加载进包内运行时从/fonts路径访问可选-sSINGLE_FILE被注释掉可将 WASM 二进制编码进单个 HTML内置serve目标python3 -m http.server -d webclean目标清理产物。六、运行产物与浏览器要求桌面原生构建直接运行build/example_sdl3_wgpu[.exe]或build/Debug/下同名文件即可弹出 SDL3 窗口展示 ImGui 演示界面。CMake 的 Emscripten 注释还建议用emrun build/index.html快速预览 Web 构建CMakeLists.txt。Web 构建README “How to Run” 全量要求浏览器必须支持并已启用 WebGPUWebGPU 仍是 WIP工作进行中API多数浏览器默认未开启make serve会用 Python3 起一个本地 webserver然后访问http://localhost:8000其他等价的本地服务器方式Emscripten 的emrun web/index.html --browser firefox起临时服务器并启动 FirefoxPython 3 内置python -m http.server -d web即make serve的实现原因引用自 Emscripten 文档Chrome、Safari 等浏览器不支持file://下的 XHR 请求无法加载 HTML 依赖的.wasm等附加文件必须通过本地 webserver 访问若通过网络而非本地访问Firefox 等浏览器会把 Gamepad API 限制在安全上下文如 https本示例启用了 Gamepad 支持见下文主循环。七、源码级解析初始化与每帧渲染管线WebGPU 实例、设备与 Surface 的获取main.cpp 的InitWGPU()是所有后端共用的初始化流程创建WGPUInstance并把TimedWaitAny列入requiredFeatures——这是后续用同步方式WaitAny等待 Future获取 Adapter/Device 的前提通过RequestAdapter/RequestDevice同步取得设备。Dawn 后端走 C 封装wgpu::InstanceWGPU/WGVK 后端走纯 C 回调风格WGPU-Native 还额外注册了wgpuSetLogCallback日志级别 Warn用于把 wgpu 内部日志转发到 stderr创建 Surface。桌面平台由 CreateWGPUSurface() 完成——由于 SDL3 目前尚无官方的 WebGPU Surface 接口该 stub 通过SDL_GetWindowProperties读取平台原生句柄Windows 取SDL_PROP_WINDOW_WIN32_HWND_POINTERmacOS 取 CocoaNSWindowLinux 区分 Waylandwl_displaywl_surface与 X11Display* window number再交给ImGui_ImplWGPU_CreateWGPUSurfaceHelper接口定义见 imgui_impl_wgpu.h。Emscripten 下则直接以 CSS 选择器#canvas描述 Surface 源用wgpuSurfaceGetCapabilities从 Surface 能力中取首选格式随后wgpuSurfaceConfigurepresentModeFifo、alphaModeAuto、usageRenderAttachment并取出WGPUQueue。ImGui WebGPU 后端初始化参数示例按 imgui_impl_wgpu.h 的ImGui_ImplWGPU_InitInfo结构初始化见 main.cpp字段示例取值说明Device上一步得到的wgpu_deviceWebGPU 设备NumFramesInFlight3三缓冲帧资源池顶点/索引缓冲轮转RenderTargetFormatSurface 首选格式渲染目标格式须与 Surface 配置一致DepthStencilFormatWGPUTextureFormat_Undefined本示例无深度模板附件PipelineMultisampleStatecount1mask 全 1多采样默认关闭头文件还声明了配套 APIImGui_ImplWGPU_NewFrame、ImGui_ImplWGPU_RenderDrawData(draw_data, pass_encoder)、ImGui_ImplWGPU_CreateDeviceObjects/InvalidateDeviceObjects设备重建而不丢 ImGui 状态、ImGui_ImplWGPU_UpdateTexture动态字体纹理的按需更新以及辅助函数ImGui_ImplWGPU_IsSurfaceStatusError/IsSurfaceStatusSubOptimal与调试工具ImGui_ImplWGPU_DebugPrintAdapterInfo初始化时即打印 Adapter 类型/后端类型。主循环中的 Surface 状态处理每帧开头示例先检查 Surface 纹理状态main.cppError 状态打印Unrecoverable Surface Texture status...后abort()——不可恢复SubOptimal 状态释放当前纹理、按当前窗口像素尺寸重新ResizeSurface配置 Surface 并continue跳过本帧——这是应对窗口缩放/显示器变化的标准处理也解释了为何ResizeSurface()同时更新wgpu_surface_configuration与记录宽度/高度。渲染提交链与缓冲增长策略每帧的渲染提交main.cpp顺序为ImGui::Render()生成ImDrawData→ 从wgpuSurfaceGetCurrentTexture取得的纹理创建WGPUTextureView→ 构造WGPURenderPassDescriptorloadOpClear、storeOpStore清屏色为clear_color预乘 alpha→wgpuDeviceCreateCommandEncoderBeginRenderPass→ImGui_ImplWGPU_RenderDrawData(draw_data, pass)→End→Finish得到命令缓冲 →wgpuQueueSubmit→ 原生平台再wgpuSurfacePresentDawn 后端最后调用wgpuDeviceTick注释说明这是 Dawn 显示验证错误的必要步骤Emscripten 下没有 present/tick。后端内部的ImGui_ImplWGPU_RenderDrawDataimgui_impl_wgpu.cpp实现细节包括先处理draw_data-Textures中的纹理更新动态字体图集支持对应RendererHasTextures能力帧资源按frameIndex % numFramesInFlight轮转当TotalVtxCount/TotalIdxCount超过现有容量时销毁旧缓冲并按“需求 5000 顶点 / 10000 索引”扩容重建所有 DrawList 的顶点/索引用memcpy拼接进单一连续缓冲经wgpuQueueWriteBuffer一次性上传大网格支持通过 16 位索引配合顶点偏移实现 64k 顶点渲染RendererHasVtxOffset能力见 imgui_impl_wgpu.h绘制回调支持DrawCallback_ResetRenderState/SetSamplerLinear/SetSamplerNearest渲染状态经platform_io.Renderer_RenderStateImGui_ImplWGPU_RenderState含 Device 与 RenderPassEncoder暴露给回调。Emscripten 专属行为差异main.cpp 在__EMSCRIPTEN__下把io.IniFilename置空禁用 ini 文件读写与IMGUI_DISABLE_FILE_FUNCTIONS呼应并用 emscripten_mainloop_stub.h 的EMSCRIPTEN_MAINLOOP_BEGIN/END把主循环包装为浏览器 rAF 驱动present/Tick段也被#ifndef __EMSCRIPTEN__排除。八、小结example_sdl3_wgpu演示了 Dear ImGui 接入 WebGPU 的完整工程形态桌面端可在 Dawn 源码构建、WGPU-Native 预编译模块、WGVK 三条路线中按构建成本与依赖偏好选择CMake 通过三个互斥的IMGUI_*_DIR变量切换并自动定义对应的IMGUI_IMPL_WEBGPU_BACKEND_*宏Web 端则以 Emscripten 4.0.15 配合--use-portemdawnwebgpu为准产出index.html/js/wasm三件套经本地 webserver 在支持 WebGPU 的浏览器中运行。理解CMakeLists.txt的分支逻辑、Makefile.emscripten的 Emscripten 选项组合以及main.cpp中 Surface 配置/重建与每帧提交链是复现与改造该示例的关键依据。【免费下载链接】imguiDear ImGui: Bloat-free Graphical User interface for C with minimal dependencies项目地址: https://gitcode.com/GitHub_Trending/im/imgui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考