r.RHIValidation.DebugBreak.Transitions

r.RHIValidation.DebugBreak.Transitions

#Overview

name: r.RHIValidation.DebugBreak.Transitions

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.RHIValidation.DebugBreak.Transitions is to control the debugger behavior when a validation error is encountered in the RHI (Rendering Hardware Interface) subsystem of Unreal Engine 5.

This setting variable is primarily used by the RHI validation system, which is part of the rendering subsystem in Unreal Engine 5. It is specifically related to the validation of resource state transitions in the RHI.

The value of this variable is set through the Unreal Engine console variable system. It is initialized with a default value of 1, but can be changed at runtime using the console command system.

The r.RHIValidation.DebugBreak.Transitions variable interacts directly with the GBreakOnTransitionError variable. They share the same value, with GBreakOnTransitionError being the actual variable used in the code logic.

Developers must be aware that when this variable is set to 1 (which is the default), the debugger will break execution when a validation error is encountered. This can be useful for identifying and fixing issues, but may interrupt workflow if not expected.

Best practices when using this variable include:

  1. Keeping it enabled (set to 1) during development to catch and address RHI validation errors early.
  2. Disabling it (set to 0) for release builds or when debugging other aspects of the engine to avoid unexpected interruptions.
  3. Using it in conjunction with other RHI validation tools and logging mechanisms for comprehensive debugging.

Regarding the associated variable GBreakOnTransitionError:

The purpose of GBreakOnTransitionError is to serve as the internal representation of the r.RHIValidation.DebugBreak.Transitions setting within the engine’s C++ code.

This variable is used directly in the RHI validation system, specifically in the FValidationRHI::ReportValidationFailure function. When a validation failure occurs, and if a debugger is present, the code checks this variable to determine whether to trigger a breakpoint.

The value of GBreakOnTransitionError is set indirectly through the r.RHIValidation.DebugBreak.Transitions console variable.

Developers should be aware that modifying GBreakOnTransitionError directly in code is not recommended, as it may be overwritten by the console variable system. Instead, they should use the r.RHIValidation.DebugBreak.Transitions console variable to control this behavior.

Best practices for GBreakOnTransitionError include:

  1. Treating it as a read-only variable in most code contexts.
  2. Using it for conditional logic related to RHI validation error handling.
  3. Ensuring that any code depending on this variable can handle both true and false states gracefully.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHIValidation.cpp:35

Scope (from outer to inner):

file
namespace    RHIValidation

Source code excerpt:

	int32 GBreakOnTransitionError = 1;
	FAutoConsoleVariableRef CVarBreakOnTransitionError(
		TEXT("r.RHIValidation.DebugBreak.Transitions"),
		GBreakOnTransitionError,
		TEXT("Controls whether the debugger should break when a validation error is encountered.\n")
		TEXT(" 0: disabled;\n")
		TEXT(" 1: break in the debugger if a validation error is encountered."),
		ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHIValidation.cpp:33

Scope (from outer to inner):

file
namespace    RHIValidation

Source code excerpt:

namespace RHIValidation
{
	int32 GBreakOnTransitionError = 1;
	FAutoConsoleVariableRef CVarBreakOnTransitionError(
		TEXT("r.RHIValidation.DebugBreak.Transitions"),
		GBreakOnTransitionError,
		TEXT("Controls whether the debugger should break when a validation error is encountered.\n")
		TEXT(" 0: disabled;\n")
		TEXT(" 1: break in the debugger if a validation error is encountered."),
		ECVF_RenderThreadSafe);

	// Returns an array of resource names parsed from the "-RHIValidationLog" command line switch.

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHIValidation.cpp:847

Scope (from outer to inner):

file
function     void FValidationRHI::ReportValidationFailure

Source code excerpt:

	UE_LOG(LogRHI, Error, TEXT("%s"), *Message);

	if (FPlatformMisc::IsDebuggerPresent() && RHIValidation::GBreakOnTransitionError)
	{
		// Print the message again using the debug output function, because UE_LOG doesn't always reach
		// the VS output window before the breakpoint is triggered, despite the log flush call below.
		FPlatformMisc::LowLevelOutputDebugStringf(TEXT("%s\n"), *Message);
		GLog->Flush();
		PLATFORM_BREAK();