r.RayTracing.LightGridMaxCount

r.RayTracing.LightGridMaxCount

#Overview

name: r.RayTracing.LightGridMaxCount

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.RayTracing.LightGridMaxCount is to control the maximum number of lights per cell in the 2D light grid used for ray tracing lighting calculations in Unreal Engine 5.

This setting variable is primarily used by the Rendering system, specifically in the Ray Tracing subsystem. It is referenced in the RayTracingLighting.cpp file, which is part of the Renderer module.

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

The associated variable CVarRayTracingLightGridMaxCount directly interacts with r.RayTracing.LightGridMaxCount, as they share the same value and purpose.

Developers must be aware that this variable affects the performance and quality of ray-traced lighting. A higher value allows for more lights per cell, potentially increasing lighting accuracy but at the cost of performance. Conversely, a lower value may improve performance but could result in less accurate lighting in complex scenes.

Best practices when using this variable include:

  1. Adjusting the value based on the complexity of the scene and the number of lights present.
  2. Balancing between performance and visual quality.
  3. Testing different values to find the optimal setting for specific scenes or use cases.
  4. Considering the target hardware capabilities when setting this value.

Regarding the associated variable CVarRayTracingLightGridMaxCount:

This is an auto console variable of type int32 that directly controls the r.RayTracing.LightGridMaxCount setting. It is defined in the same file (RayTracingLighting.cpp) and is used to implement the functionality of the setting.

The value of CVarRayTracingLightGridMaxCount is accessed in the PrepareLightGrid function, where it is used to determine the maximum number of lights per cell in the light grid. The actual value used is clamped between 1 and the total number of finite lights in the scene, ensuring that the setting remains within practical limits.

When working with this variable, developers should be aware that changes to CVarRayTracingLightGridMaxCount will directly affect the behavior of the ray tracing light grid system. It’s important to consider the performance implications of modifying this value, especially in scenes with a large number of lights.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingLighting.cpp:26

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarRayTracingLightGridMaxCount(
	TEXT("r.RayTracing.LightGridMaxCount"),
	128,
	TEXT("Controls the maximum number of lights per cell in the 2D light grid. The minimum of this value and the number of lights in the scene is used. (default = 128)\n"),
	ECVF_RenderThreadSafe
);

IMPLEMENT_GLOBAL_SHADER_PARAMETER_STRUCT(FRayTracingLightGrid, "RaytracingLightGridData");

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingLighting.cpp:25

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarRayTracingLightGridMaxCount(
	TEXT("r.RayTracing.LightGridMaxCount"),
	128,
	TEXT("Controls the maximum number of lights per cell in the 2D light grid. The minimum of this value and the number of lights in the scene is used. (default = 128)\n"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingLighting.cpp:156

Scope (from outer to inner):

file
function     static void PrepareLightGrid

Source code excerpt:


	const uint32 Resolution = FMath::RoundUpToPowerOfTwo(CVarRayTracingLightGridResolution.GetValueOnRenderThread());
	const uint32 MaxCount = FMath::Clamp(CVarRayTracingLightGridMaxCount.GetValueOnRenderThread(), 1, NumFiniteLights);
	LightGridParameters->LightGridResolution = Resolution;
	LightGridParameters->LightGridMaxCount = MaxCount;

	// pick the shortest axis
	FVector3f Diag = LightGridParameters->SceneLightsTranslatedBoundMax - LightGridParameters->SceneLightsTranslatedBoundMin;
	if (Diag.X < Diag.Y && Diag.X < Diag.Z)