r.AmbientOcclusion.Denoiser.HistoryConvolution.KernelSpreadFactor

r.AmbientOcclusion.Denoiser.HistoryConvolution.KernelSpreadFactor

#Overview

name: r.AmbientOcclusion.Denoiser.HistoryConvolution.KernelSpreadFactor

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.AmbientOcclusion.Denoiser.HistoryConvolution.KernelSpreadFactor is to control the spread of the kernel sample offset in the ambient occlusion denoiser’s history convolution process. It is a multiplication factor that affects the spatial extent of the kernel used in the denoising algorithm.

This setting variable is primarily used in the rendering system, specifically in the screen space denoising subsystem of Unreal Engine 5. It is part of the ambient occlusion post-processing pipeline, which is responsible for improving the visual quality of ambient occlusion effects by reducing noise.

The value of this variable is set as a console variable with a default value of 7. It can be modified at runtime through the console or configuration files.

The variable interacts closely with other ambient occlusion denoising settings, such as the history convolution sample count and temporal accumulation flags. It is used in conjunction with these other settings to fine-tune the denoising process.

Developers must be aware that this variable directly impacts the quality and performance of the ambient occlusion denoising. A higher value will result in a more spread-out kernel, which can help reduce noise but may also introduce blur or loss of fine details. Conversely, a lower value will maintain 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 visual quality and performance.
  2. Testing different values in various lighting scenarios to find the best compromise between noise reduction and detail preservation.
  3. Considering the target hardware capabilities, as higher values may have a more significant performance impact.

The associated variable CVarAOHistoryConvolutionKernelSpreadFactor is the actual console variable object that stores and manages the r.AmbientOcclusion.Denoiser.HistoryConvolution.KernelSpreadFactor setting. It is defined using the TAutoConsoleVariable template and is used to retrieve the current value of the setting at runtime.

This console variable is accessed in the FDefaultScreenSpaceDenoiser class, specifically in the DenoiseAmbientOcclusion function, where it is used to set up the denoising settings for ambient occlusion processing. The value is retrieved using the GetValueOnRenderThread() method, ensuring thread-safe access in the rendering pipeline.

Developers should be aware that changes to this console variable will take effect in real-time, allowing for dynamic adjustment of the denoising behavior. However, frequent changes during runtime may lead to noticeable visual inconsistencies, so it’s generally best to find optimal values during development and use them as defaults in the final product.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


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

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

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

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

static TAutoConsoleVariable<int32> CVarGIReconstructionSampleCount(
	TEXT("r.GlobalIllumination.Denoiser.ReconstructionSamples"), 16,

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

Scope (from outer to inner):

file
class        class FDefaultScreenSpaceDenoiser : public IScreenSpaceDenoiser
function     FAmbientOcclusionOutputs DenoiseAmbientOcclusion

Source code excerpt:

		Settings.bUseTemporalAccumulation = CVarAOTemporalAccumulation.GetValueOnRenderThread() != 0;
		Settings.HistoryConvolutionSampleCount = CVarAOHistoryConvolutionSampleCount.GetValueOnRenderThread();
		Settings.HistoryConvolutionKernelSpreadFactor = CVarAOHistoryConvolutionKernelSpreadFactor.GetValueOnRenderThread();
		Settings.MaxInputSPP = RayTracingConfig.RayCountPerPixel;

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