r.Lumen.ScreenProbeGather.InjectLightsToProbes

r.Lumen.ScreenProbeGather.InjectLightsToProbes

#Overview

name: r.Lumen.ScreenProbeGather.InjectLightsToProbes

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.InjectLightsToProbes is to control whether local lights are injected into screen probes in the Lumen lighting system. This setting is part of Unreal Engine 5’s rendering system, specifically the Lumen global illumination feature.

This setting variable is primarily used in the Lumen Screen Probe Gather and Filtering subsystems of Unreal Engine 5. It’s referenced in the Renderer module, particularly in the Lumen-related source files.

The value of this variable is set through a console variable (cvar) system. It’s initialized to 0 and can be changed at runtime using the console command “r.Lumen.ScreenProbeGather.InjectLightsToProbes”.

This variable interacts closely with its associated C++ variable GLumenScreenProbeInjectLightsToProbes. They share the same value and are used interchangeably in the code.

Developers must be aware that this feature is experimental. While it can potentially improve performance by injecting local lights into probes, it can cause visual artifacts such as wrap-around lighting due to lack of directionality and spherical harmonics (SH) ringing.

Best practices when using this variable include:

  1. Use it cautiously, as it’s marked experimental.
  2. Monitor the visual quality of the lighting when enabled, looking out for wrap-around lighting artifacts.
  3. Consider the performance implications in your specific use case.

Regarding the associated variable GLumenScreenProbeInjectLightsToProbes:

The purpose of GLumenScreenProbeInjectLightsToProbes is to serve as the C++ representation of the r.Lumen.ScreenProbeGather.InjectLightsToProbes console variable. It’s used directly in the C++ code to control the behavior of light injection into screen probes.

This variable is used in the Lumen Screen Probe Gather and Filtering systems, specifically in the functions related to screen probe integration and filtering.

Its value is set by the console variable system and can be changed at runtime.

It interacts directly with shader permutations and pass parameters in the screen probe integration process.

Developers should be aware that this variable directly affects the shader compilation and execution paths in the screen probe integration process.

Best practices include:

  1. Ensure consistency between the console variable and this C++ variable.
  2. When modifying related code, check the impact on both the console variable and this C++ variable.
  3. Consider the performance and visual quality trade-offs when enabling or disabling this feature in different scenarios.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:99

Scope: file

Source code excerpt:

int32 GLumenScreenProbeInjectLightsToProbes = 0;
FAutoConsoleVariableRef CVarLumenScreenProbeInjectLightsToProbes(
	TEXT("r.Lumen.ScreenProbeGather.InjectLightsToProbes"),
	GLumenScreenProbeInjectLightsToProbes,
	TEXT("Whether to inject local lights into probes.  Experimental - fast but causes wrap-around lighting due to lack of directionality and SH ringing."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeFullResolutionJitterWidth = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeFiltering.cpp:591

Scope (from outer to inner):

file
function     void FilterScreenProbes

Source code excerpt:

	}

	extern int32 GLumenScreenProbeInjectLightsToProbes;
	if (bRenderDirectLighting && GLumenScreenProbeInjectLightsToProbes != 0)
	{
		FRDGTextureRef ScreenProbeRadianceWithLightsInjected = GraphBuilder.CreateTexture(ScreenProbeRadianceDesc, TEXT("Lumen.ScreenProbeGather.ScreenProbeRadianceWithLightsInjected"));

		FScreenProbeInjectLightSamplesCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FScreenProbeInjectLightSamplesCS::FParameters>();
		PassParameters->RWScreenProbeRadiance = GraphBuilder.CreateUAV(FRDGTextureUAVDesc(ScreenProbeRadianceWithLightsInjected));
		PassParameters->ScreenProbeRadiance = ScreenProbeRadiance;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:97

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeInjectLightsToProbes = 0;
FAutoConsoleVariableRef CVarLumenScreenProbeInjectLightsToProbes(
	TEXT("r.Lumen.ScreenProbeGather.InjectLightsToProbes"),
	GLumenScreenProbeInjectLightsToProbes,
	TEXT("Whether to inject local lights into probes.  Experimental - fast but causes wrap-around lighting due to lack of directionality and SH ringing."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeFullResolutionJitterWidth = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeFullResolutionJitterWidth(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:1277

Scope (from outer to inner):

file
function     void InterpolateAndIntegrate
lambda-function

Source code excerpt:

				PermutationVector.Set< FScreenProbeIntegrateCS::FProbeIrradianceFormat >(LumenScreenProbeGather::GetScreenProbeIrradianceFormat(View.Family->EngineShowFlags));
				PermutationVector.Set< FScreenProbeIntegrateCS::FStochasticProbeInterpolation >(GLumenScreenProbeStochasticInterpolation != 0);
				PermutationVector.Set< FScreenProbeIntegrateCS::FDirectLighting >(bRenderDirectLighting && !GLumenScreenProbeInjectLightsToProbes);
				PermutationVector.Set< FScreenProbeIntegrateCS::FSupportBackfaceDiffuse >(bSupportBackfaceDiffuse);
				PermutationVector.Set< FScreenProbeIntegrateCS::FRoughSpecularSamplingMode >(RoughSpecularSamplingMode);
				auto ComputeShader = View.ShaderMap->GetShader<FScreenProbeIntegrateCS>(PermutationVector);

				FComputeShaderUtils::AddPass(
					GraphBuilder,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:1344

Scope (from outer to inner):

file
function     void InterpolateAndIntegrate
lambda-function

Source code excerpt:

			PermutationVector.Set< FScreenProbeIntegrateCS::FProbeIrradianceFormat >(LumenScreenProbeGather::GetScreenProbeIrradianceFormat(View.Family->EngineShowFlags));
			PermutationVector.Set< FScreenProbeIntegrateCS::FStochasticProbeInterpolation >(GLumenScreenProbeStochasticInterpolation != 0);
			PermutationVector.Set< FScreenProbeIntegrateCS::FDirectLighting >(bRenderDirectLighting && !GLumenScreenProbeInjectLightsToProbes);
			PermutationVector.Set< FScreenProbeIntegrateCS::FSupportBackfaceDiffuse >(bSupportBackfaceDiffuse);
			PermutationVector.Set< FScreenProbeIntegrateCS::FRoughSpecularSamplingMode >(RoughSpecularSamplingMode);
			auto ComputeShader = View.ShaderMap->GetShader<FScreenProbeIntegrateCS>(PermutationVector);

			const FIntPoint DispatchViewRect = View.ViewRect.Size();
			FIntVector DispatchCount = FComputeShaderUtils::GetGroupCount(DispatchViewRect, GScreenProbeIntegrateTileSize);