GPUDump Viewer Tool

DumpGPU is a platform-agnostic console command that dumps the intermediary rendering resource binaries of a captured frame to disk. The dump is stored with .json and .bin files that can then be browsed using a lightweight webpage viewer.

This command serves several purposes:

• It is available for all builds without the need to install a third party GPU debugging tool or restart the editor.
• Dumps can come from any supported platforms:
• Windows D3D11, D3D12, Vulkan
• Linux Vulkan
• Mac Metal, AGX
• PlayStation 4 and PlayStation 5
• XboxOne, Xbox Series X/S
• Nintendo Switch
• iOS and Android
• The interface is browsable from any platform that supports Chrome and a WebGL 2.0-capable GPU.
• Simple and platform-agnostic, which enables anyone to produce a GPU dump when encountering an artifact.
• Ideal for artists that run into unexpected and hard-to-reproduce problems while working in the editor.
• Minimizes frictions of browsing a resources binary.
• Platform GPU captures often require the correct SDK, and a dev kit to be able to analyze the resource. The GPUDump viewer enables developers to better triage bugs, but also to look at resources from any platforms with the required context of an issue.
• For graphics programmers writing new renderer functionality, this tool provides a faster iterative workflow for analyzing what may be happening.

Dumping Process

To initiate the process of creating a GPU dump of the frame, enter the command DumpGPU into the console window, or use the keyboard shortcut CTRL + Shift + /.

Once the command is initiated, it needs to copy the intermediary rendering resources to disk. To handle this, capture speed is traded for memory to limit out of memory failures from occurring. This ensures that the dump can reliably gather data of artifacts that are rare or difficult to reproduce without crashing a process that was able to reproduce it.

	GlobalDefinitions.Add("ALLOW_CONSOLE_IN_SHIPPING=1");
	GlobalDefinitions.Add("ALLOW_DUMPGPU_IN_SHIPPING=1");

Copy full snippet

Save Location of GPU Dumps

When a GPU dump is performed, it is stored in the project's root directory under the Saved/GPUDumps by default. On Desktop platforms, the file explorer will open a window to this dump location automatically on completion.

For Staged builds, they are saved in the Stage's Saved directory, with the path format: [Staged Directory] / [Platform Name] / [Project Name] / Saved / GPUDumps.

Mobile Platform Dump Save Location

For Mobile platforms, the GPU dumps are saved in the following locations:

Dump Settings

The GPU dumps created can be tailored to your needs with the following commands:

How the DumpGPU Command Copies the GPUDumpViewer

The GPUDumpViewer source code is available with the engine source and can be found in /Engine/Extras/GPUDumpViewer.

On non-Shipping builds, the GPUDumpViewer is automatically copied into the staging directory. Then, when the DumpGPU command is called to dump the frame, the files are copied from the staged directory to the dumping directory.

If you have a Shipping staged build, the GPUDumpViewer's HTML source may not be copied into the dumping directory because it is missing in the staged directory. In this case, you can copy your repository's //Engine/Extras/GPUDumpViewer application into your dumping directory to open the dump.

The GPU Dump Viewer

The GPU Dump Viewer is an HTML web-based application. From this viewer, you can access information about how the Unreal Engine renderer works.

To get started, once a GPU dump has occurred, the operating system will open the folder location of the saved dump. The viewer can be opened in Chrome by double-clicking the OpenGPUDumpViewer.bat file.

Once initiated, a new Chrome window will open with the GPUDumpViewer running.

GPUDumpViewer web application opens in a new Chrome Incognito window.

The GPUDumpViewer is a web application and functions similarly to any browser-based page or application. The following are some quick tips about working in the GPUDumpViewer:

• Any link is clickable and can be opened in its own tab for quick access.
• Navigation with the forward and back buttons will move between any previously viewed pages.
• If sharing a capture with someone, you can share the link after the # part to link them directly to a panel and part of the dump. For example, #display_output_resource(96,'0000000067e1bfa0.mip0');

1. Title Bar and Panels
2. Pass and Resource Tree
3. Viewer

Title Bar and Panels

The main title bar provides quick reference information about the name of the project, operating system, RHI, and build that was used when the dump was created. It also includes clickable information panels for general information about the project, console variables used, and a copy of the project's log.

Infos Panel

The Infos panel contains a summary of the GPU Dump. You'll find useful information about the system, drivers, and engine build, along with a screenshot of the final image from the back buffer.

