r.ManyLights.Spatial

r.ManyLights.Spatial

#Overview

name: r.ManyLights.Spatial

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.Spatial is to control whether the denoiser should run a spatial filter in the Many Lights rendering system. This setting is part of Unreal Engine’s rendering subsystem, specifically related to the denoising process for multiple light sources.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the Many Lights system within the deferred shading pipeline. This can be seen from the file location “Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLights.cpp”.

The value of this variable is set using a console variable (CVarManyLightsSpatial) with a default value of 1, meaning the spatial filter is enabled by default. Developers can change this value at runtime using console commands or through project settings.

This variable interacts with the FDenoiserSpatialCS shader class, specifically in the permutation domain setting. It determines whether the spatial filter permutation of the shader should be used.

Developers must be aware that:

  1. This setting affects the quality and performance of the Many Lights rendering system.
  2. Enabling the spatial filter (value 1) may improve visual quality but could have a performance cost.
  3. The setting is marked with ECVF_Scalability, indicating it’s part of the scalability options and can be adjusted for different performance levels.

Best practices when using this variable include:

  1. Test the visual quality and performance impact with both enabled and disabled states to find the optimal setting for your project.
  2. Consider exposing this setting in your game’s graphics options for users with different hardware capabilities.
  3. Be mindful of the performance impact when enabling the spatial filter, especially on lower-end hardware.

Regarding the associated variable CVarManyLightsSpatial: This is the actual console variable that controls the r.ManyLights.Spatial setting. It’s an int32 type variable, allowing for potential future expansion of options beyond just on/off. Currently, it’s used as a boolean where non-zero values enable the spatial filter.

The CVarManyLightsSpatial variable is used directly in the rendering code to determine whether to apply the spatial filter permutation in the denoiser shader. This can be seen in the RenderManyLights function where it’s used to set the shader permutation.

When working with CVarManyLightsSpatial, developers should:

  1. Use GetValueOnRenderThread() when accessing its value in render thread code.
  2. Be aware that changes to this variable will affect the shader permutations used, which could cause shader compilation if changed at runtime.
  3. Consider the implications on shader warmup and loading times if allowing this setting to be changed frequently.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarManyLightsSpatial(
	TEXT("r.ManyLights.Spatial"),
	1,
	TEXT("Whether denoiser should run spatial filter."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float> CVarManyLightsSpatialDepthWeightScale(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarManyLightsSpatial(
	TEXT("r.ManyLights.Spatial"),
	1,
	TEXT("Whether denoiser should run spatial filter."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderManyLights

Source code excerpt:


		FDenoiserSpatialCS::FPermutationDomain PermutationVector;
		PermutationVector.Set<FDenoiserSpatialCS::FSpatialFilter>(CVarManyLightsSpatial.GetValueOnRenderThread() != 0);
		PermutationVector.Set<FDenoiserSpatialCS::FDebugMode>(bDebug);
		auto ComputeShader = View.ShaderMap->GetShader<FDenoiserSpatialCS>(PermutationVector);

		const FIntVector GroupCount = FComputeShaderUtils::GetGroupCount(View.ViewRect.Size(), FDenoiserSpatialCS::GetGroupSize());

		FComputeShaderUtils::AddPass(