r.HeterogeneousVolumes.LightingCache.DownsampleFactor

r.HeterogeneousVolumes.LightingCache.DownsampleFactor

#Overview

name: r.HeterogeneousVolumes.LightingCache.DownsampleFactor

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.HeterogeneousVolumes.LightingCache.DownsampleFactor is to control the downsampling factor for the lighting cache in heterogeneous volumes rendering.

This setting variable is primarily used by the Renderer module in Unreal Engine 5, specifically within the heterogeneous volumes rendering system. It affects how the lighting cache resolution is calculated for heterogeneous volumes.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with an initial value of 0.

This variable interacts closely with the per-volume attribute for lighting downsample factor. When set to 0 (default), it allows the system to use the per-volume attribute. When set to a value greater than 0, it overrides the per-volume attribute.

Developers should be aware that:

  1. This variable directly impacts rendering performance and quality.
  2. Setting a higher value will result in a lower resolution lighting cache, which may improve performance at the cost of lighting quality.
  3. The actual lighting cache resolution is clamped between 1 and 1024 for each dimension.

Best practices when using this variable include:

  1. Use the default value (0) unless there’s a specific need to override all volumes’ lighting cache resolution.
  2. When overriding, start with small increments and test thoroughly to find the right balance between performance and visual quality.
  3. Be mindful of the performance impact on different hardware configurations.

Regarding the associated variable CVarHeterogeneousVolumesLightingCacheDownsampleFactor:

This is the actual console variable that stores the value of r.HeterogeneousVolumes.LightingCache.DownsampleFactor. It’s used internally by the engine to access and modify the downsample factor.

The variable is used in the GetLightingCacheResolution function to determine the final lighting cache resolution. If the value is greater than 0, it overrides the per-volume downsample factor.

Developers should note that this variable is accessed on the render thread (GetValueOnRenderThread()), which means changes to this value will be applied on the next frame render.

When working with this variable, ensure that any modifications are thread-safe and consider the potential impact on render thread performance.

#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:200

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesLightingCacheDownsampleFactor(
	TEXT("r.HeterogeneousVolumes.LightingCache.DownsampleFactor"),
	0,
	TEXT("Overrides the lighting-cache downsample factor, relative to the preshading volume resolution (Default = 0)\n")
	TEXT("0: Disabled, uses per-volume attribute\n")
	TEXT(">0: Overrides the lighting-cache downsample factor"),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesLightingCacheDownsampleFactor(
	TEXT("r.HeterogeneousVolumes.LightingCache.DownsampleFactor"),
	0,
	TEXT("Overrides the lighting-cache downsample factor, relative to the preshading volume resolution (Default = 0)\n")
	TEXT("0: Disabled, uses per-volume attribute\n")
	TEXT(">0: Overrides the lighting-cache downsample factor"),
	ECVF_RenderThreadSafe

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

Scope (from outer to inner):

file
namespace    HeterogeneousVolumes
function     FIntVector GetLightingCacheResolution

Source code excerpt:

	FIntVector GetLightingCacheResolution(const IHeterogeneousVolumeInterface* RenderInterface, float LODFactor)
	{
		float OverrideDownsampleFactor = CVarHeterogeneousVolumesLightingCacheDownsampleFactor.GetValueOnRenderThread();
		float DownsampleFactor = OverrideDownsampleFactor > 0.0 ? OverrideDownsampleFactor : RenderInterface->GetLightingDownsampleFactor() * LODFactor;
		DownsampleFactor = FMath::Max(DownsampleFactor, 0.125);

		FVector VolumeResolution = FVector(GetVolumeResolution(RenderInterface));
		FIntVector LightingCacheResolution = FIntVector(VolumeResolution / DownsampleFactor);
		LightingCacheResolution.X = FMath::Clamp(LightingCacheResolution.X, 1, 1024);