ShowFlag.RayTracingDebug

ShowFlag.RayTracingDebug

#Overview

name: ShowFlag.RayTracingDebug

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

It is referenced in 24 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.RayTracingDebug is to enable ray tracing debug visualization in Unreal Engine 5’s rendering system. This setting variable is primarily used for debugging and visualizing ray tracing effects in the engine.

The Unreal Engine subsystems that rely on this setting variable are primarily the Rendering module and the Ray Tracing system. Based on the callsites, it’s used in various parts of the deferred shading renderer, post-processing, and ray tracing debug functionality.

The value of this variable is typically set through the engine’s show flags system, which allows developers to toggle various debug and visualization options. It’s not explicitly shown where the value is set in the provided code snippets, but it’s likely controlled through the engine’s user interface or debug commands.

This variable interacts with several other variables and systems:

  1. It’s used in conjunction with other show flags like PathTracing and VisualizeLightCulling.
  2. It affects the behavior of auto-exposure and pre-exposure calculations.
  3. It influences the selection of ray tracing pipelines and shaders.

Developers should be aware of the following when using this variable:

  1. It’s only available in non-shipping builds (SHOWFLAG_FIXED_IN_SHIPPING(0, …)).
  2. Enabling this flag may impact performance, as it adds additional debug visualization passes.
  3. It may affect other rendering features like auto-exposure and tonemapping.

Best practices for using this variable include:

  1. Only enable it when actively debugging ray tracing features.
  2. Be aware of its impact on other rendering systems and adjust accordingly.
  3. Use it in conjunction with other ray tracing debug tools and visualizations for comprehensive debugging.

Regarding the associated variable RayTracingDebug:

The purpose of RayTracingDebug is the same as ShowFlag.RayTracingDebug. It’s used interchangeably in the code to check if ray tracing debug visualization is enabled.

This variable is used in various parts of the rendering pipeline, including deferred shading, post-processing, and ray tracing specific functions.

The value of RayTracingDebug is likely set based on the ShowFlag.RayTracingDebug value, as they are used interchangeably in the code.

Developers should treat RayTracingDebug the same way as ShowFlag.RayTracingDebug, being aware of its impact on performance and other rendering features.

Best practices for RayTracingDebug align with those of ShowFlag.RayTracingDebug, focusing on using it judiciously for debugging purposes and understanding its interactions with other rendering systems.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:395

Scope: file

Source code excerpt:

// RHI_RAYTRACING begin
SHOWFLAG_ALWAYS_ACCESSIBLE(PathTracing, SFG_Hidden, NSLOCTEXT("UnrealEd", "PathTracing", "Path tracing"))
SHOWFLAG_FIXED_IN_SHIPPING(0, RayTracingDebug, SFG_Hidden, NSLOCTEXT("UnrealEd", "RayTracingDebug", "Ray tracing debug"))
// RHI_RAYTRACING end

/** Enable the SkyAtmosphere visualization to be drawn on screen */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeSkyAtmosphere, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeSkyAtmosphereSF", "Sky Atmosphere"))
/** Enable the light function atlas debug visualization to be drawn on screen */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeLightFunctionAtlas, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeLightFunctionAtlasSF", "Visualize Light Function Atlas"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShowFlags.cpp:822

Scope: file

Source code excerpt:

		return VMI_PathTracing;
	}
	else if (EngineShowFlags.RayTracingDebug)
	{
		return VMI_RayTracingDebug;
	}
	else if (EngineShowFlags.VisualizeGPUSkinCache)
	{
		return VMI_VisualizeGPUSkinCache;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:395

Scope: file

Source code excerpt:

// RHI_RAYTRACING begin
SHOWFLAG_ALWAYS_ACCESSIBLE(PathTracing, SFG_Hidden, NSLOCTEXT("UnrealEd", "PathTracing", "Path tracing"))
SHOWFLAG_FIXED_IN_SHIPPING(0, RayTracingDebug, SFG_Hidden, NSLOCTEXT("UnrealEd", "RayTracingDebug", "Ray tracing debug"))
// RHI_RAYTRACING end

/** Enable the SkyAtmosphere visualization to be drawn on screen */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeSkyAtmosphere, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeSkyAtmosphereSF", "Sky Atmosphere"))
/** Enable the light function atlas debug visualization to be drawn on screen */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeLightFunctionAtlas, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeLightFunctionAtlasSF", "Visualize Light Function Atlas"))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.cpp:772

Scope: file

Source code excerpt:

			if (Lumen::IsUsingRayTracingLightingGrid(ViewFamily, View, bLumenEnabled)
				|| GetRayTracingTranslucencyOptions(View).bEnabled
				|| ViewFamily.EngineShowFlags.RayTracingDebug)
			{
				bBuildLightGrid = true;
			}
		}

		// The light data is built in TranslatedWorld space so must be built per view

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.cpp:3194

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::Render

