-
Notifications
You must be signed in to change notification settings - Fork 959
Debugging wgpu Applications
This page describes all the tricks and tools aimed at investigating issues related to wgpu.
wgpu goal is to guarantee that only valid workloads reach the low-level APIs under the hood. If anything is not correct, we are going to complain about it. You should never need to listen to the low-level API complains.
This is a big work-in-progress, however. So in the meantime, it's useful to hear what the low-level validation has to say.
On Vulkan and OpenGL we redirect all the validation output to the console. You will see it as long as:
- you run a debug build
- you have the validation layers installed (i.e. LunarG SDK)
- you capture logging (with something like env_logger)
On D3D we are requesting a debug kind of device when running in debug builds. The output goes to the "Windows Debug Output". It can be intercepted with DeubgView, or you'll see it in the output window if you run the app directly from Visual Studio.
On Metal you can either set METAL_DEVICE_WRAPPER_TYPE=1 in the environment, or launch from XCode, where validation options are configurable in project menus (and enabled by default).
If the validation is clean, and you are getting incorrect rendering or computing, it's time to dive into GPU debugging. Many tools exist today:
- RenderDoc can be used on Windows and Linux to capture Vulkan, D3D, and OpenGL.
- XCode has powerful Metal GPU capture support with full shader debugging.
In order to run your application from XCode, you can create an empty project, select your executable binary, and provide the command line parameters in the project settings.
As wgpu is a Rust project, all the regular methods of debugging would work. It's convenient to launch an application from XCode (e.g. as an "External build system" type project), or Visual Studio (just go to "Open Project" and select the executable, adjust the path and parameters).
When looking at a crash/panic, first step is typically enabling RUST_BACKTRACE=1 in the environment. This will spew out the stack trace, which helps you to locate the problem.
Hop on to "#wgpu:matrix.org" and try to explain what happens and why. Maybe we listen. Maybe you'll figure out the answer by then ;)
There is a trace_path optional parameter in request_device. When it's set to an existing folder path, the device will be recording a trace of everything that's going on, to this folder. Once the trace is recorded, you can zip the folder and attach it to an issue. This should allow anyone, including the developers, to reproduce the issue on their machines, using the player:
cd player
cargo run --features winit -- <trace_folder_path>Read more at initial PR.