r.DumpShaderOutputCacheHits

r.DumpShaderOutputCacheHits

#Overview

name: r.DumpShaderOutputCacheHits

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

• type: Var
• help: Dumps shader output bytecode and cache hits with reference to original output.\nDumping shader output bytecode for all compile shaders also requires CVar r.DumpShaderDebugInfo=1.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DumpShaderOutputCacheHits is to control the debugging output of shader compilation cache hits in Unreal Engine 5. Specifically, it enables the dumping of shader output bytecode and cache hits with reference to the original output.

This setting variable is primarily used by the shader compilation system within Unreal Engine’s rendering subsystem. It’s part of the engine’s shader compiler module, as evidenced by its location in the ShaderCompiler.cpp file.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with a default value of false. This means it can be toggled on or off at runtime through the console or configuration files.

The associated variable CVarDumpShaderOutputCacheHits directly interacts with r.DumpShaderOutputCacheHits. They share the same value and purpose, with CVarDumpShaderOutputCacheHits being the actual console variable implementation.

Developers must be aware of several things when using this variable:

1. It’s marked as ECVF_ReadOnly, meaning its value should not be changed during runtime.
2. For full functionality, it requires another console variable, r.DumpShaderDebugInfo, to be set to 1.
3. Enabling this variable may have performance implications, as it will cause additional I/O operations for dumping shader information.

Best practices when using this variable include:

1. Use it only for debugging purposes, not in production builds.
2. Ensure r.DumpShaderDebugInfo is also set when you want to dump shader output bytecode for all compiled shaders.
3. Be prepared to handle and analyze the additional output files generated when this variable is enabled.

Regarding the associated variable CVarDumpShaderOutputCacheHits:

The purpose of CVarDumpShaderOutputCacheHits is identical to r.DumpShaderOutputCacheHits. It’s the actual console variable implementation that controls the shader output cache hit dumping.

This variable is used in the shader compilation system, specifically within the FShaderJobCache class, to determine whether to dump cached debug information.

The value of this variable is set through the console variable system, with a default value of false.

It directly interacts with r.DumpShaderOutputCacheHits, as they share the same value and purpose.

Developers should be aware that this variable is accessed using the GetValueOnAnyThread() method, which suggests it can be safely read from any thread.

Best practices for using this variable are the same as for r.DumpShaderOutputCacheHits, as they are essentially the same variable exposed through different interfaces.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:2086

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarDumpShaderOutputCacheHits(
	TEXT("r.DumpShaderOutputCacheHits"),
	false,
	TEXT("Dumps shader output bytecode and cache hits with reference to original output.\n")
	TEXT("Dumping shader output bytecode for all compile shaders also requires CVar r.DumpShaderDebugInfo=1."),
	ECVF_ReadOnly);

static int32 GDumpShaderDebugInfoShort = 0;

#Associated Variable and Callsites

This variable is associated with another variable named CVarDumpShaderOutputCacheHits. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:2085

Scope: file

Source code excerpt:

	);

static TAutoConsoleVariable<bool> CVarDumpShaderOutputCacheHits(
	TEXT("r.DumpShaderOutputCacheHits"),
	false,
	TEXT("Dumps shader output bytecode and cache hits with reference to original output.\n")
	TEXT("Dumping shader output bytecode for all compile shaders also requires CVar r.DumpShaderDebugInfo=1."),
	ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:11103

Scope (from outer to inner):

file
function     void FShaderJobCache::AddJobOutput

Source code excerpt:

	}

	const bool bDumpCachedDebugInfo = CVarDumpShaderOutputCacheHits.GetValueOnAnyThread();

	// Get dump shader debug output path
	FString InputDebugInfoPath, InputSourceFilename;
	if (bDumpCachedDebugInfo)
	{
		if (const FShaderCompileJob* SingleJob = FinishedJob->GetSingleShaderJob())