r.Material.ShaderMapDump

r.Material.ShaderMapDump

#Overview

name: r.Material.ShaderMapDump

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Material.ShaderMapDump is to output a textual dump of all shader maps for a specified material. This setting variable is primarily used for debugging and analysis of material shader compilation in Unreal Engine’s rendering system.

This setting variable is utilized by the Unreal Engine’s material system, specifically within the shader compilation and caching subsystem. Based on the callsites, it’s clear that this variable is used in the Engine module, particularly in the Materials subsystem.

The value of this variable is set through the console or configuration files. It’s a string variable, where the value should be the path of the material for which you want to dump the shader maps.

The variable interacts closely with its associated variable CVarMaterialShaderMapDump. They share the same value and purpose, with CVarMaterialShaderMapDump being the actual TAutoConsoleVariable object used in the code.

Developers must be aware that:

  1. This variable is read-only (ECVF_ReadOnly), meaning it can’t be changed at runtime through code.
  2. The dump files are saved in the “Saved\MaterialShaderMaps” directory with a .txt extension.
  3. The filename of the dump is based on the DDC (Derived Data Cache) key hash.
  4. This feature will dump shader maps for all instances of the specified material, including those created by MaterialInstances.

Best practices when using this variable include:

  1. Use it only for debugging purposes, as it may impact performance.
  2. Ensure you have sufficient disk space, as shader map dumps can be large.
  3. Be specific with the material path to avoid generating unnecessary dumps.
  4. Remember to clear old dump files to prevent cluttering the project.

Regarding the associated variable CVarMaterialShaderMapDump:

The purpose of CVarMaterialShaderMapDump is identical to r.Material.ShaderMapDump. It’s the actual console variable object that controls the shader map dumping functionality.

This variable is used in the FMaterialShaderMap::SaveToDerivedDataCache() function to check if a dump should be created for the current material being processed.

The value of this variable is set through the same console command as r.Material.ShaderMapDump.

Developers should be aware that:

  1. This variable is of type TAutoConsoleVariable, allowing for string input.
  2. It’s checked every time a material shader map is saved to the derived data cache.

Best practices for using CVarMaterialShaderMapDump include:

  1. Use it in conjunction with debugging tools to analyze shader compilation issues.
  2. Clear the variable value when not actively debugging to avoid unnecessary file I/O operations.
  3. Be cautious when using in production builds, as it may impact performance and create large amounts of data.

#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:45

Scope: file

Source code excerpt:


static TAutoConsoleVariable<FString> CVarMaterialShaderMapDump(
	TEXT("r.Material.ShaderMapDump"),
	"",
	TEXT("Outputs a textual dump of all shader maps found for the given named material (specified by path).\n")
	TEXT("Note that this will include any instances of said material created by a MaterialInstance.\n")
	TEXT("Files (.txt extension) will be dumped to Saved\\MaterialShaderMaps named with the DDC key hash.\n"),
	ECVF_ReadOnly);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<FString> CVarMaterialShaderMapDump(
	TEXT("r.Material.ShaderMapDump"),
	"",
	TEXT("Outputs a textual dump of all shader maps found for the given named material (specified by path).\n")
	TEXT("Note that this will include any instances of said material created by a MaterialInstance.\n")
	TEXT("Files (.txt extension) will be dumped to Saved\\MaterialShaderMaps named with the DDC key hash.\n"),
	ECVF_ReadOnly);

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

Scope (from outer to inner):

file
function     void FMaterialShaderMap::SaveToDerivedDataCache

Source code excerpt:

	UE_LOG(LogMaterial, VeryVerbose, TEXT("Full DDC data key for %s: %s"), *Request.Name, *DataKey);

	if (!CVarMaterialShaderMapDump->GetString().IsEmpty() && CVarMaterialShaderMapDump->GetString() == GetMaterialPath())
	{
		TStringBuilder<256> Path;
		FPathViews::Append(Path, FPaths::ProjectSavedDir(), TEXT("MaterialShaderMaps"), TEXT(""));
		Path << Request.Key.Hash << ".txt";
		FArchive* DumpAr = IFileManager::Get().CreateFileWriter(*Path, FILEWRITE_Silent);
		if (DumpAr)