r.PathTracing.LightGridResolution

r.PathTracing.LightGridResolution

#Overview

name: r.PathTracing.LightGridResolution

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

• type: Var
• help: Controls the resolution of the 2D light grid used to cull irrelevant lights from lighting calculations (default = 256)\n

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PathTracing.LightGridResolution is to control the resolution of the 2D light grid used in path tracing for culling irrelevant lights from lighting calculations. This setting variable is part of Unreal Engine 5’s rendering system, specifically the path tracing module.

The path tracing subsystem within the Renderer module relies on this setting variable. It is used in the PathTracing.cpp file, which is responsible for implementing path tracing functionality in Unreal Engine 5.

The value of this variable is set through a console variable (CVarPathTracingLightGridResolution) with a default value of 256. It can be modified at runtime using console commands or through engine configuration files.

This variable interacts closely with another variable called CVarPathTracingLightGridMaxCount, which sets the maximum number of lights to consider in the light grid.

Developers must be aware that this variable affects the performance and quality of path tracing. A higher resolution provides more accurate light culling but requires more memory and computation. The value is always rounded up to the nearest power of two for efficiency.

Best practices when using this variable include:

1. Adjusting it based on the scene complexity and lighting requirements.
2. Balancing it with CVarPathTracingLightGridMaxCount for optimal performance.
3. Testing different values to find the best trade-off between quality and performance for your specific scene.

Regarding the associated variable CVarPathTracingLightGridResolution:

This is the actual console variable that stores and manages the r.PathTracing.LightGridResolution value. It is defined as a TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime through console commands.

The purpose of CVarPathTracingLightGridResolution is to provide a way to access and modify the light grid resolution setting from within the engine code and through the console.

This variable is used in the PrepareLightGrid function and when setting up the path tracing configuration. It’s important to note that the value is always rounded up to the nearest power of two when used, which ensures efficient memory usage and computation.

Developers should be aware that changes to this console variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag used in its definition.

Best practices for using CVarPathTracingLightGridResolution include:

1. Using GetValueOnRenderThread() when accessing its value in render thread code.
2. Considering the performance implications when changing this value dynamically during gameplay.
3. Documenting any non-default values used in your project for easier maintenance and optimization.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:259

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarPathTracingLightGridResolution(
	TEXT("r.PathTracing.LightGridResolution"),
	256,
	TEXT("Controls the resolution of the 2D light grid used to cull irrelevant lights from lighting calculations (default = 256)\n"),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarPathTracingLightGridMaxCount(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:258

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingLightGridResolution(
	TEXT("r.PathTracing.LightGridResolution"),
	256,
	TEXT("Controls the resolution of the 2D light grid used to cull irrelevant lights from lighting calculations (default = 256)\n"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:1946

Scope (from outer to inner):

file
function     void PrepareLightGrid

Source code excerpt:

		}

		const uint32 Resolution = FMath::RoundUpToPowerOfTwo(CVarPathTracingLightGridResolution.GetValueOnRenderThread());
		const uint32 MaxCount = FMath::Clamp(
			CVarPathTracingLightGridMaxCount.GetValueOnRenderThread(),
			1,
			FMath::Min(NumFiniteLights, RAY_TRACING_LIGHT_COUNT_MAXIMUM)
		);
		LightGridParameters->LightGridResolution = Resolution;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:2513

Scope: file

Source code excerpt:

	Config.ViewRect = View.ViewRect;

	Config.LightGridResolution = FMath::RoundUpToPowerOfTwo(CVarPathTracingLightGridResolution.GetValueOnRenderThread());
	Config.LightGridMaxCount = FMath::Clamp(CVarPathTracingLightGridMaxCount.GetValueOnRenderThread(), 1, RAY_TRACING_LIGHT_COUNT_MAXIMUM);

	Config.PathTracingData.MaxSamples = MaxSPP;

	bool FirstTime = false;
	if (!View.ViewState->PathTracingState.IsValid())