r.Bloom.CacheKernel

r.Bloom.CacheKernel

#Overview

name: r.Bloom.CacheKernel

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.Bloom.CacheKernel is to control whether the bloom kernel is cached in the spectral domain for Fast Fourier Transform (FFT) bloom effects in Unreal Engine’s rendering system.

This setting variable is primarily used in the rendering system, specifically in the post-processing pipeline for bloom effects. It is part of the FFT bloom implementation, which is an advanced technique for creating high-quality bloom effects.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the post-processing components dealing with bloom effects.

The value of this variable is set through the console variable system in Unreal Engine. It is defined as a TAutoConsoleVariable with a default value of 1 (enabled).

This variable interacts closely with the ViewState’s BloomFFTKernel structure. When enabled, it allows the engine to cache the spectral domain representation of the bloom kernel, which can improve performance by avoiding redundant calculations.

Developers should be aware that enabling this variable (which is the default behavior) can improve performance at the cost of additional memory usage. The cached kernel is stored in the ViewState, so it persists between frames.

Best practices when using this variable include:

  1. Leaving it enabled (default value of 1) for most scenarios to benefit from the performance optimization.
  2. Consider disabling it (setting to 0) if memory usage is a concern and the performance gain is negligible for your specific use case.
  3. Profile your application with and without kernel caching to determine the optimal setting for your specific scenario.

The associated variable CVarBloomCacheKernel is the actual console variable object that controls this setting. It is used in the same way as r.Bloom.CacheKernel, and they share the same value. This variable is used directly in the C++ code to check the current setting and determine whether to cache the kernel or not.

When working with CVarBloomCacheKernel, developers should:

  1. Use GetValueOnRenderThread() to safely access its value from render thread code.
  2. Be aware that changes to this variable will take effect on the next frame when the bloom effect is processed.
  3. Consider exposing this setting in development builds for easy tweaking and performance testing.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessFFTBloom.cpp:19

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarBloomCacheKernel(
	TEXT("r.Bloom.CacheKernel"), 1,
	TEXT("Whether to cache the kernel in spectral domain."),
	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarAsynComputeFFTBloom(
	TEXT("r.Bloom.AsyncCompute"), 1,
	TEXT("Whether to run FFT bloom on async compute.\n"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessFFTBloom.cpp:18

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarBloomCacheKernel(
	TEXT("r.Bloom.CacheKernel"), 1,
	TEXT("Whether to cache the kernel in spectral domain."),
	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarAsynComputeFFTBloom(
	TEXT("r.Bloom.AsyncCompute"), 1,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessFFTBloom.cpp:335

Scope (from outer to inner):

file
function     void InitDomainAndGetKernel

Source code excerpt:

		TexCreate_ShaderResource | TexCreate_UAV);

	if (ViewState && ViewState->BloomFFTKernel.Spectral && CVarBloomCacheKernel.GetValueOnRenderThread() != 0)
	{
		auto& FFTKernel = ViewState->BloomFFTKernel;

		FRDGTextureRef PrevCachedSpectralKernel = GraphBuilder.RegisterExternalTexture(FFTKernel.Spectral);

		const bool bSameTexture = (FFTKernel.PhysicalRHI == PhysicalSpaceKernelTextureRef);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessFFTBloom.cpp:684

Scope (from outer to inner):

file
function     void InitDomainAndGetKernel

Source code excerpt:


	// Update the data on the ViewState
	if (ViewState && CVarBloomCacheKernel.GetValueOnRenderThread() != 0)
	{
		ViewState->BloomFFTKernel.Scale = BloomConvolutionSize;
		ViewState->BloomFFTKernel.ImageSize = Intermediates.ImageSize;
		ViewState->BloomFFTKernel.Physical = View.FinalPostProcessSettings.BloomConvolutionTexture;
		ViewState->BloomFFTKernel.PhysicalRHI = PhysicalSpaceKernelTextureRef;
		ViewState->BloomFFTKernel.PhysicalMipLevel = BloomConvolutionTextureResource->GetCurrentMipCount();