r.RayTracing.LightGridResolution

r.RayTracing.LightGridResolution

#Overview

name: r.RayTracing.LightGridResolution

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.LightGridResolution is to control the resolution of the 2D light grid used for culling irrelevant lights in ray tracing lighting calculations. This setting variable is part of Unreal Engine 5’s ray tracing system, which is a key component of the rendering pipeline.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, specifically the ray tracing lighting component. This can be seen from the file path where the variable is defined: Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingLighting.cpp.

The value of this variable is set as a console variable with a default value of 256. It can be modified at runtime through the console or programmatically.

This variable interacts with another variable named CVarRayTracingLightGridMaxCount, which is used together to configure the light grid parameters for ray tracing.

Developers must be aware that this variable directly affects the performance and quality of ray-traced lighting in the scene. A higher resolution may provide more accurate light culling but at the cost of increased memory usage and potentially lower performance.

Best practices when using this variable include:

  1. Balancing between quality and performance by adjusting the resolution based on the scene complexity and available hardware resources.
  2. Ensuring the value is a power of two for optimal performance, as evidenced by the FMath::RoundUpToPowerOfTwo() function used in the code.
  3. Considering the relationship between this variable and CVarRayTracingLightGridMaxCount to achieve the best light culling results.

Regarding the associated variable CVarRayTracingLightGridResolution:

The purpose of CVarRayTracingLightGridResolution is the same as r.RayTracing.LightGridResolution, as they share the same value. It’s an internal representation of the console variable within the engine’s code.

This variable is used directly in the PrepareLightGrid function to set up the light grid parameters for ray tracing. It’s retrieved using the GetValueOnRenderThread() method, indicating that it’s accessed on the render thread for thread-safe operations.

Developers should be aware that modifying r.RayTracing.LightGridResolution will affect CVarRayTracingLightGridResolution, and vice versa. When working with ray tracing lighting in Unreal Engine 5, it’s important to use the console variable (r.RayTracing.LightGridResolution) for external configuration and rely on CVarRayTracingLightGridResolution for internal engine logic.

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarRayTracingLightGridResolution(
	TEXT("r.RayTracing.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> CVarRayTracingLightGridMaxCount(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarRayTracingLightGridResolution(
	TEXT("r.RayTracing.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/RayTracing/RayTracingLighting.cpp:155

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;