r.ShaderCompiler.DebugDDCKeyAsset

r.ShaderCompiler.DebugDDCKeyAsset

#Overview

name: r.ShaderCompiler.DebugDDCKeyAsset

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

• type: Var
• help: if set, assets containing this name will print their full DDC key hash information when requested

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderCompiler.DebugDDCKeyAsset is to enable debugging of Derived Data Cache (DDC) key information for specific assets in the shader compilation process. This setting variable is primarily used in the material and shader compilation system of Unreal Engine.

This setting variable is used within the Unreal Engine’s shader compilation subsystem, specifically in the material shader module. It’s part of the engine’s core rendering system, used during the shader compilation and caching process.

The value of this variable is set through the console variable system (CVarShaderCompilerDebugDDCKeyAsset). It’s a string value that can be set at runtime, allowing developers to specify which assets they want to debug.

The associated variable CVarShaderCompilerDebugDDCKeyAsset directly interacts with r.ShaderCompiler.DebugDDCKeyAsset. They share the same value and purpose.

Developers must be aware that this variable is only available in editor builds (#if WITH_EDITOR), so it’s not meant for use in shipping games. It’s a debugging tool that, when set, will cause additional logging output for assets whose names contain the specified string.

Best practices when using this variable include:

1. Use it sparingly and only when debugging shader compilation issues.
2. Be specific with the asset name to avoid excessive logging.
3. Remember to clear the variable after debugging to prevent unnecessary performance overhead.

Regarding the associated variable CVarShaderCompilerDebugDDCKeyAsset:

The purpose of CVarShaderCompilerDebugDDCKeyAsset is identical to r.ShaderCompiler.DebugDDCKeyAsset. It’s the actual console variable implementation that controls the behavior.

This variable is used in the FMaterialShaderMap::BeginLoadFromDerivedDataCache function to check if debug logging should be performed for a specific material asset.

The value is set and retrieved using the console variable system, specifically with GetValueOnAnyThread().

It interacts directly with the material loading and shader compilation process, triggering debug output when the material’s asset name matches the specified string.

Developers should be aware that using this variable will incur a small performance cost due to the additional string comparison and potential logging, so it should be used judiciously.

Best practices include using this for targeted debugging of specific problematic materials or shaders, and ensuring it’s not left enabled in builds that will be distributed or used for performance testing.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialShader.cpp:54

Scope: file

Source code excerpt:

#if WITH_EDITOR
static TAutoConsoleVariable<FString> CVarShaderCompilerDebugDDCKeyAsset(
	TEXT("r.ShaderCompiler.DebugDDCKeyAsset"),
	FString(),
	TEXT("if set, assets containing this name will print their full DDC key hash information when requested"),
	ECVF_Default
);
#endif // WITH_EDITOR

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialShader.cpp:53

Scope: file

Source code excerpt:

#if WITH_EDITOR
static TAutoConsoleVariable<FString> CVarShaderCompilerDebugDDCKeyAsset(
	TEXT("r.ShaderCompiler.DebugDDCKeyAsset"),
	FString(),
	TEXT("if set, assets containing this name will print their full DDC key hash information when requested"),
	ECVF_Default
);
#endif // WITH_EDITOR

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialShader.cpp:1514

Scope (from outer to inner):

file
function     TSharedRef<FMaterialShaderMap::FAsyncLoadContext> FMaterialShaderMap::BeginLoadFromDerivedDataCache
function     STAT

Source code excerpt:

			}

			if (UNLIKELY(!CVarShaderCompilerDebugDDCKeyAsset.GetValueOnAnyThread().IsEmpty()))
			{
				FString DebugDDCKeyAsset = CVarShaderCompilerDebugDDCKeyAsset.GetValueOnAnyThread();
				if (Material->GetAssetName().Contains(DebugDDCKeyAsset))
				{
					FString DataKey = Result->DataKey;
					DataKey.RemoveFromEnd(TEXT("\n"));
					UE_LOG(LogMaterial, Display, TEXT("%s-%s-%s: %s"), *Material->GetAssetName(), *LexToString(ShaderMapId.FeatureLevel), *LexToString(ShaderMapId.QualityLevel), *DataKey);
				}