r.Lumen.DiffuseIndirect.Allow

r.Lumen.DiffuseIndirect.Allow

#Overview

name: r.Lumen.DiffuseIndirect.Allow

The value of this variable can be defined or overridden in .ini config files. 5 .ini config files referencing this setting variable.

This variable is created as a Console Variable (cvar).

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.DiffuseIndirect.Allow is to control whether Lumen Global Illumination (GI) is allowed in the rendering system. This setting variable is primarily used in the Lumen subsystem of Unreal Engine 5’s rendering module.

The Unreal Engine subsystems that rely on this setting variable are:

  1. The Renderer module, specifically the Lumen subsystem for global illumination.
  2. The Landscape module, which uses this variable to determine if Lumen is supported for landscape components.

The value of this variable is set through the console variable system. It’s initialized with a default value of 1 (enabled) but can be changed at runtime.

This variable interacts closely with another variable named CVarLumenGlobalIllumination. They share the same value and are used interchangeably in the code.

Developers must be aware of the following when using this variable:

  1. It can only disable Lumen GI if it’s enabled in the project settings.
  2. Changing this variable will trigger a recreation of render states for affected components.
  3. It’s used in conjunction with other settings to determine if Lumen GI should be rendered for a specific view.

Best practices when using this variable include:

  1. Use it for performance optimization by disabling Lumen GI when not needed.
  2. Consider the impact on visual quality when disabling Lumen GI.
  3. Be aware of its interaction with project settings and other console variables related to global illumination.

Regarding the associated variable CVarLumenGlobalIllumination:

The purpose of CVarLumenGlobalIllumination is identical to r.Lumen.DiffuseIndirect.Allow. It’s used to control whether Lumen Global Illumination is allowed.

This variable is primarily used in the Lumen subsystem of the Renderer module. It’s referenced in functions that determine if Lumen GI is allowed, if PSOs (Pipeline State Objects) should be precached, and if Lumen Diffuse GI should be rendered.

The value of this variable is set through the console variable system, initialized with a default value of 1 (enabled).

CVarLumenGlobalIllumination interacts directly with r.Lumen.DiffuseIndirect.Allow, as they share the same value and are used interchangeably.

Developers should be aware that this variable is used in performance-critical code paths and can affect the rendering pipeline significantly.

Best practices for using CVarLumenGlobalIllumination include:

  1. Use it in conjunction with r.Lumen.DiffuseIndirect.Allow for consistency.
  2. Consider its impact on performance and visual quality when modifying its value.
  3. Be aware of its use in determining whether to precache PSOs, which can affect loading times and memory usage.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:260, section: [GlobalIlluminationQuality@0]

Location: <Workspace>/Engine/Config/BaseScalability.ini:267, section: [GlobalIlluminationQuality@1]

Location: <Workspace>/Engine/Config/BaseScalability.ini:273, section: [GlobalIlluminationQuality@2]

Location: <Workspace>/Engine/Config/BaseScalability.ini:296, section: [GlobalIlluminationQuality@3]

Location: <Workspace>/Engine/Config/BaseScalability.ini:320, section: [GlobalIlluminationQuality@Cine]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:28

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int> CVarLumenGlobalIllumination(
	TEXT("r.Lumen.DiffuseIndirect.Allow"),
	1,
	TEXT("Whether to allow Lumen Global Illumination.  Lumen GI is enabled in the project settings, this cvar can only disable it."), 
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Loc: <Workspace>/Engine/Source/Runtime/Landscape/Private/LandscapeCulling.cpp:161

Scope (from outer to inner):

file
namespace    UE::Landscape::Culling
function     FLumenCVarsState

Source code excerpt:

		bLumenSupported = (SupportedCVar && SupportedCVar->GetInt() != 0);
		
		IConsoleVariable* DiffuseIndirectCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Lumen.DiffuseIndirect.Allow"));
		if (bLumenSupported && DiffuseIndirectCVar)
		{
			DiffuseIndirectCVar->SetOnChangedCallback(FConsoleVariableDelegate::CreateStatic(&LandscapeComponentsRecreateRenderState));
		}
		DiffuseIndirectInt = DiffuseIndirectCVar->AsVariableInt();
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IndirectLightRendering.cpp:31

Scope: file

Source code excerpt:

#include "Lumen/LumenReflections.h"

// This is the project default dynamic global illumination, NOT the scalability setting (see r.Lumen.DiffuseIndirect.Allow for scalability)
// Must match EDynamicGlobalIlluminationMethod
// Note: Default for new projects set by GameProjectUtils
static TAutoConsoleVariable<int32> CVarDynamicGlobalIlluminationMethod(
	TEXT("r.DynamicGlobalIlluminationMethod"), 0,
	TEXT("0 - None.  Global Illumination can be baked into Lightmaps but no technique will be used for Dynamic Global Illumination.\n")
	TEXT("1 - Lumen.  Use Lumen Global Illumination for all lights, emissive materials casting light and SkyLight Occlusion.  Requires 'Generate Mesh Distance Fields' enabled for Software Ray Tracing and 'Support Hardware Ray Tracing' enabled for Hardware Ray Tracing.\n")

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

}

static TAutoConsoleVariable<int> CVarLumenGlobalIllumination(
	TEXT("r.Lumen.DiffuseIndirect.Allow"),
	1,
	TEXT("Whether to allow Lumen Global Illumination.  Lumen GI is enabled in the project settings, this cvar can only disable it."), 
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;

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

Scope (from outer to inner):

file
function     bool LumenDiffuseIndirect::IsAllowed

Source code excerpt:

bool LumenDiffuseIndirect::IsAllowed()
{
	return CVarLumenGlobalIllumination.GetValueOnAnyThread() != 0;
}

bool LumenDiffuseIndirect::UseAsyncCompute(const FViewFamilyInfo& ViewFamily)
{
	return Lumen::UseAsyncCompute(ViewFamily) && CVarLumenDiffuseIndirectAsyncCompute.GetValueOnRenderThread() != 0;
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:214

Scope (from outer to inner):

file
function     bool Lumen::ShouldPrecachePSOs

Source code excerpt:

bool Lumen::ShouldPrecachePSOs(EShaderPlatform Platform)
{
	return DoesPlatformSupportLumenGI(Platform) && CVarLumenGlobalIllumination.GetValueOnAnyThread();
}

void FHemisphereDirectionSampleGenerator::GenerateSamples(int32 TargetNumSamples, int32 InPowerOfTwoDivisor, int32 InSeed, bool bInFullSphere, bool bInCosineDistribution)
{
	int32 NumThetaSteps = FMath::Max(FMath::TruncToInt(FMath::Sqrt(TargetNumSamples / ((float)PI))), 1);
	//int32 NumPhiSteps = FMath::TruncToInt(NumThetaSteps * (float)PI);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:273

Scope (from outer to inner):

file
function     bool ShouldRenderLumenDiffuseGI

Source code excerpt:

	return Lumen::IsLumenFeatureAllowedForView(Scene, View, bSkipTracingDataCheck, bSkipProjectCheck)
		&& View.FinalPostProcessSettings.DynamicGlobalIlluminationMethod == EDynamicGlobalIlluminationMethod::Lumen
		&& CVarLumenGlobalIllumination.GetValueOnAnyThread()
		&& View.Family->EngineShowFlags.GlobalIllumination 
		&& View.Family->EngineShowFlags.LumenGlobalIllumination
		&& !View.Family->EngineShowFlags.PathTracing
		&& (bSkipTracingDataCheck || Lumen::UseHardwareRayTracedScreenProbeGather(*View.Family) || Lumen::IsSoftwareRayTracingSupported());
}