r.ForceDebugViewModes

r.ForceDebugViewModes

#Overview

name: r.ForceDebugViewModes

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ForceDebugViewModes is to control the availability of debug view modes in Unreal Engine’s rendering system. This setting variable allows developers to force enable or disable debug view modes across different build configurations.

r.ForceDebugViewModes is primarily used by the rendering system, specifically in the RenderCore and Renderer modules. These subsystems rely on this variable to determine whether debug view modes should be available or not.

The value of this variable is set through a console variable (CVarForceDebugViewModes) defined in ShaderCore.cpp. It can be set to 0 (default, no effect), 1 (force enable), or 2 (force disable).

This variable interacts closely with its associated variable CVarForceDebugViewModes, which is the actual TAutoConsoleVariable that stores and manages the value.

Developers must be aware that:

  1. Setting this to 1 will force debug view modes to be available even in cooked builds.
  2. Setting it to 2 will force debug view modes to be unavailable even in editor builds, which can reduce shader permutations and speed up shader iteration.
  3. On console platforms, additional steps may be required to enable debug view modes (setting to 1 in ConsoleVariables.ini and including EngineDebugMaterials in StartupPackages).

Best practices when using this variable include:

  1. Use it judiciously, as enabling debug view modes in production builds may have performance implications.
  2. When disabling debug view modes in editor builds (value 2), be aware that this will remove many shader permutations, which can affect development workflows.
  3. Coordinate its use with the team, as it can significantly impact the rendering pipeline and debugging capabilities.

Regarding the associated variable CVarForceDebugViewModes:

The purpose of CVarForceDebugViewModes is to provide a console-accessible way to control the r.ForceDebugViewModes setting. It’s defined as a TAutoConsoleVariable, which allows it to be changed at runtime through the console.

This variable is used directly in the RenderCore module to determine the state of debug view modes. It’s accessed using GetValueOnAnyThread() method, which suggests it’s designed to be safe for multi-threaded access.

The value of CVarForceDebugViewModes is set when it’s defined, with a default value of 0. It can be changed at runtime through the console or potentially through configuration files.

CVarForceDebugViewModes directly interacts with the r.ForceDebugViewModes setting, essentially serving as its storage and interface.

Developers should be aware that this is a read-only console variable (ECVF_ReadOnly flag), meaning it can’t be changed during runtime in shipping builds. It’s also marked as render thread safe (ECVF_RenderThreadSafe flag).

Best practices for using CVarForceDebugViewModes include:

  1. Use it for debugging and development purposes, not for gameplay features.
  2. Be cautious when changing its value, as it can have significant impacts on rendering and performance.
  3. Remember that changes to this variable will affect the entire rendering pipeline, so use it in a controlled environment.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderCore.cpp:363

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarForceDebugViewModes(
	TEXT("r.ForceDebugViewModes"),
	0,
	TEXT("0: Setting has no effect.\n")
	TEXT("1: Forces debug view modes to be available, even on cooked builds.")
	TEXT("2: Forces debug view modes to be unavailable, even on editor builds.  Removes many shader permutations for faster shader iteration."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderCore.cpp:383

Scope (from outer to inner):

file
function     bool AllowDebugViewmodes

Source code excerpt:

	int32 ForceDebugViewValue = CVarForceDebugViewModes.GetValueOnAnyThread();

	// To use debug viewmodes on consoles, r.ForceDebugViewModes must be set to 1 in ConsoleVariables.ini
	// And EngineDebugMaterials must be in the StartupPackages for the target platform.

	// Force enabled: r.ForceDebugViewModes 1
	const bool bForceEnable = ForceDebugViewValue == 1;
	if (bForceEnable)
	{
		return true;
	}

	// Force disabled: r.ForceDebugViewModes 2
	const bool bForceDisable = ForceDebugViewValue == 2;
	if (bForceDisable)
	{
		return false;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:4398

Scope (from outer to inner):

file
function     bool FSceneRenderer::ShouldCompositeDebugPrimitivesInPostProcess

Source code excerpt:

	{
		//If we have primitives to draw, check we aren't forcing debug view modes off.
		static bool bIsForceDisabled = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.ForceDebugViewModes"))->GetValueOnAnyThread() == 2;
		return !bIsForceDisabled;
	}
	return false;
}
#endif

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderCore.cpp:362

Scope: file

Source code excerpt:

static TMap<FString, FString> GShaderSourceDirectoryMappings;

static TAutoConsoleVariable<int32> CVarForceDebugViewModes(
	TEXT("r.ForceDebugViewModes"),
	0,
	TEXT("0: Setting has no effect.\n")
	TEXT("1: Forces debug view modes to be available, even on cooked builds.")
	TEXT("2: Forces debug view modes to be unavailable, even on editor builds.  Removes many shader permutations for faster shader iteration."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderCore.cpp:381

Scope (from outer to inner):

file
function     bool AllowDebugViewmodes

Source code excerpt:

bool AllowDebugViewmodes()
{	
	int32 ForceDebugViewValue = CVarForceDebugViewModes.GetValueOnAnyThread();

	// To use debug viewmodes on consoles, r.ForceDebugViewModes must be set to 1 in ConsoleVariables.ini
	// And EngineDebugMaterials must be in the StartupPackages for the target platform.

	// Force enabled: r.ForceDebugViewModes 1
	const bool bForceEnable = ForceDebugViewValue == 1;

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderCore.cpp:419

Scope (from outer to inner):

file
function     bool AllowDebugViewmodes

Source code excerpt:

{
#if WITH_EDITOR
	const int32 ForceDebugViewValue = CVarForceDebugViewModes.GetValueOnAnyThread();
	bool bForceEnable = ForceDebugViewValue == 1;
	bool bForceDisable = ForceDebugViewValue == 2;

	#if 0
		// We can't distinguish between editor and non-editor targets solely from EShaderPlatform.
		// RequiresCookedData() was always returning true for Windows in UE 4, and false in UE 5, for Windows