r.Lumen.SampleFog

r.Lumen.SampleFog

#Overview

name: r.Lumen.SampleFog

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.SampleFog is to control whether fog contribution is sampled in Lumen tracing. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, which is a key component of the rendering subsystem.

The Lumen rendering system relies on this setting variable to determine whether to include fog sampling in its tracing calculations. Specifically, it’s used in the LumenTracingUtils module, which is part of the Renderer subsystem.

The value of this variable is set through a console variable (CVarLumenSampleFog) in the C++ code. It’s initialized with a default value of 0, meaning fog sampling is disabled by default. The value can be changed at runtime through console commands or through project settings.

This variable interacts closely with its associated variable CVarLumenSampleFog. They share the same value, and CVarLumenSampleFog is used to actually retrieve the value in the render thread.

Developers must be aware that enabling this feature (by setting the value to 1 or higher) may have performance implications. Sampling fog in Lumen tracing adds additional calculations to the rendering process, which could impact frame rates, especially on lower-end hardware.

Best practices when using this variable include:

  1. Only enable it when fog is a significant part of your scene and you need accurate global illumination interaction with fog.
  2. Test performance with and without this feature enabled to understand its impact on your specific project.
  3. Consider making it a scalability option, allowing it to be enabled on higher-end hardware configurations while disabled on lower-end ones.

Regarding the associated variable CVarLumenSampleFog:

The purpose of CVarLumenSampleFog is to provide a programmatic interface to control the r.Lumen.SampleFog setting. It’s implemented as a console variable, which allows for easy runtime modification and integration with Unreal Engine’s configuration and console systems.

This variable is used directly in the rendering code to determine whether to sample fog during Lumen tracing. Specifically, in the GetLumenCardTracingParameters function, its value is retrieved and used to set the SampleHeightFog parameter.

The value of CVarLumenSampleFog is set when it’s initialized, but can be changed at runtime through console commands or through engine code that modifies console variables.

Developers should be aware that changes to CVarLumenSampleFog will immediately affect the rendering behavior, potentially causing visual changes or performance impacts mid-game.

Best practices for CVarLumenSampleFog include:

  1. Use it for debugging or performance testing scenarios where you need to toggle fog sampling on and off quickly.
  2. Consider exposing it as a user-facing graphics option in your game’s settings menu if fog sampling has a significant visual or performance impact.
  3. When reading its value, always use the GetValueOnRenderThread() method to ensure thread-safe access in rendering code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenTracingUtils.cpp:14

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenSampleFog(
	TEXT("r.Lumen.SampleFog"),
	0,
	TEXT("Sample the fog contribution in Lumen tracing. Disabled by default."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

void GetLumenCardTracingParameters(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenTracingUtils.cpp:13

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenSampleFog(
	TEXT("r.Lumen.SampleFog"),
	0,
	TEXT("Sample the fog contribution in Lumen tracing. Disabled by default."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenTracingUtils.cpp:40

Scope (from outer to inner):

file
function     void GetLumenCardTracingParameters

Source code excerpt:

	TracingParameters.InvFullSkylightLeakingDistance = 1.0f / FMath::Clamp<float>(View.FinalPostProcessSettings.LumenFullSkylightLeakingDistance, .1f, Lumen::GetMaxTraceDistance(View));

	TracingParameters.SampleHeightFog = CVarLumenSampleFog.GetValueOnRenderThread() > 0 ? 1u : 0u;
	TracingParameters.FogUniformParameters = CreateFogUniformBuffer(GraphBuilder, View);

	const FScene* Scene = ((const FScene*)View.Family->Scene);

	if (FrameTemporaries.CardPageLastUsedBufferUAV && FrameTemporaries.CardPageHighResLastUsedBufferUAV)
	{