r.ManyLights

r.ManyLights

#Overview

name: r.ManyLights

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

• type: Var
• help: Whether to enable Many Lights. Experimental feature leveraging ray tracing to stochastically importance sample lights.\n1 - all lights using ray tracing shadows will be stochastically sampled\n2 - all lights will be stochastically sampled

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ManyLights is to enable an experimental feature that leverages ray tracing to stochastically importance sample lights in the rendering system. This setting allows developers to control the extent of stochastic light sampling in the scene.

This setting variable is primarily used in the rendering subsystem of Unreal Engine 5, specifically in the Many Lights module. It’s implemented in the Renderer module, as evidenced by its location in the ‘ManyLights.cpp’ file within the Renderer’s private directory.

The value of this variable is set through the console variable system (CVarManyLights). It can take three values: 0 - Disabled (default) 1 - All lights using ray tracing shadows will be stochastically sampled 2 - All lights will be stochastically sampled

The associated variable CVarManyLights interacts directly with r.ManyLights, as they share the same value. This variable is used in the code to check the current state of the Many Lights feature.

Developers must be aware that this is an experimental feature and may impact performance. They should also note that the behavior changes based on the value set:

• At value 1, only lights with ray-traced shadows are affected
• At value 2, all lights are affected, regardless of their shadow settings

Best practices when using this variable include:

1. Testing thoroughly in various lighting scenarios to ensure desired results
2. Monitoring performance impact, especially when set to 2
3. Using in conjunction with other ray tracing settings for optimal results
4. Considering the impact on different hardware capabilities

Regarding the associated variable CVarManyLights:

• It’s a TAutoConsoleVariable, which means it’s an integer console variable
• It’s used to check if the Many Lights feature is enabled (IsEnabled() function)
• It’s also used to determine if a specific light should be supported by this feature (IsLightSupported function)
• When working with this variable, developers should use the GetValueOnRenderThread() method to ensure thread-safe access to its value

Developers should be cautious when modifying or relying on CVarManyLights directly, as it’s tightly coupled with the r.ManyLights setting. Any changes to one should be reflected in the other to maintain consistency in the rendering system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLights.cpp:7

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarManyLights(
	TEXT("r.ManyLights"),
	0,
	TEXT("Whether to enable Many Lights. Experimental feature leveraging ray tracing to stochastically importance sample lights.\n")
	TEXT("1 - all lights using ray tracing shadows will be stochastically sampled\n")
	TEXT("2 - all lights will be stochastically sampled"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLights.cpp:6

Scope: file

Source code excerpt:

#include "BasePassRendering.h"

static TAutoConsoleVariable<int32> CVarManyLights(
	TEXT("r.ManyLights"),
	0,
	TEXT("Whether to enable Many Lights. Experimental feature leveraging ray tracing to stochastically importance sample lights.\n")
	TEXT("1 - all lights using ray tracing shadows will be stochastically sampled\n")
	TEXT("2 - all lights will be stochastically sampled"),
	ECVF_Scalability | ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLights.cpp:152

Scope (from outer to inner):

file
namespace    ManyLights
function     bool IsEnabled

Source code excerpt:

	bool IsEnabled()
	{
		return CVarManyLights.GetValueOnRenderThread() != 0;
	}

	bool IsUsingLightFunctions()
	{
		return IsEnabled() && CVarManyLightsLightFunctions.GetValueOnRenderThread() != 0;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLights.cpp:165

Scope (from outer to inner):

file
namespace    ManyLights
function     bool IsLightSupported

Source code excerpt:

		{
			const bool bRayTracedShadows = (CastRayTracedShadow == ECastRayTracedShadow::Enabled || (ShouldRenderRayTracingShadows() && CastRayTracedShadow == ECastRayTracedShadow::UseProjectSetting));
			return CVarManyLights.GetValueOnRenderThread() == 2 || bRayTracedShadows;
		}

		return false;
	}

	bool ShouldCompileShaders(const FGlobalShaderPermutationParameters& Parameters)