r.Lumen.RadianceCache.HardwareRayTracing.TemporaryBufferAllocationDownsampleFactor

r.Lumen.RadianceCache.HardwareRayTracing.TemporaryBufferAllocationDownsampleFactor

#Overview

name: r.Lumen.RadianceCache.HardwareRayTracing.TemporaryBufferAllocationDownsampleFactor

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.Lumen.RadianceCache.HardwareRayTracing.TemporaryBufferAllocationDownsampleFactor is to control the downsample factor for the temporary buffer used by the Hardware Ray Tracing Radiance Cache in Unreal Engine’s Lumen global illumination system. This setting is part of the rendering system, specifically the Lumen subsystem.

The Lumen Radiance Cache Hardware Ray Tracing module relies on this setting variable. It is used to determine the size of temporary buffers allocated for ray tracing operations.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. The default value is 8, as seen in the source code.

This variable interacts with other variables in the ray tracing process, such as MaxProbeTraceTileResolution and MaxNumProbes, to calculate the dimensions of temporary buffers used in the ray tracing process.

Developers must be aware that:

  1. Higher downsample factors save more transient allocator memory but may cause overflow and artifacts.
  2. The value affects the performance and quality trade-off of the ray tracing process.
  3. It’s used in critical calculations for buffer sizes, so changing it can have significant impacts on memory usage and rendering quality.

Best practices when using this variable include:

  1. Carefully balance between memory savings and potential artifacts.
  2. Test thoroughly after changing the value to ensure no negative impacts on visual quality or performance.
  3. Consider scene complexity and available GPU memory when adjusting this value.

The associated variable CVarLumenRadianceCacheTemporaryBufferAllocationDownsampleFactor is the actual console variable that stores and provides access to this setting. It’s defined with the same properties as the r.Lumen.RadianceCache.HardwareRayTracing.TemporaryBufferAllocationDownsampleFactor setting.

This CVar is used in the LumenRadianceCache::RenderLumenHardwareRayTracingRadianceCache function to determine the TemporaryBufferAllocationDownsampleFactor. It’s important to note that this value can be overridden if GRadianceCacheForceFullUpdate is true, in which case a value of 4 is used instead.

When working with this CVar, developers should be aware that it can be changed at runtime, and its value is retrieved using the GetValueOnRenderThread() method, ensuring thread-safe access in the render thread.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenRadianceCacheHardwareRayTracing.cpp:27

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenRadianceCacheTemporaryBufferAllocationDownsampleFactor(
	TEXT("r.Lumen.RadianceCache.HardwareRayTracing.TemporaryBufferAllocationDownsampleFactor"),
	8,
	TEXT("Downsample factor on the temporary buffer used by Hardware Ray Tracing Radiance Cache.  Higher downsample factors save more transient allocator memory, but may cause overflow and artifacts."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenRadianceCacheHardwareRayTracingRetraceFarField(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenRadianceCacheHardwareRayTracing.cpp:26

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenRadianceCacheTemporaryBufferAllocationDownsampleFactor(
	TEXT("r.Lumen.RadianceCache.HardwareRayTracing.TemporaryBufferAllocationDownsampleFactor"),
	8,
	TEXT("Downsample factor on the temporary buffer used by Hardware Ray Tracing Radiance Cache.  Higher downsample factors save more transient allocator memory, but may cause overflow and artifacts."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenRadianceCacheHardwareRayTracing.cpp:412

Scope (from outer to inner):

file
function     void LumenRadianceCache::RenderLumenHardwareRayTracingRadianceCache

Source code excerpt:


	// Overflow is possible however unlikely - only nearby probes trace at max resolution
	const int32 TemporaryBufferAllocationDownsampleFactor = GRadianceCacheForceFullUpdate ? 4 : CVarLumenRadianceCacheTemporaryBufferAllocationDownsampleFactor.GetValueOnRenderThread();
	const int32 TempAtlasNumTraceTilesPerProbe = FMath::DivideAndRoundUp(MaxProbeTraceTileResolution * MaxProbeTraceTileResolution, TemporaryBufferAllocationDownsampleFactor);
	const int32 TempAtlasNumTraceTiles = MaxNumProbes * TempAtlasNumTraceTilesPerProbe;
	const FIntPoint WrappedTraceTileLayout(
		TempAtlasTraceTileStride,
		FMath::DivideAndRoundUp(TempAtlasNumTraceTiles, TempAtlasTraceTileStride));
	const FIntPoint TempTraceAtlasResolution = WrappedTraceTileLayout * TraceTileSize;