r.RayTracing.DebugTriangleHitCount.TopKMostHits

r.RayTracing.DebugTriangleHitCount.TopKMostHits

#Overview

name: r.RayTracing.DebugTriangleHitCount.TopKMostHits

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

• type: Var
• help: Highlight top k most hit instances in the view. (default = 10)\n

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RayTracing.DebugTriangleHitCount.TopKMostHits is to control the number of most-hit instances to highlight in the view during ray tracing debug visualization. This setting variable is primarily used for debugging and performance analysis of the ray tracing system in Unreal Engine 5.

This setting variable is utilized by the Renderer module, specifically within the ray tracing debug visualization subsystem. It’s primarily referenced in the RayTracingDebug.cpp file, which is part of the ray tracing debugging functionality.

The value of this variable is set through a console variable (CVarRayTracingDebugHitCountTopKHits) with a default value of 10. It can be modified at runtime through the console or configuration files.

The associated variable CVarRayTracingDebugHitCountTopKHits directly interacts with r.RayTracing.DebugTriangleHitCount.TopKMostHits. They share the same value and purpose.

Developers should be aware that:

1. This variable affects debugging performance and visualization, not the actual ray tracing process.
2. Higher values may impact performance during debugging sessions.
3. The visualization lags by one frame, which might cause some instances to be missed in a single frame.

Best practices when using this variable include:

1. Use it judiciously during development and debugging phases.
2. Adjust the value based on the complexity of the scene and the specific debugging needs.
3. Be mindful of potential performance impacts when setting higher values.

Regarding the associated variable CVarRayTracingDebugHitCountTopKHits:

• Its purpose is identical to r.RayTracing.DebugTriangleHitCount.TopKMostHits.
• It’s used to retrieve the value in various parts of the ray tracing debug code.
• It’s defined as a TAutoConsoleVariable, allowing for runtime modification.
• The variable is accessed using GetValueOnRenderThread() to ensure thread-safe access in the rendering code.
• Developers should use this variable when they need to programmatically access or modify the top-K most hit instances value in C++ code within the ray tracing debug system.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarRayTracingDebugHitCountTopKHits(
	TEXT("r.RayTracing.DebugTriangleHitCount.TopKMostHits"),
	10,
	TEXT("Highlight top k most hit instances in the view. (default = 10)\n")
);

static int32 GVisualizeProceduralPrimitives = 0;
static FAutoConsoleVariableRef CVarVisualizeProceduralPrimitives(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarRayTracingDebugHitCountTopKHits(
	TEXT("r.RayTracing.DebugTriangleHitCount.TopKMostHits"),
	10,
	TEXT("Highlight top k most hit instances in the view. (default = 10)\n")
);

static int32 GVisualizeProceduralPrimitives = 0;

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

Scope (from outer to inner):

file
function     static void PrintTopKMostHitMessage

Source code excerpt:

	ShaderPrint::SetEnabled(true);

	int32 NumPrimitives = CVarRayTracingDebugHitCountTopKHits.GetValueOnRenderThread();
	if (ShaderPrint::IsEnabled(View.ShaderPrintData) && NumPrimitives > 0)
	{
		// This lags by one frame, so may miss some in one frame, also overallocates since we will cull a lot.
		ShaderPrint::RequestSpaceForLines(NumPrimitives * 12);

		const uint32 MaxPrimitiveNameCount = 128u;

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

Scope (from outer to inner):

file
function     static FRDGBufferRef RayTracingPerformHitStatsPerPrimitive

Source code excerpt:

	const uint32 NumPrimitives = FMath::Max<uint32>(Scene->Primitives.Num(),
		(uint32)CVarRayTracingDebugHitCountTopKHits.GetValueOnRenderThread());
	FRDGBufferDesc HitStatsPerPrimitiveBufferDesc = FRDGBufferDesc::CreateStructuredDesc(sizeof(FRayTracingHitStatsEntry), NumPrimitives);
	HitStatsPerPrimitiveBufferDesc.Usage = EBufferUsageFlags(HitStatsPerPrimitiveBufferDesc.Usage | BUF_SourceCopy);
	FRDGBufferRef HitStatsBuffer = GraphBuilder.CreateBuffer(HitStatsPerPrimitiveBufferDesc, TEXT("RayTracingDebug.HitStatsBuffer"));
	

	FRayTracingDebugHitStatsUniformBufferParameters* DebugHitStatsUniformBufferParameters = GraphBuilder.AllocParameters<FRayTracingDebugHitStatsUniformBufferParameters>();

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderRayTracingDebug

Source code excerpt:

	RayGenParameters->RayTracingDebugHitStatsUniformBuffer = DebugHitStatsUniformBuffer;
	RayGenParameters->LightGridPacked = View.RayTracingLightGridUniformBuffer;
	RayGenParameters->TopKMostHitInstances = CVarRayTracingDebugHitCountTopKHits.GetValueOnRenderThread();
	RayGenParameters->NumTotalInstances = NumInstances;

	
	// If we don't output depth, create dummy 1x1 texture
	const bool bOutputDepth = DebugVisualizationMode == RAY_TRACING_DEBUG_VIZ_INSTANCE_OVERLAP;