r.Lumen.ReSTIRGather.MaxRayIntensity

r.Lumen.ReSTIRGather.MaxRayIntensity

#Overview

name: r.Lumen.ReSTIRGather.MaxRayIntensity

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

• type: Var
• help: Clamps the maximum ray lighting intensity (with PreExposure) to reduce fireflies.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ReSTIRGather.MaxRayIntensity is to control the maximum ray lighting intensity in Lumen’s ReSTIR (Resampled Importance Sampling for Real-Time Ray Tracing) gather process. This setting is part of Unreal Engine 5’s Lumen global illumination system and is specifically used to reduce fireflies (bright specks) in the rendered image.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the LumenReSTIRGather.cpp file, which is part of the renderer’s implementation of Lumen’s ReSTIR gathering process.

The value of this variable is set through the engine’s console variable system. It’s initialized with a default value of 100 and can be modified at runtime using the console command “r.Lumen.ReSTIRGather.MaxRayIntensity”.

The associated variable GLumenReSTIRMaxRayIntensity directly interacts with r.Lumen.ReSTIRGather.MaxRayIntensity. They share the same value, with GLumenReSTIRMaxRayIntensity being the actual float variable used in the C++ code to apply the clamping.

Developers should be aware that this variable affects the visual quality of the rendered image, particularly in scenes with high dynamic range lighting. Setting it too low might reduce fireflies but could also clamp legitimate bright areas, while setting it too high might not effectively reduce fireflies.

Best practices when using this variable include:

1. Adjusting it based on the specific lighting conditions of your scene.
2. Testing different values to find the right balance between firefly reduction and preserving bright highlights.
3. Considering the impact on performance, as very high values might require more computation.

Regarding the associated variable GLumenReSTIRMaxRayIntensity:

• Its purpose is to store the actual value used in the rendering calculations.
• It’s used directly in the Lumen ReSTIR gather process, specifically in the RenderLumenReSTIRGather function.
• Its value is set by the console variable system and can be modified at runtime.
• It interacts directly with the r.Lumen.ReSTIRGather.MaxRayIntensity console variable.
• Developers should be aware that modifying GLumenReSTIRMaxRayIntensity directly in code is not recommended; instead, they should use the console variable for changes.
• Best practice is to treat GLumenReSTIRMaxRayIntensity as a read-only variable in most scenarios, relying on the console variable system for modifications.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReSTIRGather.cpp:138

Scope: file

Source code excerpt:

float GLumenReSTIRMaxRayIntensity = 100;
FAutoConsoleVariableRef CVarLumenReSTIRMaxRayIntensity(
	TEXT("r.Lumen.ReSTIRGather.MaxRayIntensity"),
	GLumenReSTIRMaxRayIntensity,
	TEXT("Clamps the maximum ray lighting intensity (with PreExposure) to reduce fireflies."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRUpsampleMethod = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReSTIRGather.cpp:136

Scope: file

Source code excerpt:

);

float GLumenReSTIRMaxRayIntensity = 100;
FAutoConsoleVariableRef CVarLumenReSTIRMaxRayIntensity(
	TEXT("r.Lumen.ReSTIRGather.MaxRayIntensity"),
	GLumenReSTIRMaxRayIntensity,
	TEXT("Clamps the maximum ray lighting intensity (with PreExposure) to reduce fireflies."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRUpsampleMethod = 1;
FAutoConsoleVariableRef CVarLumenReSTIRUpsampleMethod(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReSTIRGather.cpp:1007

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

				Parameters->ApplySkyLight = 1;
				Parameters->MaxTraceDistance = Lumen::GetMaxTraceDistance(View);
				Parameters->MaxRayIntensity = GLumenReSTIRMaxRayIntensity;
			}

			const bool bUseHitLighting = LumenReflections::UseHitLighting(View, true);
			const bool bUseMinimalPayload = !bUseHitLighting;

			FLumenValidateReservoirsRGS::FPermutationDomain PermutationVector;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReSTIRGather.cpp:1046

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

			Parameters->ApplySkyLight = 1;
			Parameters->MaxTraceDistance = Lumen::GetMaxTraceDistance(View);
			Parameters->MaxRayIntensity = GLumenReSTIRMaxRayIntensity;
		}

		const bool bUseHitLighting = LumenReflections::UseHitLighting(View, true);
		const bool bUseMinimalPayload = !bUseHitLighting;

		FLumenInitialSamplingRGS::FPermutationDomain PermutationVector;