r.ManyLights.NumSamplesPerPixel

r.ManyLights.NumSamplesPerPixel

#Overview

name: r.ManyLights.NumSamplesPerPixel

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.ManyLights.NumSamplesPerPixel is to control the number of samples (shadow rays) per half-resolution pixel in the Many Lights rendering system of Unreal Engine 5.

This setting variable is primarily used by the rendering system, specifically the Many Lights module, which is responsible for efficient rendering of scenes with numerous light sources.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by its location in the ManyLights.cpp file within the Runtime/Renderer/Private/ManyLights directory.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 4, but can be changed at runtime or through configuration files.

This variable interacts with its associated variable CVarManyLightsNumSamplesPerPixel, which is the actual TAutoConsoleVariable object that stores and manages the value.

Developers must be aware that this variable affects the quality and performance of shadow rendering in scenes with many lights. Higher values will produce better quality shadows but at the cost of increased rendering time.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of the scene and target hardware.
  2. Testing different values to find the optimal balance between visual quality and performance.
  3. Considering using lower values for less powerful hardware or in performance-critical scenarios.

Regarding the associated variable CVarManyLightsNumSamplesPerPixel:

The purpose of CVarManyLightsNumSamplesPerPixel is to provide a programmatic interface for the r.ManyLights.NumSamplesPerPixel setting within the engine’s code.

It’s used directly in the ManyLights module of the Renderer subsystem, specifically in the GetNumSamplesPerPixel2d() function.

The value of this variable is set through the CVar system and can be accessed using the GetValueOnRenderThread() method.

This variable directly determines the number of samples used for shadow ray tracing, affecting both the quality of shadows and the performance of the rendering process.

Developers should be aware that this variable’s value is clamped between 1 and 4, and then rounded up to the nearest power of two.

Best practices include using this variable to dynamically adjust the shadow quality based on the current rendering load or user preferences, and caching its value when appropriate to avoid frequent calls to GetValueOnRenderThread().

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarManyLightsNumSamplesPerPixel(
	TEXT("r.ManyLights.NumSamplesPerPixel"),
	4,
	TEXT("Number of samples (shadow rays) per half-res pixel.\n")
	TEXT("1 - 0.25 trace per pixel\n")
	TEXT("2 - 0.5 trace per pixel\n")
	TEXT("4 - 1 trace per pixel"),
	ECVF_Scalability | ECVF_RenderThreadSafe

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarManyLightsNumSamplesPerPixel(
	TEXT("r.ManyLights.NumSamplesPerPixel"),
	4,
	TEXT("Number of samples (shadow rays) per half-res pixel.\n")
	TEXT("1 - 0.25 trace per pixel\n")
	TEXT("2 - 0.5 trace per pixel\n")
	TEXT("4 - 1 trace per pixel"),

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

Scope (from outer to inner):

file
namespace    ManyLights
function     FIntPoint GetNumSamplesPerPixel2d

Source code excerpt:

	FIntPoint GetNumSamplesPerPixel2d()
	{
		const uint32 NumSamplesPerPixel1d = FMath::RoundUpToPowerOfTwo(FMath::Clamp(CVarManyLightsNumSamplesPerPixel.GetValueOnRenderThread(), 1, 4));
		return NumSamplesPerPixel1d == 4 ? FIntPoint(2, 2) : (NumSamplesPerPixel1d == 2 ? FIntPoint(2, 1) : FIntPoint(1, 1));
	}

	int32 GetDebugMode()
	{
		return CVarManyLightsDebug.GetValueOnRenderThread();