DumpGPU

DumpGPU

#Overview

name: DumpGPU

This variable is created as a Console Variable (cvar).

It is referenced in 12 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DumpGPU is to capture and save intermediary GPU resources for a single frame of rendering to disk for debugging and analysis purposes.

This setting variable is primarily used in the rendering system of Unreal Engine 5. It is referenced in several subsystems and modules, including:

  1. LevelEditor module
  2. UnrealEd module
  3. RenderCore module
  4. Core engine module

The value of this variable is set through a console command. In the Core module’s ConsoleManager.cpp, there’s a registration of the “DumpGPU” console command:

IConsoleManager::Get().RegisterConsoleCommand(TEXT("DumpGPU"), TEXT("Dump one frame of rendering intermediary resources to disk."), ECVF_Cheat);

DumpGPU interacts with other variables and systems, particularly:

  1. WITH_DUMPGPU macro, which controls whether the DumpGPU functionality is available.
  2. FRDGBuilder class, which is part of the Render Dependency Graph system.
  3. Various texture and resource handling systems in the rendering pipeline.

Developers must be aware of the following when using this variable:

  1. It’s only available in non-shipping builds by default, unless explicitly allowed in test or shipping builds.
  2. Using DumpGPU can have performance implications, as it involves writing potentially large amounts of data to disk.
  3. It’s primarily a debugging tool and should not be used in production environments.

Best practices when using this variable include:

  1. Use it sparingly and only when necessary for debugging rendering issues.
  2. Be aware of the performance impact when enabled.
  3. Ensure sufficient disk space is available when using this feature, as it can generate large amounts of data.
  4. Use in conjunction with other debugging tools and the GPU dump viewer for comprehensive analysis.
  5. Remember to disable it after debugging to avoid unnecessary performance overhead.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Editor/LevelEditor/Private/LevelEditor.cpp:1736

Scope (from outer to inner):

file
function     void FLevelEditorModule::BindGlobalLevelEditorCommands

