r.Lumen.Reflections.TraceCompaction.GroupSizeInTraceTiles

r.Lumen.Reflections.TraceCompaction.GroupSizeInTraceTiles

#Overview

name: r.Lumen.Reflections.TraceCompaction.GroupSizeInTraceTiles

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.Reflections.TraceCompaction.GroupSizeInTraceTiles is to control the size of the trace compaction threadgroup in Lumen’s reflection system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically for the reflection tracing component.

This setting variable is primarily used in the Lumen reflection tracing subsystem, which is part of the rendering module in Unreal Engine 5. It’s specifically related to the trace compaction process for reflections.

The value of this variable is set through the Unreal Engine console system, as indicated by the FAutoConsoleVariableRef declaration. It’s initialized with a default value of 16.

This variable interacts closely with GLumenReflectionTraceCompactionWaveOps. The actual thread group size used in the compaction process depends on whether wave operations are enabled.

Developers should be aware that:

  1. This setting only affects the WaveOps path of trace compaction.
  2. Larger group sizes can lead to better coherency in compacted traces, but may also impact performance.
  3. The effective group size is determined by both this variable and the WaveOps setting.

Best practices when using this variable include:

  1. Experiment with different values to find the optimal balance between trace coherency and performance for your specific use case.
  2. Consider the capabilities of your target hardware, as larger group sizes may be more beneficial on some GPU architectures than others.
  3. Always profile your application when adjusting this setting to ensure it’s not negatively impacting overall performance.

Regarding the associated variable GLumenReflectionTraceCompactionGroupSizeInTiles:

This is an internal C++ variable that directly corresponds to the console variable r.Lumen.Reflections.TraceCompaction.GroupSizeInTraceTiles. It’s used within the engine code to actually store and access the value set by the console variable.

The purpose of GLumenReflectionTraceCompactionGroupSizeInTiles is to provide a quick, direct access to the trace compaction group size within the C++ code of the Lumen reflection tracing system.

This variable is used in the Lumen reflection tracing subsystem, specifically in the trace compaction process.

Its value is set by the FAutoConsoleVariableRef system, which links it to the r.Lumen.Reflections.TraceCompaction.GroupSizeInTraceTiles console variable.

It interacts closely with GLumenReflectionTraceCompactionWaveOps to determine the actual thread group size used in the compaction process.

Developers should be aware that modifying this variable directly in C++ code is not recommended, as it’s meant to be controlled via the console variable system.

Best practices include using the console variable for runtime adjustments and avoiding direct manipulation of GLumenReflectionTraceCompactionGroupSizeInTiles in code unless absolutely necessary.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:71

Scope: file

Source code excerpt:

int32 GLumenReflectionTraceCompactionGroupSizeInTiles = 16;
FAutoConsoleVariableRef GVarLumenReflectionTraceCompactionGroupSizeInTiles(
	TEXT("r.Lumen.Reflections.TraceCompaction.GroupSizeInTraceTiles"),
	GLumenReflectionTraceCompactionGroupSizeInTiles,
	TEXT("Size of the trace compaction threadgroup.  Larger group = better coherency in the compacted traces.  Currently only supported by WaveOps path."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionTraceCompactionWaveOps = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:69

Scope: file

Source code excerpt:

);

int32 GLumenReflectionTraceCompactionGroupSizeInTiles = 16;
FAutoConsoleVariableRef GVarLumenReflectionTraceCompactionGroupSizeInTiles(
	TEXT("r.Lumen.Reflections.TraceCompaction.GroupSizeInTraceTiles"),
	GLumenReflectionTraceCompactionGroupSizeInTiles,
	TEXT("Size of the trace compaction threadgroup.  Larger group = better coherency in the compacted traces.  Currently only supported by WaveOps path."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionTraceCompactionWaveOps = 1;
FAutoConsoleVariableRef CVarLumenReflectionTraceCompactionWaveOps(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:606

Scope (from outer to inner):

file
function     FCompactedReflectionTraceParameters LumenReflections::CompactTraces

Source code excerpt:


	// Only the wave ops path maintains trace order, switch to smaller groups without it to preserve coherency in the traces
	const uint32 CompactionThreadGroupSize = FReflectionCompactTracesCS::GetThreadGroupSize(bWaveOps ? GLumenReflectionTraceCompactionGroupSizeInTiles : 1);
	FRDGBufferRef ReflectionCompactionIndirectArgs = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateIndirectDesc<FRHIDispatchIndirectParameters>(1), TEXT("Lumen.Reflections.CompactionIndirectArgs"));

	{
		FSetupCompactionIndirectArgsCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FSetupCompactionIndirectArgsCS::FParameters>();
		PassParameters->RWCompactedTraceTexelAllocator = GraphBuilder.CreateUAV(CompactedTraceTexelAllocator, PF_R32_UINT);
		PassParameters->RWReflectionCompactionIndirectArgs = GraphBuilder.CreateUAV(ReflectionCompactionIndirectArgs, PF_R32_UINT);