RenderDoc Website: https://renderdoc.org/
Documentation https://renderdoc.org/docs/index.html
From inside renderdoc, find the "Launch Application tab"
Don't forget to save the settings.
Most of the following info comes from https://github.com/servo/webrender/wiki/Debugging-WebRender#renderdoc
To set the executable path and command-line argument fields, look at what's printed when towards the beginning of a ./mach run
invocation.
For me it looks like:
/home/nical/dev/mozilla/objdir/dbg/dist/bin/firefox
-no-remote -profile /home/nical/dev/mozilla/objdir/dbg/tmp/profile-default
Disable sandboxing via the following environment variables (Set from within RenderDoc):
MOZ_DISABLE_GPU_SANDBOX=1
MOZ_DISABLE_CONTENT_SANDBOX=1
On windows, tick "Capture Child Processes" in the "Launch application" tab.
Part of the difficulty of getting a WebRender workload captured is invalidation (we don't re-render content that hasn't changed since the previous frame). Setting the gfx.webrender.debug.force-picture-invalidation
pref helps there.
RenderDoc also allows capturing N consecutive frames which also helps a lot.
Sometimes Firefox is successfully launched from renderdoc but the connection closes (timeout) before you get a chance to capture a frame in renderdoc. If this happens, it is still possible to re-attach to the Firefox process by selecting File > Attach to running instance
in renderdoc.
Start firefox with the --wait-for-browser
command-line option. Otherwise the launcher process starts firefox and terminates right away which RenderDoc understands as the program terminating before anything interesting happened.
These prefs may also help:
gfx.webrender.enabled-no-gpu-process-with-angle-win
to true, andbrowser.launcherProcess.enabled
to false;gfx.webrender.compositor
to false. RenderDoc can't see frames when rendering to DirectComposition.Another way is to capture a trace and replay it in renderdoc via wrench
.
Set the pref gfx.webrender.debug.enable-capture
to true.
Multi-account containers have a keyboard shortcut which conflicts with the one used for WebRender captures. To disable the conflicting shortcut, go to about:addons
> click the gear icon > Manage Extension Shortcuts
and make sure that ctrl + shift + 3
is not used by the extension.
Note that WebRender captures contain most of WebRender's internal state. To ensure that the frame is re-rendered when replayed (rather than only compositing already-rendered picture cache tiles), delete the frame-*.ron
file in the recording's folder. Or hit one of the arrow keys to make wrench re-render the frame.
Renderdoc does not like wayland. Thankfully, renderdoc itself works under wayland, as long as the application being debugged uses x11. To do that for winit applications:
0.29.1
, set the WINIT_UNIX_BACKEND
env var to x11
.0.29.2
and later, set WAYLAND_DISPLAY
to an empty string.The event browser acts as a timeline of interactions with the API and drives what most of the other UI elements point at. I usually start by using the event browser in conjunction with the texture viewer tab to find the part of the frame I am interested in. Select various events in the event browser and see the render target updating with the result of each event.
In the texture viewer it can help to change the overlay (see the drop down menu towards the top). "Wireframe Mesh" is the overlay I use most. "Depth test" and "Stencil test" are sometimes very useful to understand why a particular draw call is not shown.
By default the texture viewer shows the render target, but you can focus on other textures like depth/stencil or inputs using the panel on the right. Sometimes it's useful to check that we are indeed sampling from the texture we expect.
If content is rendered upside-down, there is a green vertical double arrow button next to the overlay drop down menu that can be used to flip the y axis.
The mesh viewer is very useful when trying to understand what goes in and out of the vertex shader.
The tables show information for a single instance at a time. You can visit other instances using the control above the table.
In a lot of cases adding varyings and inspecting them in the mesh viewer is the moral equivalent of printf-debugging.
There is a lot of information in there. Is the render target configured incorrectly? Is it an issue with the cull mode, the depth function or scissor that's preventing content from being shown? You'll probably find out in the Rasterizer or FB (Framebuffer) sections of the pipeline state tab.
You can also see which shader is used at each stage (see the "View" and "Edit" buttons in the corresponding sections).
Does not work with OpenGL, but works with Vulkan and D3D.
When recording from a wrench trace on windows, pass --angle
to the wrench invocation so that D3D11 is used under the hood for shader debugging to work.
In the texture viewer, right-click on a pixel and click the "Debug" button on the bottom right of the UI.
In the mesh viewer, right-click a vertex in the table, then "Debug this vertex".
Not very precise so take results with more than a pinch of salt, but there is a little clock icon at the top of the event browser which re-runs the frame and measures the time spent in each draw call. I'd use it only as a very rough proxy.
If RenderDoc is started from the terminal, the application's stdout will be visible in the terminal that started renderdoc.
A different tool which, unlike RenderDoc, captures all frames, so it can be used in a few cases where RenderDoc is not a good fit.
Supports GL and D3D11 (but no modern API)
No Metal/RenderDoc for mac (at least not on m1 macs). But xcode's GPU debugging stuff is pretty good.
See https://github.com/gfx-rs/wgpu/wiki/Debugging-with-Xcode about how to set it up