Source code excerpt:

				}
			}
			else if (ViewFamily.EngineShowFlags.RayTracingDebug)
			{
				for (const FViewInfo& View : Views)
				{
					FRayTracingPickingFeedback PickingFeedback = {};
					RenderRayTracingDebug(GraphBuilder, View, SceneTextures.Color.Target, PickingFeedback);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.cpp:3510

Scope (from outer to inner):

file
function     bool HasRayTracedOverlay

Source code excerpt:

	return
		ViewFamily.EngineShowFlags.PathTracing ||
		ViewFamily.EngineShowFlags.RayTracingDebug;
}

void FDeferredShadingSceneRenderer::InitializeRayTracingFlags_RenderThread()
{
	// The result of this call is used by AnyRayTracingPassEnabled to decide if we have any RT shadows enabled
	Scene->UpdateRayTracedLights();

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IndirectLightRendering.cpp:1910

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderDeferredReflectionsAndSkyLighting

Source code excerpt:

	extern int32 GLumenVisualizeIndirectDiffuse;
	if (ViewFamily.EngineShowFlags.VisualizeLightCulling 
		|| ViewFamily.EngineShowFlags.RayTracingDebug
		|| ViewFamily.EngineShowFlags.PathTracing
		|| !ViewFamily.EngineShowFlags.Lighting
		|| GLumenVisualizeIndirectDiffuse != 0)
	{
		return;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:343

Scope (from outer to inner):

file
function     bool IsAutoExposureDebugMode

Source code excerpt:

		!EngineShowFlags.Lighting ||
		(EngineShowFlags.VisualizeBuffer && View.CurrentBufferVisualizationMode != NAME_None && !GetBufferVisualizationData().GetMaterialApplyAutoExposure(View.CurrentBufferVisualizationMode)) ||
		EngineShowFlags.RayTracingDebug ||
		EngineShowFlags.VisualizeDistanceFieldAO ||
		EngineShowFlags.VisualizeVolumetricCloudConservativeDensity ||
		EngineShowFlags.VisualizeVolumetricCloudEmptySpaceSkipping ||
		EngineShowFlags.CollisionVisibility ||
		EngineShowFlags.CollisionPawn ||
		!EngineShowFlags.PostProcessing;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:1205

Scope (from outer to inner):

file
function     void FViewInfo::UpdatePreExposure

Source code excerpt:

		&& !ViewFamily.EngineShowFlags.ActorColoration
		&& ((!ViewFamily.EngineShowFlags.VisualizeBuffer) || CurrentBufferVisualizationMode != NAME_None) // disable pre-exposure for the buffer visualization modes
		&& !ViewFamily.EngineShowFlags.RayTracingDebug;

	// Compute the PreExposure to use.
	bool bUpdateLastExposure = false;
	PreExposure = 1.f;
	if (!ViewState)
	{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessing.cpp:1816

Scope (from outer to inner):

file
function     void AddDebugViewPostProcessingPasses

Source code excerpt:


	// Some view modes do not actually output a color so they should not be tonemapped.
	const bool bTonemapAfter = View.Family->EngineShowFlags.RayTracingDebug || View.Family->EngineShowFlags.VisualizeGPUSkinCache;
	const bool bTonemapBefore = !bTonemapAfter && !View.Family->EngineShowFlags.ShaderComplexity;
	const bool bViewFamilyOutputInHDR = View.Family->RenderTarget->GetSceneHDREnabled();

	enum class EPass : uint32
	{
		Visualize,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:116

Scope: file

Source code excerpt:

);

IMPLEMENT_RT_PAYLOAD_TYPE(ERayTracingPayloadType::RayTracingDebug, 44);

BEGIN_UNIFORM_BUFFER_STRUCT(FRayTracingDebugHitStatsUniformBufferParameters, )
	SHADER_PARAMETER_RDG_BUFFER_UAV(RWStructuredBuffer<FRayTracingHitStatsEntry>, HitStatsOutput)
END_UNIFORM_BUFFER_STRUCT()

IMPLEMENT_UNIFORM_BUFFER_STRUCT(FRayTracingDebugHitStatsUniformBufferParameters, "RayTracingDebugHitStatsUniformBuffer");

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:169

Scope (from outer to inner):

file
class        class FRayTracingDebugRGS : public FGlobalShader
function     static ERayTracingPayloadType GetRayTracingPayloadType

Source code excerpt:

		if (PermutationVector.Get<FUseDebugCHSType>())
		{
			return ERayTracingPayloadType::RayTracingDebug;
		}
		else
		{
			return ERayTracingPayloadType::RayTracingMaterial;
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:211

Scope (from outer to inner):

file
class        class FRayTracingDebugCHS : public FGlobalShader
function     static ERayTracingPayloadType GetRayTracingPayloadType

Source code excerpt:

	static ERayTracingPayloadType GetRayTracingPayloadType(const int32 PermutationId)
	{
		return ERayTracingPayloadType::RayTracingDebug;
	}
};
IMPLEMENT_GLOBAL_SHADER(FRayTracingDebugCHS, "/Engine/Private/RayTracing/RayTracingDebugCHS.usf", "closesthit=RayTracingDebugMainCHS anyhit=RayTracingDebugAHS", SF_RayHitGroup);

class FRayTracingDebugMS : public FGlobalShader
{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:239

Scope (from outer to inner):

file
class        class FRayTracingDebugMS : public FGlobalShader
function     static ERayTracingPayloadType GetRayTracingPayloadType

Source code excerpt:

	static ERayTracingPayloadType GetRayTracingPayloadType(const int32 PermutationId)
	{
		return ERayTracingPayloadType::RayTracingDebug;
	}
};
IMPLEMENT_GLOBAL_SHADER(FRayTracingDebugMS, "/Engine/Private/RayTracing/RayTracingDebugMS.usf", "RayTracingDebugMS", SF_RayMiss);
class FRayTracingDebugHitStatsRGS : public FGlobalShader
{
	DECLARE_GLOBAL_SHADER(FRayTracingDebugHitStatsRGS);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:266

Scope (from outer to inner):

file
class        class FRayTracingDebugHitStatsRGS : public FGlobalShader
function     static ERayTracingPayloadType GetRayTracingPayloadType

Source code excerpt:

	static ERayTracingPayloadType GetRayTracingPayloadType(const int32 PermutationId)
	{
		return ERayTracingPayloadType::RayTracingDebug;
	}
};
IMPLEMENT_GLOBAL_SHADER(FRayTracingDebugHitStatsRGS, "/Engine/Private/RayTracing/RayTracingDebugHitStats.usf", "RayTracingDebugHitStatsRGS", SF_RayGen);


class FRayTracingDebugHitStatsCHS : public FGlobalShader

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:303

Scope (from outer to inner):

file
class        class FRayTracingDebugHitStatsCHS : public FGlobalShader
function     static ERayTracingPayloadType GetRayTracingPayloadType

Source code excerpt:

	static ERayTracingPayloadType GetRayTracingPayloadType(const int32 PermutationId)
	{
		return ERayTracingPayloadType::RayTracingDebug;
	}
};
IMPLEMENT_GLOBAL_SHADER(FRayTracingDebugHitStatsCHS, "/Engine/Private/RayTracing/RayTracingDebugHitStatsCHS.usf", "closesthit=RayTracingDebugHitStatsCHS anyhit=RayTracingDebugHitStatsAHS", SF_RayHitGroup);

class FRayTracingDebugTraversalCS : public FGlobalShader
{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:387

Scope (from outer to inner):

file
class        class FRayTracingPickingRGS : public FGlobalShader
function     static ERayTracingPayloadType GetRayTracingPayloadType

Source code excerpt:

	static ERayTracingPayloadType GetRayTracingPayloadType(const int32 PermutationId)
	{
		return ERayTracingPayloadType::RayTracingDebug;
	}
};
IMPLEMENT_GLOBAL_SHADER(FRayTracingPickingRGS, "/Engine/Private/RayTracing/RayTracingDebugPicking.usf", "RayTracingDebugPickingRGS", SF_RayGen);

class FRayTracingDebugInstanceOverlapVS : public FGlobalShader
{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:787

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::PrepareRayTracingDebug

Source code excerpt:

{
	// Declare all RayGen shaders that require material closest hit shaders to be bound
	bool bEnabled = ViewFamily.EngineShowFlags.RayTracingDebug && ShouldRenderRayTracingEffect(ERayTracingPipelineCompatibilityFlags::FullPipeline);
	if (bEnabled)
	{
		{
			FRayTracingDebugRGS::FPermutationDomain PermutationVector;
			PermutationVector.Set<FRayTracingDebugRGS::FUseDebugCHSType>(false);
			auto RayGenShader = GetGlobalShaderMap(ViewFamily.GetShaderPlatform())->GetShader<FRayTracingDebugRGS>(PermutationVector);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:805

Scope (from outer to inner):

file
function     static FRDGBufferRef RayTracingPerformPicking

Source code excerpt:


	FRayTracingPipelineStateInitializer Initializer;
	Initializer.MaxPayloadSizeInBytes = GetRayTracingPayloadTypeMaxSize(ERayTracingPayloadType::RayTracingDebug);

	FRHIRayTracingShader* RayGenShaderTable[] = { RayGenShader.GetRayTracingShader() };
	Initializer.SetRayGenShaderTable(RayGenShaderTable);

	FRayTracingDebugCHS::FPermutationDomain PermutationVector;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:1040

Scope (from outer to inner):

file
function     static FRDGBufferRef RayTracingPerformHitStatsPerPrimitive

Source code excerpt:


	FRayTracingPipelineStateInitializer Initializer;
	Initializer.MaxPayloadSizeInBytes = GetRayTracingPayloadTypeMaxSize(ERayTracingPayloadType::RayTracingDebug);

	FRHIRayTracingShader* RayGenShaderTable[] = { RayGenShader.GetRayTracingShader() };
	Initializer.SetRayGenShaderTable(RayGenShaderTable);

	FRayTracingDebugHitStatsCHS::FPermutationDomain PermutationVector;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:1386

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderRayTracingDebug

Source code excerpt:

		FIntRect ViewRect = View.ViewRect;

		RDG_GPU_STAT_SCOPE(GraphBuilder, RayTracingDebug);

		const FIntPoint GroupSize(FRayTracingDebugTraversalCS::ThreadGroupSizeX, FRayTracingDebugTraversalCS::ThreadGroupSizeY);
		const FIntVector GroupCount = FComputeShaderUtils::GetGroupCount(ViewRect.Size(), GroupSize);

		FRayTracingDebugTraversalCS::FPermutationDomain PermutationVector;
		PermutationVector.Set<FRayTracingDebugTraversalCS::FSupportProceduralPrimitive>((bool)GVisualizeProceduralPrimitives);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:1473

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderRayTracingDebug

Source code excerpt:

	{
		FRayTracingPipelineStateInitializer Initializer;
		Initializer.MaxPayloadSizeInBytes = GetRayTracingPayloadTypeMaxSize(ERayTracingPayloadType::RayTracingDebug);

		FRHIRayTracingShader* RayGenShaderTable[] = { RayGenShader.GetRayTracingShader() };
		Initializer.SetRayGenShaderTable(RayGenShaderTable);

		FRayTracingDebugCHS::FPermutationDomain PermutationVectorCHS;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:1552

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderRayTracingDebug

Source code excerpt:

	FIntRect ViewRect = View.ViewRect;

	RDG_GPU_STAT_SCOPE(GraphBuilder, RayTracingDebug);

	GraphBuilder.AddPass(
		RDG_EVENT_NAME("RayTracingDebug"),
		RayGenParameters,
		ERDGPassFlags::Compute,
		[this, RayGenParameters, RayGenShader, &View, Pipeline, ViewRect, bRequiresBindings](FRHIRayTracingCommandList& RHICmdList)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingPrimaryRays.cpp:83

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::PrepareRayTracingTranslucency

Source code excerpt:

	// Declare all RayGen shaders that require material closest hit shaders to be bound.
	// NOTE: Translucency shader may be used for primary ray debug view mode.
	if (GetRayTracingTranslucencyOptions(View).bEnabled || View.Family->EngineShowFlags.RayTracingDebug)
	{
		FRayTracingPrimaryRaysRGS::FPermutationDomain PermutationVector;

		PermutationVector.Set<FRayTracingPrimaryRaysRGS::FEnableTwoSidedGeometryForShadowDim>(EnableRayTracingShadowTwoSidedGeometry());

		auto RayGenShader = View.ShaderMap->GetShader<FRayTracingPrimaryRaysRGS>(PermutationVector);