r.GlobalIllumination.Denoiser.PreConvolution

r.GlobalIllumination.Denoiser.PreConvolution

#Overview

name: r.GlobalIllumination.Denoiser.PreConvolution

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.PreConvolution is to control the number of pre-convolution passes in the Global Illumination (GI) denoiser system of Unreal Engine 5. This setting variable is specifically used for the rendering system, particularly in the screen space denoising process for global illumination.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the ScreenSpaceDenoise.cpp file. It’s part of the global illumination denoising system, which is crucial for improving the quality of rendered images by reducing noise in global illumination calculations.

The value of this variable is set as a console variable (CVar) with a default value of 1. It can be modified at runtime through the console or programmatically.

The associated variable CVarGIPreConvolutionCount interacts directly with r.GlobalIllumination.Denoiser.PreConvolution. They share the same value and purpose.

Developers must be aware that this variable affects the performance and quality trade-off in the global illumination denoising process. Increasing the number of pre-convolution passes can potentially improve image quality but at the cost of increased computational overhead.

Best practices when using this variable include:

  1. Keeping the default value (1) unless there’s a specific need for more pre-convolution passes.
  2. Experimenting with different values to find the optimal balance between image quality and performance for your specific use case.
  3. Considering the target hardware when adjusting this value, as higher values may impact performance on less powerful systems.

Regarding the associated variable CVarGIPreConvolutionCount:

The purpose of CVarGIPreConvolutionCount is identical to r.GlobalIllumination.Denoiser.PreConvolution. It’s an internal representation of the console variable used within the C++ code.

This variable is used in the Renderer module, specifically in the FDefaultScreenSpaceDenoiser class for both diffuse indirect lighting and skylight denoising.

The value of CVarGIPreConvolutionCount is set by the console variable r.GlobalIllumination.Denoiser.PreConvolution and is retrieved using the GetValueOnRenderThread() method.

CVarGIPreConvolutionCount interacts with other denoising-related variables like CVarGIReconstructionSampleCount and CVarGITemporalAccumulation to define the overall denoising settings.

Developers should be aware that this variable is used directly in the denoising calculations and affects the PreConvolutionCount parameter of the denoising settings.

Best practices for CVarGIPreConvolutionCount include:

  1. Treating it as a read-only variable in most cases, modifying it through the r.GlobalIllumination.Denoiser.PreConvolution console variable instead.
  2. Being cautious when directly modifying this variable, as it could lead to inconsistencies if not properly synchronized with the console variable.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


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

static TAutoConsoleVariable<int32> CVarGITemporalAccumulation(
	TEXT("r.GlobalIllumination.Denoiser.TemporalAccumulation"), 1,
	TEXT("Accumulates the samples over multiple frames."),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

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

static TAutoConsoleVariable<int32> CVarGITemporalAccumulation(
	TEXT("r.GlobalIllumination.Denoiser.TemporalAccumulation"), 1,

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

Scope (from outer to inner):

file
class        class FDefaultScreenSpaceDenoiser : public IScreenSpaceDenoiser
function     FSSDSignalTextures DenoiseDiffuseIndirect

Source code excerpt:

		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;

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

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

Scope (from outer to inner):

file
class        class FDefaultScreenSpaceDenoiser : public IScreenSpaceDenoiser
function     FDiffuseIndirectOutputs DenoiseSkyLight

Source code excerpt:

		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;

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