r.GlobalIllumination.Denoiser.HistoryConvolution.KernelSpreadFactor

r.GlobalIllumination.Denoiser.HistoryConvolution.KernelSpreadFactor

#Overview

name: r.GlobalIllumination.Denoiser.HistoryConvolution.KernelSpreadFactor

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GlobalIllumination.Denoiser.HistoryConvolution.KernelSpreadFactor is to control the spread of the kernel used in the history convolution process of the Global Illumination (GI) denoiser in Unreal Engine 5’s rendering system.

This setting variable is primarily used by the rendering subsystem, specifically within the screen space denoising module. It’s part of the Global Illumination denoising process, which aims to reduce noise in rendered images while preserving detail.

The value of this variable is set through a console variable (CVar) named CVarGIHistoryConvolutionKernelSpreadFactor. It’s defined with a default value of 3 and can be adjusted at runtime.

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

Developers should be aware that this variable directly affects the quality and performance of the GI denoising process. A higher value will result in a wider spread of the convolution kernel, which can help reduce noise but may also blur fine details. Conversely, a lower value will preserve more detail but may be less effective at noise reduction.

Best practices when using this variable include:

  1. Balancing it with other denoising parameters for optimal results.
  2. Testing different values to find the best trade-off between noise reduction and detail preservation for your specific scene.
  3. Considering performance implications, as higher values may increase computational cost.

Regarding the associated variable CVarGIHistoryConvolutionKernelSpreadFactor:

This is the actual console variable that stores and provides access to the r.GlobalIllumination.Denoiser.HistoryConvolution.KernelSpreadFactor value. It’s used in the FDefaultScreenSpaceDenoiser class to set up denoising settings for both diffuse indirect lighting and skylight denoising.

The variable is accessed using GetValueOnRenderThread(), indicating that it’s designed to be safely read from the render thread. This is important for maintaining thread safety in the rendering pipeline.

When working with this variable, developers should:

  1. Use the GetValueOnRenderThread() method to access its value safely from render thread code.
  2. Be aware that changes to this variable will affect both diffuse indirect and skylight denoising.
  3. Consider exposing this setting in user interfaces if fine-tuning of denoising is required for different scenes or quality settings.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarGIHistoryConvolutionKernelSpreadFactor(
	TEXT("r.GlobalIllumination.Denoiser.HistoryConvolution.KernelSpreadFactor"), 3,
	TEXT("Multiplication factor applied on the kernel sample offset (default=3)."),
	ECVF_RenderThreadSafe);

/** The maximum number of mip level supported in the denoiser. */
// TODO(Denoiser): jump to 3 because bufefr size already have a size multiple of 4.
static const int32 kMaxMipLevel = 2;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarGIHistoryConvolutionKernelSpreadFactor(
	TEXT("r.GlobalIllumination.Denoiser.HistoryConvolution.KernelSpreadFactor"), 3,
	TEXT("Multiplication factor applied on the kernel sample offset (default=3)."),
	ECVF_RenderThreadSafe);

/** The maximum number of mip level supported in the denoiser. */
// TODO(Denoiser): jump to 3 because bufefr size already have a size multiple of 4.

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

Scope (from outer to inner):

file
class        class FDefaultScreenSpaceDenoiser : public IScreenSpaceDenoiser
function     FSSDSignalTextures DenoiseDiffuseIndirect

Source code excerpt:

		Settings.bUseTemporalAccumulation = CVarGITemporalAccumulation.GetValueOnRenderThread() != 0;
		Settings.HistoryConvolutionSampleCount = CVarGIHistoryConvolutionSampleCount.GetValueOnRenderThread();
		Settings.HistoryConvolutionKernelSpreadFactor = CVarGIHistoryConvolutionKernelSpreadFactor.GetValueOnRenderThread();
		Settings.MaxInputSPP = Config.RayCountPerPixel;

		TStaticArray<FScreenSpaceDenoiserHistory*, IScreenSpaceDenoiser::kMaxBatchSize> PrevHistories;
		TStaticArray<FScreenSpaceDenoiserHistory*, IScreenSpaceDenoiser::kMaxBatchSize> NewHistories;
		PrevHistories[0] = &PreviousViewInfos->DiffuseIndirectHistory;
		NewHistories[0] = View.ViewState ? &View.ViewState->PrevFrameViewInfo.DiffuseIndirectHistory : nullptr;

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

Scope (from outer to inner):

file
class        class FDefaultScreenSpaceDenoiser : public IScreenSpaceDenoiser
function     FDiffuseIndirectOutputs DenoiseSkyLight

Source code excerpt:

		Settings.bUseTemporalAccumulation = CVarGITemporalAccumulation.GetValueOnRenderThread() != 0;
		Settings.HistoryConvolutionSampleCount = CVarGIHistoryConvolutionSampleCount.GetValueOnRenderThread();
		Settings.HistoryConvolutionKernelSpreadFactor = CVarGIHistoryConvolutionKernelSpreadFactor.GetValueOnRenderThread();
		Settings.MaxInputSPP = Config.RayCountPerPixel;

		TStaticArray<FScreenSpaceDenoiserHistory*, IScreenSpaceDenoiser::kMaxBatchSize> PrevHistories;
		TStaticArray<FScreenSpaceDenoiserHistory*, IScreenSpaceDenoiser::kMaxBatchSize> NewHistories;
		PrevHistories[0] = &PreviousViewInfos->SkyLightHistory;
		NewHistories[0] = View.ViewState ? &View.ViewState->PrevFrameViewInfo.SkyLightHistory : nullptr;