r.Lumen.Visualize.HardwareRayTracing.Compact

r.Lumen.Visualize.HardwareRayTracing.Compact

#Overview

name: r.Lumen.Visualize.HardwareRayTracing.Compact

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.Lumen.Visualize.HardwareRayTracing.Compact is to control whether a second trace will be compacted before traversal in Lumen’s hardware ray tracing visualization system. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically its visualization tools for hardware-based ray tracing.

The Lumen subsystem within the Renderer module relies on this setting variable. It is primarily used in the LumenVisualizeHardwareRayTracing component of the engine.

The value of this variable is set using a console variable (CVar) system. It is initialized with a default value of 1, meaning compaction is enabled by default.

This variable interacts with a C++ variable named CVarLumenVisualizeHardwareRayTracingCompact, which is an instance of TAutoConsoleVariable. This C++ variable directly corresponds to the console variable and is used to access its value in the code.

Developers must be aware that this variable affects the performance and behavior of the ray tracing visualization system. When enabled (set to 1), it causes a second trace to be compacted before traversal, which can potentially improve performance but may have other implications on the visualization process.

Best practices when using this variable include:

  1. Understanding the performance implications of enabling or disabling compaction.
  2. Testing the visualization with both settings (0 and 1) to ensure desired results.
  3. Considering the target hardware capabilities when deciding whether to enable compaction.

Regarding the associated variable CVarLumenVisualizeHardwareRayTracingCompact:

This C++ variable is the internal representation of the r.Lumen.Visualize.HardwareRayTracing.Compact console variable. It’s used to retrieve the current value of the setting within the C++ code.

The purpose of this variable is to provide a programmatic way to access the console variable’s value, allowing the code to make decisions based on the user’s setting.

It’s used in the Lumen visualization system to determine whether to perform ray compaction. For example, in the provided code snippet, it’s checked to decide whether to compact rays that need to be re-traced:

if ((CVarLumenVisualizeHardwareRayTracingCompact.GetValueOnRenderThread() != 0) || bForceHitLighting)

Developers should be aware that this variable’s value is accessed using the GetValueOnRenderThread() method, which suggests it should only be used in render thread contexts.

Best practices for using this variable include:

  1. Only accessing it from the render thread.
  2. Caching its value if it’s going to be used multiple times in a single frame, to avoid repeated calls to GetValueOnRenderThread().
  3. Being aware of its impact on the visualization system’s behavior and performance when making changes to related code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeHardwareRayTracing.cpp:74

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenVisualizeHardwareRayTracingCompact(
	TEXT("r.Lumen.Visualize.HardwareRayTracing.Compact"),
	1,
	TEXT("Determines whether a second trace will be compacted before traversal (default = 1"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenVisualizeHardwareRayTracingBucketMaterials(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeHardwareRayTracing.cpp:73

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenVisualizeHardwareRayTracingCompact(
	TEXT("r.Lumen.Visualize.HardwareRayTracing.Compact"),
	1,
	TEXT("Determines whether a second trace will be compacted before traversal (default = 1"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeHardwareRayTracing.cpp:721

Scope: file

Source code excerpt:

	{
		// Compact rays which need to be re-traced
		if ((CVarLumenVisualizeHardwareRayTracingCompact.GetValueOnRenderThread() != 0) || bForceHitLighting)
		{
			FRDGBufferRef CompactedRayAllocatorBuffer = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateBufferDesc(sizeof(uint32), 1), TEXT("Lumen.Visualize.CompactedRayAllocator"));
			AddClearUAVPass(GraphBuilder, GraphBuilder.CreateUAV(CompactedRayAllocatorBuffer, PF_R32_UINT), 0);

			FRDGBufferRef CompactedRayDataPackedBuffer = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateStructuredDesc(sizeof(LumenVisualize::FRayDataPacked), RayCount), TEXT("Lumen.Visualize.CompactedRayDataPacked"));
			FRDGBufferRef CompactedTraceDataPackedBuffer = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateStructuredDesc(sizeof(LumenVisualize::FTraceDataPacked), RayCount), TEXT("Lumen.Visualize.CompactedTraceDataPacked"));