CVars Panel

The CVars panel includes a searchable list of any rendering console variables — ones that begin with .r.* or .sg.*, or contain the RHI keyword — that were run before the dump occured.

Log Panel

The Log panel provides a copy of the project's log, which gets saved along with the dump once the dump is completed. This is where you can also inspect whether there has been any warning issued in the dumping process.

Viewers

The viewing area displays information about the different Passes, Textures, and Buffers when selected.

Pass Viewer

When clicking on a Pass in the draw event hierarchy, only the resources that the pass reads and modifies will be shown. It automatically opens up the first output resource, whether it's a texture or the buffer.

Next to the pass name (at the top of the viewer), you will find the Pass Parameters button.

Clicking this will display the raw pass parameters. More often than not, the pass parameters are shader parameters. For example, when FComputerShaderUtils::AddPass() or FPixelShaderUtils::AddPass() are used.

Pass Parameters enable you to verify that no instances of NaN from the CPU affects your shader through the shader parameters.

Texture Viewer

When a Texture is selected in the Pass view's Input Resources or Output Resources list, you can visualize its pixels in the viewer.

WebGL 2.0's canvas makes it possible to view textures by loading the raw resource binary (the RHI has copied into the dump's directory), and displaying it using a simpler WebGL pixel shader. For formats not supported by WebGL, such as 32 bit UINT textures, additional work behind the scenes is done to accurately simulate the pixel format.

The Texture Viewer includes several buttons along the top of the displayed texture:

• Set the size of the texture being displayed in the viewer or simply fit it to the window.

• Use Copy to clipboard to copy the currently displayed texture and relevant resource information to your clipboard. When you paste it into a text editor, or email, you should see something like this:

  
• There are three buttons to change the texture view mode: Visualization for standard texture view mode, or NaN (not a number) and Inf (infinity) viewing modes for identifying those types of pixel errors.

Hovering the mouse over the texture returns the current RGBA values of the cursor texel position. Left-clicking the mouse will capture and hold the texel RGBA position value.

For parts of the texture you want to examine more closely, you can use the mouse wheel to zoom in and out of the texture. When zoomed in, you can right-click and drag to move around the texture.

The area below the displayed texture provides key information about the texture and how it is being rendered.

1. Texture Descriptor
2. WebGL 2.0 visualization shader to customize
3. Passes that modify the resource
4. Passes that read the resource

Texture Descriptor

The Texture Descriptor displays information about the currently displayed texture. This is the one set up on FRDGBuilder::CreateTexture().

WebGL 2.0 Visualization Shader

The WebGL 2.0 Visualization Shader displays the code fragment that gets compiled to display the texture in the top window. Below it, the compilation log window displays any compilation errors that may occur.

The WebGL 2.0 canvas window is an editable text box that can be used to write any WebGL 2.0 GLSL. It can be customized to visualize and decode the texture, like when your image is compressing multiple bits of information per channel, or using a different color space. Any code typed in this field will automatically recompile and display any errors.

The syntax for WebGL 2.0 shaders differs from those that Unreal Engine uses with its Unreal Shader Format (.usf) and Unreal Shader Header (.ush) files used to write internal rendering code with HLSL. A link to the WebGL 2.0 quick reference card for GLSL syntax is linked at the bottom of the compilation window.

Passes being Modified and Read

At the very bottom are two windows, one for the Passes that are modifying the selected resource and Passes that are reading from the selected resource. In either Passes list, click on any Pass to display them in the viewer.

Buffer Viewer

Once a texture is selected for viewing in the Pass Input Resources or Output Resources lists, the Buffer view will list its descriptor and visualization contents.

The Buffer Descriptor lists general information about the selected resource, such as its name, size, description, usage, and more.

The Buffer Visualization lists addresses in the buffer with decimal or 0x prefix hexadecimal values.

Use the Address text field to jump to a specific address that is either decimal or with a 0x prefix.

The format of the list can be customized and supports the following:

• Float, Half
• Int, short, char
• Uint, ushort, char
• Hex(), or bin(), which displays any of the above formats in hexadecimal or binary.

Because the GPUDumpViewer doesn't know how the data should be interpreted, the buffer defaults to data visualization using the hex(uint) format unless it has the DrawIndirect usage flag, in which case the Uint format is used.