Source code excerpt:

	
	ActionList.MapAction(
		Commands.DumpGPU,
		FExecuteAction::CreateStatic( &FLevelEditorActionCallbacks::ExecuteExecCommand, FString( TEXT("DUMPGPU") ) )
		);

	ActionList.MapAction(
		Commands.ResetAllParticleSystems,
		FExecuteAction::CreateStatic( &FLevelEditorActionCallbacks::ExecuteExecCommand, FString( TEXT("PARTICLE RESET ALL") ) )

#Loc: <Workspace>/Engine/Source/Editor/LevelEditor/Private/LevelEditorActions.cpp:3931

Scope (from outer to inner):

file
function     UE_DISABLE_OPTIMIZATION_SHIP void FLevelEditorCommands::RegisterCommands

Source code excerpt:

	UI_COMMAND( RecompileShaders, "Recompile Changed Shaders", "Recompiles shaders which are out of date", EUserInterfaceActionType::Button, FInputChord( EModifierKey::Shift|EModifierKey::Control, EKeys::Period ) );
	UI_COMMAND( ProfileGPU, "Profile GPU", "Profiles the GPU for the next frame and opens a window with profiled data", EUserInterfaceActionType::Button, FInputChord( EModifierKey::Shift|EModifierKey::Control, EKeys::Comma ) );
	UI_COMMAND( DumpGPU, "Dump GPU", "Dump the GPU intermediary resources for the next frame and opens explorer", EUserInterfaceActionType::Button, FInputChord( EModifierKey::Shift|EModifierKey::Control, EKeys::Slash ) );

	UI_COMMAND( ResetAllParticleSystems, "Reset All Particle Systems", "Resets all particle system emitters (removes all active particles and restarts them)", EUserInterfaceActionType::Button, FInputChord( EModifierKey::Shift, EKeys::Slash ) );
	UI_COMMAND( ResetSelectedParticleSystem, "Resets Selected Particle Systems" , "Resets selected particle system emitters (removes all active particles and restarts them)", EUserInterfaceActionType::Button, FInputChord( EKeys::Slash ) );

	UI_COMMAND( SelectActorsInLayers, "Select all actors in selected actor's layers", "Selects all actors belonging to the layers of the currently selected actors", EUserInterfaceActionType::Button, FInputChord( EModifierKey::Control, EKeys::L ) );

#Loc: <Workspace>/Engine/Source/Editor/LevelEditor/Public/LevelEditorActions.h:623

Scope (from outer to inner):

file
class        class FLevelEditorCommands : public TCommands<FLevelEditorCommands>

Source code excerpt:

	TSharedPtr< FUICommandInfo > RecompileShaders;
	TSharedPtr< FUICommandInfo > ProfileGPU;
	TSharedPtr< FUICommandInfo > DumpGPU;

	TSharedPtr< FUICommandInfo > ResetAllParticleSystems;
	TSharedPtr< FUICommandInfo > ResetSelectedParticleSystem;
	TSharedPtr< FUICommandInfo > SelectActorsInLayers;

        // Open merge actor command

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/SEditorViewport.cpp:605

Scope (from outer to inner):

file
function     bool SEditorViewport::IsVisible

Source code excerpt:

	const float VisibilityTimeThreshold = .25f;
	// The viewport is visible if we don't have a parent layout (likely a floating window) or this viewport is visible in the parent layout.
	// Also, always render the viewport if DumpGPU is active, regardless of tick time threshold -- otherwise these don't show up due to lag
	// caused by the GPU dump being triggered.
	return 
		LastTickTime == 0.0	||	// Never been ticked
		FPlatformTime::Seconds() - LastTickTime <= VisibilityTimeThreshold	// Ticked recently
#if WITH_DUMPGPU
		|| FRDGBuilder::IsDumpingFrame()	// GPU dump in progress

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/HAL/ConsoleManager.cpp:3364

Scope (from outer to inner):

file
function     void CreateConsoleVariables

Source code excerpt:


#if WITH_DUMPGPU
	IConsoleManager::Get().RegisterConsoleCommand(TEXT("DumpGPU"), TEXT("Dump one frame of rendering intermediary resources to disk."), ECVF_Cheat);
#endif

#if WITH_GPUDEBUGCRASH
	IConsoleManager::Get().RegisterConsoleCommand(TEXT("GPUDebugCrash"), TEXT("Crash GPU intentionally for debugging."), ECVF_Cheat);
#endif

#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/Misc/Build.h:395

Scope: file

Source code excerpt:

#endif

// DumpGPU command
#define WITH_DUMPGPU (!(UE_BUILD_SHIPPING || UE_BUILD_TEST) || (UE_BUILD_TEST && ALLOW_DUMPGPU_IN_TEST) || (UE_BUILD_SHIPPING && ALLOW_DUMPGPU_IN_SHIPPING))

#ifndef ALLOW_GPUDEBUGCRASH_IN_TEST
#define ALLOW_GPUDEBUGCRASH_IN_TEST 1
#endif

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/LaunchEngineLoop.cpp:6194

Scope: file

Source code excerpt:

#endif

		// Tick DumpGPU to start/stop frame dumps
		#if WITH_ENGINE && WITH_DUMPGPU
			UE::RenderCore::DumpGPU::TickEndFrame();
		#endif

		#if !UE_SERVER && WITH_ENGINE
		{

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:382

Scope (from outer to inner):

file
function     IDumpGPUUploadServiceProvider::FDumpParameters GetDumpParameters

Source code excerpt:

	{
		IDumpGPUUploadServiceProvider::FDumpParameters DumpServiceParameters;
		DumpServiceParameters.Type = TEXT("DumpGPU");
		DumpServiceParameters.LocalPath = DumpingDirectoryPath;
		DumpServiceParameters.Time = Time.ToString();
		return DumpServiceParameters;
	}

	FString GetDumpFullPath(const FString& DumpRelativeFileName) const

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:833

Scope (from outer to inner):

file
function     FTextureSubresourceDumpDesc TranslateSubresourceDumpDesc

Source code excerpt:

		bool bIsUnsupported = false;

		// We support uncompressing certain BC formats, as the DumpGPU viewer doesn't support compressed formats.  Compression
		// is used by Lumen, so it's extremely useful to preview.  Additional code below selects the uncompressed format (BC4 is
		// scalar, so we use PF_R32_FLOAT, BC5 is dual channel, so it uses PF_G16R16F, etc).  If you add a format here, you must
		// also update Engine\Extras\GPUDumpViewer\GPUDumpViewer.html (see "translate_subresource_desc").
		if ((GPixelFormats[Desc.Format].BlockSizeX != 1 ||
			 GPixelFormats[Desc.Format].BlockSizeY != 1 ||
			 GPixelFormats[Desc.Format].BlockSizeZ != 1) &&

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:2979

Scope: file

Source code excerpt:

}

} // namespace UE::RenderCore::DumpGPU

#endif // RDG_DUMP_RESOURCES

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Public/DumpGPU.h:42

Scope: file

Source code excerpt:

RENDERCORE_API bool ShouldCameraCut();

} // namespace  UE::RenderCore::DumpGPU

#endif // WITH_DUMPGPU

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Public/RenderGraphBuilder.h:1007

Scope (from outer to inner):

file
class        class FRDGBuilder

Source code excerpt:


	/////////////////////////////////////////////////////////////////////////////
	// Clobber, Visualize, and DumpGPU tools.

	/** Tracks stack counters of auxiliary passes to avoid calling them recursively. */
	struct FAuxiliaryPass
	{
		uint8 Clobber = 0;
		uint8 Visualize = 0;