r.GlobalIllumination.Denoiser.ReconstructionSamples

r.GlobalIllumination.Denoiser.ReconstructionSamples

#Overview

name: r.GlobalIllumination.Denoiser.ReconstructionSamples

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GlobalIllumination.Denoiser.ReconstructionSamples is to control the maximum number of samples used in the reconstruction pass of the Global Illumination (GI) denoiser in Unreal Engine 5’s rendering system.

This setting variable is primarily used by the rendering system, specifically within the screen space denoising module. It’s part of the Global Illumination denoising process, which aims to reduce noise in the rendered image while maintaining visual quality.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by its usage in the ScreenSpaceDenoise.cpp file.

The value of this variable is set through a console variable (CVarGIReconstructionSampleCount) with a default value of 16. It can be changed at runtime using console commands or through engine configuration files.

This variable interacts closely with other GI denoising settings, such as CVarGIPreConvolutionCount, CVarGITemporalAccumulation, and CVarGIHistoryConvolutionSampleCount. Together, these variables control various aspects of the denoising process.

Developers should be aware that this variable directly impacts the quality and performance of the GI denoising process. A higher value will result in better quality but may impact performance, while a lower value will be faster but may produce lower quality results.

Best practices when using this variable include:

  1. Balancing between quality and performance based on the target hardware and project requirements.
  2. Testing different values to find the optimal setting for specific scenes or use cases.
  3. Considering its interaction with other GI denoising settings for best results.

Regarding the associated variable CVarGIReconstructionSampleCount:

This is the actual console variable that controls the r.GlobalIllumination.Denoiser.ReconstructionSamples setting. It’s defined as a TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime.

The purpose of CVarGIReconstructionSampleCount is to provide a way to access and modify the r.GlobalIllumination.Denoiser.ReconstructionSamples setting programmatically and through console commands.

This variable is used directly in the rendering code to set the ReconstructionSamples parameter in the denoising settings structure. It’s clamped between 1 and kStackowiakMaxSampleCountPerSet to ensure valid values.

Developers should be aware that changes to this variable will take effect on the render thread, as indicated by the GetValueOnRenderThread() calls.

Best practices for using CVarGIReconstructionSampleCount include:

  1. Using it for dynamic adjustments of the reconstruction samples count during development or for performance tuning.
  2. Considering its impact on both visual quality and performance when modifying its value.
  3. Ensuring that any code that modifies this value does so in a thread-safe manner, respecting the render thread.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScreenSpaceDenoise.cpp:97

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarGIReconstructionSampleCount(
	TEXT("r.GlobalIllumination.Denoiser.ReconstructionSamples"), 16,
	TEXT("Maximum number of samples for the reconstruction pass (default = 16)."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarGIPreConvolutionCount(
	TEXT("r.GlobalIllumination.Denoiser.PreConvolution"), 1,
	TEXT("Number of pre-convolution passes (default = 1)."),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScreenSpaceDenoise.cpp:96

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarGIReconstructionSampleCount(
	TEXT("r.GlobalIllumination.Denoiser.ReconstructionSamples"), 16,
	TEXT("Maximum number of samples for the reconstruction pass (default = 16)."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarGIPreConvolutionCount(
	TEXT("r.GlobalIllumination.Denoiser.PreConvolution"), 1,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScreenSpaceDenoise.cpp:2700

Scope (from outer to inner):

file
class        class FDefaultScreenSpaceDenoiser : public IScreenSpaceDenoiser
function     FSSDSignalTextures DenoiseDiffuseIndirect

Source code excerpt:

		Settings.SignalProcessing = ESignalProcessing::DiffuseAndAmbientOcclusion;
		Settings.InputResolutionFraction = Config.ResolutionFraction;
		Settings.ReconstructionSamples = FMath::Clamp(CVarGIReconstructionSampleCount.GetValueOnRenderThread(), 1, kStackowiakMaxSampleCountPerSet);
		Settings.PreConvolutionCount = CVarGIPreConvolutionCount.GetValueOnRenderThread();
		Settings.bUseTemporalAccumulation = CVarGITemporalAccumulation.GetValueOnRenderThread() != 0;
		Settings.HistoryConvolutionSampleCount = CVarGIHistoryConvolutionSampleCount.GetValueOnRenderThread();
		Settings.HistoryConvolutionKernelSpreadFactor = CVarGIHistoryConvolutionKernelSpreadFactor.GetValueOnRenderThread();
		Settings.MaxInputSPP = Config.RayCountPerPixel;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScreenSpaceDenoise.cpp:2744

Scope (from outer to inner):

file
class        class FDefaultScreenSpaceDenoiser : public IScreenSpaceDenoiser
function     FDiffuseIndirectOutputs DenoiseSkyLight

Source code excerpt:

		Settings.SignalProcessing = ESignalProcessing::DiffuseAndAmbientOcclusion;
		Settings.InputResolutionFraction = Config.ResolutionFraction;
		Settings.ReconstructionSamples = FMath::Clamp(CVarGIReconstructionSampleCount.GetValueOnRenderThread(), 1, kStackowiakMaxSampleCountPerSet);
		Settings.PreConvolutionCount = CVarGIPreConvolutionCount.GetValueOnRenderThread();
		Settings.bUseTemporalAccumulation = CVarGITemporalAccumulation.GetValueOnRenderThread() != 0;
		Settings.HistoryConvolutionSampleCount = CVarGIHistoryConvolutionSampleCount.GetValueOnRenderThread();
		Settings.HistoryConvolutionKernelSpreadFactor = CVarGIHistoryConvolutionKernelSpreadFactor.GetValueOnRenderThread();
		Settings.MaxInputSPP = Config.RayCountPerPixel;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScreenSpaceDenoise.cpp:2790

Scope (from outer to inner):

file
class        class FDefaultScreenSpaceDenoiser : public IScreenSpaceDenoiser
function     FSSDSignalTextures DenoiseDiffuseIndirectHarmonic

Source code excerpt:

		Settings.SignalProcessing = ESignalProcessing::DiffuseSphericalHarmonic;
		Settings.InputResolutionFraction = 1.0f / float(CommonDiffuseParameters.DownscaleFactor);
		Settings.ReconstructionSamples = CVarGIReconstructionSampleCount.GetValueOnRenderThread();
		Settings.bUseTemporalAccumulation = CVarGITemporalAccumulation.GetValueOnRenderThread() != 0;
		Settings.MaxInputSPP = CommonDiffuseParameters.RayCountPerPixel;
		Settings.DenoisingResolutionFraction = 1.0f / float(CommonDiffuseParameters.DownscaleFactor);

		TStaticArray<FScreenSpaceDenoiserHistory*, IScreenSpaceDenoiser::kMaxBatchSize> PrevHistories;
		TStaticArray<FScreenSpaceDenoiserHistory*, IScreenSpaceDenoiser::kMaxBatchSize> NewHistories;