r.Lumen.ScreenProbeGather.AdaptiveProbeAllocationFraction

r.Lumen.ScreenProbeGather.AdaptiveProbeAllocationFraction

#Overview

name: r.Lumen.ScreenProbeGather.AdaptiveProbeAllocationFraction

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.ScreenProbeGather.AdaptiveProbeAllocationFraction is to control the fraction of uniform probes allocated for adaptive probe placement in Lumen’s screen probe gathering system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically the screen probe gathering component.

This setting variable is primarily used in the Renderer module, particularly in the Lumen subsystem. It’s referenced in the LumenScreenProbeGather.cpp file, which is responsible for handling screen probe gathering in the Lumen global illumination system.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be adjusted at runtime through the console or configuration files. It’s initialized with a default value of 0.5 (50%).

The associated variable GLumenScreenProbeGatherAdaptiveProbeAllocationFraction directly interacts with this console variable. They share the same value, with the console variable controlling the C++ variable.

Developers must be aware that this variable affects the balance between uniform and adaptive probe placement. A higher value allows for more adaptive probes, which can potentially improve lighting quality in complex scenes but may also increase computational cost.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of your scene. More complex scenes with varying lighting conditions might benefit from a higher value.
  2. Monitoring performance impact when increasing this value, as it could affect rendering time.
  3. Using it in conjunction with other Lumen settings to achieve the best balance between quality and performance.

Regarding the associated variable GLumenScreenProbeGatherAdaptiveProbeAllocationFraction:

When working with this variable, it’s important to consider the trade-offs between lighting quality, performance, and memory usage, and to test thoroughly with different values to find the optimal setting for your specific use case.

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

Scope: file

Source code excerpt:

float GLumenScreenProbeGatherAdaptiveProbeAllocationFraction = .5f;
FAutoConsoleVariableRef GVarAdaptiveProbeAllocationFraction(
	TEXT("r.Lumen.ScreenProbeGather.AdaptiveProbeAllocationFraction"),
	GLumenScreenProbeGatherAdaptiveProbeAllocationFraction,
	TEXT("Fraction of uniform probes to allow for adaptive probe placement."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherReferenceMode = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenScreenProbeGatherAdaptiveProbeAllocationFraction = .5f;
FAutoConsoleVariableRef GVarAdaptiveProbeAllocationFraction(
	TEXT("r.Lumen.ScreenProbeGather.AdaptiveProbeAllocationFraction"),
	GLumenScreenProbeGatherAdaptiveProbeAllocationFraction,
	TEXT("Fraction of uniform probes to allow for adaptive probe placement."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherReferenceMode = 0;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherReferenceMode(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenScreenProbeGather

Source code excerpt:

	ScreenProbeParameters.ScreenProbeViewSize = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), (int32)ScreenProbeParameters.ScreenProbeDownsampleFactor);
	ScreenProbeParameters.ScreenProbeAtlasViewSize = ScreenProbeParameters.ScreenProbeViewSize;
	ScreenProbeParameters.ScreenProbeAtlasViewSize.Y += FMath::TruncToInt(ScreenProbeParameters.ScreenProbeViewSize.Y * GLumenScreenProbeGatherAdaptiveProbeAllocationFraction);

	ScreenProbeParameters.ScreenProbeAtlasBufferSize = FIntPoint::DivideAndRoundUp(SceneTextures.Config.Extent, (int32)ScreenProbeParameters.ScreenProbeDownsampleFactor);
	ScreenProbeParameters.ScreenProbeAtlasBufferSize.Y += FMath::TruncToInt(ScreenProbeParameters.ScreenProbeAtlasBufferSize.Y * GLumenScreenProbeGatherAdaptiveProbeAllocationFraction);

	ScreenProbeParameters.ScreenProbeGatherMaxMip = GLumenScreenProbeGatherNumMips - 1;
	ScreenProbeParameters.RelativeSpeedDifferenceToConsiderLightingMoving = GLumenScreenProbeRelativeSpeedDifferenceToConsiderLightingMoving;
	ScreenProbeParameters.ScreenTraceNoFallbackThicknessScale = (Lumen::UseHardwareRayTracedScreenProbeGather(ViewFamily) ? 1.0f : GLumenScreenProbeScreenTracesThicknessScaleWhenNoFallback) * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
	ScreenProbeParameters.NumUniformScreenProbes = ScreenProbeParameters.ScreenProbeViewSize.X * ScreenProbeParameters.ScreenProbeViewSize.Y;
	ScreenProbeParameters.MaxNumAdaptiveProbes = FMath::TruncToInt(ScreenProbeParameters.NumUniformScreenProbes * GLumenScreenProbeGatherAdaptiveProbeAllocationFraction);
	
	ScreenProbeParameters.FixedJitterIndex = GLumenScreenProbeFixedJitterIndex;

	{
		FVector2f InvAtlasWithBorderBufferSize = FVector2f(1.0f) / (FVector2f(ScreenProbeParameters.ScreenProbeGatherOctahedronResolutionWithBorder) * FVector2f(ScreenProbeParameters.ScreenProbeAtlasBufferSize));
		ScreenProbeParameters.SampleRadianceProbeUVMul = FVector2f(ScreenProbeParameters.ScreenProbeGatherOctahedronResolution) * InvAtlasWithBorderBufferSize;