r.Lumen.Reflections.TraceCompaction.WaveOps

r.Lumen.Reflections.TraceCompaction.WaveOps

#Overview

name: r.Lumen.Reflections.TraceCompaction.WaveOps

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

• type: Var
• help: Whether to use Wave Ops path for trace compaction.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Reflections.TraceCompaction.WaveOps is to control whether Wave Operations are used for trace compaction in Lumen’s reflection system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically focusing on the reflection component.

This setting variable is primarily used in the Lumen reflection tracing subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is referenced in the LumenReflectionTracing.cpp file, which is part of the Renderer module.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 1 (enabled) and can be changed at runtime or through configuration files.

The associated variable GLumenReflectionTraceCompactionWaveOps directly interacts with this setting. They share the same value, with the console variable (CVarLumenReflectionTraceCompactionWaveOps) controlling the associated C++ variable.

Developers must be aware that this setting is only effective when certain hardware conditions are met. As seen in the code, the use of Wave Operations is contingent on:

1. The setting being enabled (GLumenReflectionTraceCompactionWaveOps != 0)
2. The hardware supporting Wave Operations (GRHISupportsWaveOperations)
3. The minimum and maximum wave sizes being compatible (GRHIMinimumWaveSize <= 32 && GRHIMaximumWaveSize >= 32)
4. The current shader platform supporting Wave Operations

Best practices when using this variable include:

1. Ensuring that target hardware supports Wave Operations before relying on this feature.
2. Testing performance with and without this feature enabled, as the impact may vary depending on the specific scene and hardware.
3. Being aware that disabling this feature may affect the coherency of traces, which might impact performance or visual quality.

Regarding the associated variable GLumenReflectionTraceCompactionWaveOps:

• Its purpose is to store the actual boolean value used in the code to determine if Wave Operations should be used for trace compaction.
• It’s used directly in the LumenReflections::CompactTraces function to determine the compaction method.
• Its value is set by the console variable system, allowing for runtime configuration.
• Developers should be aware that changing this variable directly in code won’t have an effect unless the console variable is also updated.
• Best practice is to use the console variable (r.Lumen.Reflections.TraceCompaction.WaveOps) to modify this setting rather than changing the GLumenReflectionTraceCompactionWaveOps variable directly.

#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:79

Scope: file

Source code excerpt:

int32 GLumenReflectionTraceCompactionWaveOps = 1;
FAutoConsoleVariableRef CVarLumenReflectionTraceCompactionWaveOps(
	TEXT("r.Lumen.Reflections.TraceCompaction.WaveOps"),
	GLumenReflectionTraceCompactionWaveOps,
	TEXT("Whether to use Wave Ops path for trace compaction."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionsSampleSceneColorAtHit = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReflectionTraceCompactionWaveOps = 1;
FAutoConsoleVariableRef CVarLumenReflectionTraceCompactionWaveOps(
	TEXT("r.Lumen.Reflections.TraceCompaction.WaveOps"),
	GLumenReflectionTraceCompactionWaveOps,
	TEXT("Whether to use Wave Ops path for trace compaction."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionsSampleSceneColorAtHit = 1;
FAutoConsoleVariableRef CVarLumenReflectionsSampleSceneColorAtHit(

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

Scope (from outer to inner):

file
function     FCompactedReflectionTraceParameters LumenReflections::CompactTraces

Source code excerpt:

	FRDGBufferRef CompactedTraceTexelData = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateBufferDesc(sizeof(uint32), NumCompactedTraceTexelDataElements), TEXT("Lumen.Reflections.CompactedTraceTexelData"));

	const bool bWaveOps = GLumenReflectionTraceCompactionWaveOps != 0 
		&& GRHISupportsWaveOperations 
		&& GRHIMinimumWaveSize <= 32 
		&& GRHIMaximumWaveSize >= 32
		&& RHISupportsWaveOperations(View.GetShaderPlatform());

	// Only the wave ops path maintains trace order, switch to smaller groups without it to preserve coherency in the traces