r.HeterogeneousVolumes.LightingCache

r.HeterogeneousVolumes.LightingCache

#Overview

name: r.HeterogeneousVolumes.LightingCache

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.HeterogeneousVolumes.LightingCache is to enable an optimized pre-pass for caching certain volumetric rendering lighting quantities in heterogeneous volumes rendering. This setting is part of Unreal Engine 5’s rendering system, specifically for volumetric lighting optimization.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, particularly in the heterogeneous volumes rendering subsystem. It’s referenced in the HeterogeneousVolumes.cpp file, which is part of the volumetric rendering implementation.

The value of this variable is set through a console variable (CVarHeterogeneousVolumesLightingCache) with a default value of 2. It can be changed at runtime through console commands or programmatically.

The variable interacts closely with its associated variable CVarHeterogeneousVolumesLightingCache, which is the actual TAutoConsoleVariable object that stores and manages the setting’s value.

Developers must be aware that this variable has three possible states: 0: Disabled (no caching) 1: Cache transmittance 2: Cache in-scattering (default)

When using this variable, developers should consider the performance implications of each setting. Caching can improve rendering performance but may consume more memory.

Best practices when using this variable include:

  1. Testing different settings to find the optimal balance between performance and visual quality for your specific use case.
  2. Considering the target hardware capabilities when deciding on the caching strategy.
  3. Being aware that changing this setting at runtime may affect rendering performance and visual consistency.

Regarding the associated variable CVarHeterogeneousVolumesLightingCache:

The purpose of CVarHeterogeneousVolumesLightingCache is to provide a programmatic interface for getting and setting the r.HeterogeneousVolumes.LightingCache value within the engine’s C++ code.

This variable is used directly in the Renderer module, specifically in the HeterogeneousVolumes namespace. It’s accessed in functions like GetLightingCacheMode(), UseLightingCacheForInscattering(), and UseLightingCacheForTransmittance().

The value of this variable is set when the TAutoConsoleVariable is initialized, but can be changed at runtime using Unreal Engine’s console variable system.

This variable doesn’t directly interact with other variables, but its value determines the behavior of the lighting cache system in heterogeneous volume rendering.

Developers must be aware that this variable is accessed on the render thread, which means changes to its value will be reflected in the next frame render.

Best practices when using this variable include:

  1. Using the provided accessor functions (like GetLightingCacheMode()) instead of directly accessing the console variable when possible.
  2. Being mindful of the performance implications when changing this value, especially in performance-critical sections of code.
  3. Ensuring that any code that relies on this variable’s value is executed on the render thread or uses the appropriate thread-safe accessor methods.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.cpp:183

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesLightingCache(
	TEXT("r.HeterogeneousVolumes.LightingCache"),
	2,
	TEXT("Enables an optimized pre-pass, caching certain volumetric rendering lighting quantities (Default = 2)\n")
	TEXT("0: Disabled\n")
	TEXT("1: Cache transmittance\n")
	TEXT("2: Cache in-scattering\n"),
	ECVF_RenderThreadSafe

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.cpp:182

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesLightingCache(
	TEXT("r.HeterogeneousVolumes.LightingCache"),
	2,
	TEXT("Enables an optimized pre-pass, caching certain volumetric rendering lighting quantities (Default = 2)\n")
	TEXT("0: Disabled\n")
	TEXT("1: Cache transmittance\n")
	TEXT("2: Cache in-scattering\n"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.cpp:450

Scope (from outer to inner):

file
namespace    HeterogeneousVolumes
function     int32 GetLightingCacheMode

Source code excerpt:

	int32 GetLightingCacheMode()
	{
		return CVarHeterogeneousVolumesLightingCache.GetValueOnRenderThread();
	}

	bool UseAdaptiveVolumetricShadowMapForSelfShadowing(const FPrimitiveSceneProxy* PrimitiveSceneProxy)
	{
		bool bUseAVSM = CVarHeterogeneousVolumesLightingCacheUseAVSM.GetValueOnRenderThread() != 0;
		bool bPrimitiveCastsDynamicShadows = PrimitiveSceneProxy->CastsDynamicShadow();

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.cpp:462

Scope (from outer to inner):

file
namespace    HeterogeneousVolumes
function     bool UseLightingCacheForInscattering

Source code excerpt:

	bool UseLightingCacheForInscattering()
	{
		return CVarHeterogeneousVolumesLightingCache.GetValueOnRenderThread() == 2;
	}

	bool UseLightingCacheForTransmittance()
	{
		return CVarHeterogeneousVolumesLightingCache.GetValueOnRenderThread() == 1;
	}

	bool ShouldJitter()
	{
		return CVarHeterogeneousVolumesJitter.GetValueOnRenderThread() != 0;
	}