r.Lumen.ScreenProbeGather.GatherNumMips

r.Lumen.ScreenProbeGather.GatherNumMips

#Overview

name: r.Lumen.ScreenProbeGather.GatherNumMips

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.GatherNumMips is to control the number of mip maps prepared for diffuse integration in the Lumen lighting system of Unreal Engine 5. This setting is specifically related to the screen probe gather process, which is a part of Lumen’s real-time global illumination solution.

This setting variable is primarily used in the Lumen rendering subsystem, specifically in the screen probe gathering and filtering modules. It’s referenced in files such as LumenScreenProbeFiltering.cpp and LumenScreenProbeGather.cpp, which are part of the Renderer module.

The value of this variable is set through an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands or configuration files. It’s initialized with a default value of 1.

The associated variable GLumenScreenProbeGatherNumMips directly interacts with r.Lumen.ScreenProbeGather.GatherNumMips. They share the same value, with GLumenScreenProbeGatherNumMips being the actual integer variable used in the C++ code.

Developers should be aware that this variable affects the quality and performance of Lumen’s screen probe gather process. Increasing the number of mip maps can potentially improve the quality of diffuse lighting integration but may also increase memory usage and processing time.

Best practices when using this variable include:

  1. Balancing quality and performance by adjusting the mip map count.
  2. Testing different values to find the optimal setting for your specific scene and performance requirements.
  3. Being mindful of potential memory implications when increasing the mip map count.

Regarding the associated variable GLumenScreenProbeGatherNumMips:

The purpose of GLumenScreenProbeGatherNumMips is to store and provide access to the number of mip maps used in the screen probe gather process within the C++ code of the Lumen system.

This variable is used in various parts of the Lumen rendering system, particularly in the screen probe filtering and gathering processes. It’s used to determine buffer sizes, loop iterations for mip level generation, and other calculations related to screen probe processing.

The value of GLumenScreenProbeGatherNumMips is set through the r.Lumen.ScreenProbeGather.GatherNumMips console variable.

GLumenScreenProbeGatherNumMips interacts directly with r.Lumen.ScreenProbeGather.GatherNumMips and is used in calculations involving other Lumen-related variables and parameters.

Developers should be aware that changes to this variable will affect various aspects of the screen probe gather process, including texture sizes and processing steps.

Best practices for using GLumenScreenProbeGatherNumMips include:

  1. Ensuring that any code using this variable can handle different mip map counts.
  2. Considering the performance implications when using this variable in loops or calculations.
  3. Documenting any assumptions about the range of values this variable might take in your code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherNumMips = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherNumMips(
	TEXT("r.Lumen.ScreenProbeGather.GatherNumMips"),
	GLumenScreenProbeGatherNumMips,
	TEXT("Number of mip maps to prepare for diffuse integration"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherMaxRayIntensity = 40;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherNumMips = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherNumMips(
	TEXT("r.Lumen.ScreenProbeGather.GatherNumMips"),
	GLumenScreenProbeGatherNumMips,
	TEXT("Number of mip maps to prepare for diffuse integration"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherMaxRayIntensity = 40;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherMaxRayIntensity(

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

Scope (from outer to inner):

file
function     void FilterScreenProbes

Source code excerpt:

	{
		const FIntPoint ScreenProbeGatherWithBorderBufferSize = ScreenProbeParameters.ScreenProbeAtlasBufferSize * ScreenProbeParameters.ScreenProbeGatherOctahedronResolutionWithBorder;
		FRDGTextureDesc ScreenProbeRadianceWithBorderDesc(FRDGTextureDesc::Create2D(ScreenProbeGatherWithBorderBufferSize, PF_FloatRGB, FClearValueBinding::Black, TexCreate_ShaderResource | TexCreate_UAV, GLumenScreenProbeGatherNumMips));
		ScreenProbeRadianceWithBorder = GraphBuilder.CreateTexture(ScreenProbeRadianceWithBorderDesc, TEXT("Lumen.ScreenProbeGather.ScreenProbeFilteredRadianceWithBorder"));

		FScreenProbeFixupBordersCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FScreenProbeFixupBordersCS::FParameters>();
		PassParameters->RWScreenProbeRadiance = GraphBuilder.CreateUAV(FRDGTextureUAVDesc(ScreenProbeRadianceWithBorder));
		PassParameters->ScreenProbeRadiance = ScreenProbeRadiance;
		PassParameters->ScreenProbeParameters = ScreenProbeParameters;

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

Scope (from outer to inner):

file
function     void FilterScreenProbes

Source code excerpt:

	}

	for (int32 MipLevel = 1; MipLevel < GLumenScreenProbeGatherNumMips; MipLevel++)
	{
		FScreenProbeGenerateMipLevelCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FScreenProbeGenerateMipLevelCS::FParameters>();
		PassParameters->RWScreenProbeRadianceWithBorderMip = GraphBuilder.CreateUAV(FRDGTextureUAVDesc(ScreenProbeRadianceWithBorder, MipLevel));
		PassParameters->ScreenProbeRadianceWithBorderParentMip = GraphBuilder.CreateSRV(FRDGTextureSRVDesc::CreateForMipLevel(ScreenProbeRadianceWithBorder, MipLevel - 1));
		PassParameters->MipLevel = MipLevel;
		PassParameters->ScreenProbeParameters = ScreenProbeParameters;

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenScreenProbeGather

Source code excerpt:

	ensureMsgf(ScreenProbeParameters.ScreenProbeTracingOctahedronResolution < (1 << 6) - 1, TEXT("Tracing resolution %u was larger than supported by PackRayInfo()"), ScreenProbeParameters.ScreenProbeTracingOctahedronResolution);
	ScreenProbeParameters.ScreenProbeGatherOctahedronResolution = LumenScreenProbeGather::GetGatherOctahedronResolution(ScreenProbeParameters.ScreenProbeTracingOctahedronResolution);
	ScreenProbeParameters.ScreenProbeGatherOctahedronResolutionWithBorder = ScreenProbeParameters.ScreenProbeGatherOctahedronResolution + 2 * (1 << (GLumenScreenProbeGatherNumMips - 1));
	ScreenProbeParameters.ScreenProbeDownsampleFactor = LumenScreenProbeGather::GetScreenDownsampleFactor(View);

	ScreenProbeParameters.ScreenProbeLightSampleResolutionXY = FMath::Clamp<uint32>(GLumenScreenProbeLightSampleResolutionXY, 1, 8);

	ScreenProbeParameters.ScreenProbeViewSize = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), (int32)ScreenProbeParameters.ScreenProbeDownsampleFactor);
	ScreenProbeParameters.ScreenProbeAtlasViewSize = ScreenProbeParameters.ScreenProbeViewSize;

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenScreenProbeGather

Source code excerpt:

	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;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.h:18

Scope: file

Source code excerpt:

}

extern int32 GLumenScreenProbeGatherNumMips;

// Must match LumenScreenProbeCommon.ush
enum class EScreenProbeIrradianceFormat : uint8
{
	SH3,
	Octahedral,