需链接wgpu-native C库并显式指定后端：Windows用wgpu_native.lib+DLL，Linux/macOS用.a/.so/.dylib；初始化时设backends非零值，检查wgpuCreateInstance返回值；Surface创建依赖正确原生句柄，configure须设format、usage、viewFormats等字段；每帧调wgpuSurfaceGetCurrentTexture与wgpuSurfaceTexturePresent；启用WGPUErrorCallback捕获GPU错误。
怎么链接 wgpu-native 库并初始化实例
不能直接用 C++ 调 wgpu 的 Rust API，wgpu-native 是官方提供的 C FFI 封装，所有函数都是 C 风格的。你得先编译它（或用预编译二进制），再按 C ABI 链接。
- Windows 下必须链接
wgpu_native.lib（不是 DLL），且运行时要确保wgpu_native.dll在 PATH 或可执行目录里；Linux/macOS 对应libwgpu_native.a+libwgpu_native.so/libwgpu_native.dylib -
wgpuInstanceDescriptor里backends字段不设默认值——如果留 0，某些平台（比如 macOS）会直接返回空实例；建议显式写WGPUBackendType_Vulkan | WGPUBackendType_Metal | WGPUBackendType_D3D12 - 调用
wgpuCreateInstance后务必检查返回值是否为nullptr，尤其在 CI 或无 GPU 环境下，它不会报错，只会静默失败
wgpuSurface 创建失败的常见原因
Surface 是连接窗口系统和 GPU 的关键一环，C++ 里没封装窗口抽象，全靠你传对原生句柄。错一个字段，wgpuInstanceCreateSurface 就返回 nullptr，还不报具体错误。
- Windows：传
HINSTANCE和HWND到WGPUSurfaceDescriptorFromWindowsHWND，注意HINSTANCE必须是主模块实例，不能是GetModuleHandle(nullptr)拿错；HWND必须已创建且未销毁 - Linux（X11）：
display和window字段不能为nullptr，且display必须是主线程创建的 XOpenDisplay 返回值；Wayland 下要用WGPUSurfaceDescriptorFromWaylandSurface，别混用 - macOS：
layer必须是非 nil 的CAMetalLayer*，且该 layer 已被加到NSView的图层树中——否则 Surface 创建成功但后续configure会崩溃
配置 wgpuSurfaceConfiguration 时容易漏掉的关键字段
Surface configure 不是“设个分辨率就完事”，它决定了整个渲染管线的数据流起点。少设一个非可选字段，wgpuSurfaceConfigure 就直接 abort。
C++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
-
format必须是wgpuSurfaceGetPreferredFormat返回的值之一，硬写WGPUTextureFormat_BGRA8Unorm在 macOS 上大概率失败（它偏爱WGPUTextureFormat_BGRA8UnormSrgb） -
usage至少包含WGPUTextureUsage_RenderAttachment，如果还要读回 CPU，得额外加WGPUTextureUsage_CopySrc，但注意这会让性能掉一截 -
viewFormatCount和viewFormats常被忽略——即使只用一种格式，也要把viewFormatCount = 1和viewFormats = &format设上，否则 Vulkan 后端可能拒绝配置
为什么 wgpuQueueSubmit 后画面没更新
提交命令队列本身不触发呈现，Surface 的帧需要显式 present。而且 WebGPU 的 present 是异步的，出错也不抛异常，只静默丢帧。
立即学习“C++免费学习笔记（深入）”；
- 每帧必须调一次
wgpuSurfaceGetCurrentTexture拿WGPUSurfaceTexture，检查status == WGPUSurfaceGetCurrentTextureStatus_Success；如果返回Outdated，说明 surface 被 resize 过，得重新configure -
wgpuQueueSubmit提交的是 command buffer，不是 texture；你得把 render pass encode 到 buffer 里，再 submit，最后调wgpuSurfaceTexturePresent——少任何一环，屏幕都黑着 - 调试时可在
wgpuQueueOnSubmittedWorkDone注册回调，打印日志确认提交是否真正完成；否则容易误以为卡在 GPU，其实是 CPU 根本没发过去
最麻烦的是 error callback 默认不开启，wgpuInstanceSetLogLevel 只控制日志级别，真要捕获 GPU 错误得自己实现 WGPUErrorCallback 并传给 wgpuInstanceRequestAdapter 和 wgpuDeviceCreateCommandEncoder 等——这点几乎没人提，但一旦 shader 写错或纹理尺寸越界，就只能靠猜。
