bUseIrradianceGradients

bUseIrradianceGradients

#Overview

name: bUseIrradianceGradients

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of bUseIrradianceGradients is to control whether irradiance gradients are used in the lighting calculation process, specifically within the irradiance caching system. This setting is part of the lighting and global illumination system in Unreal Engine 5.

The Unreal Engine subsystem that primarily relies on this setting variable is the Lightmass system, which is responsible for global illumination and static lighting calculations. It’s specifically used within the irradiance caching component of Lightmass.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the configuration file in the FLightmassExporter::WriteSceneSettings function.

This variable interacts with other irradiance caching settings, such as bAllowIrradianceCaching, bShowGradientsOnly, and bVisualizeIrradianceSamples. It also influences the bUseStratifiedSampling setting in the ImportanceTracingSettings.

Developers must be aware that:

  1. This setting is primarily for debugging and advanced lighting optimization.
  2. Enabling irradiance gradients can increase the accuracy of interpolation in the irradiance cache, but may also increase computation time.
  3. It requires bAllowIrradianceCaching to be true to have any effect.
  4. When enabled, it forces stratified sampling to be used in importance tracing.

Best practices when using this variable include:

  1. Only enable it when working on optimizing lighting quality and performance.
  2. Use it in conjunction with other irradiance caching settings for comprehensive debugging.
  3. Be prepared for potential increases in build times when enabled.
  4. Test the impact on both lighting quality and performance before using it in production builds.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:208, section: [DevOptions.IrradianceCache]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2399

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.IrradianceCache"), TEXT("bAllowIrradianceCaching"), bConfigBool, GLightmassIni));
		Scene.IrradianceCachingSettings.bAllowIrradianceCaching = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.IrradianceCache"), TEXT("bUseIrradianceGradients"), bConfigBool, GLightmassIni));
		Scene.IrradianceCachingSettings.bUseIrradianceGradients = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.IrradianceCache"), TEXT("bShowGradientsOnly"), bConfigBool, GLightmassIni));
		Scene.IrradianceCachingSettings.bShowGradientsOnly = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.IrradianceCache"), TEXT("bVisualizeIrradianceSamples"), bConfigBool, GLightmassIni));
		Scene.IrradianceCachingSettings.bVisualizeIrradianceSamples = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("RecordRadiusScale"), Scene.IrradianceCachingSettings.RecordRadiusScale, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("InterpolationMaxAngle"), Scene.IrradianceCachingSettings.InterpolationMaxAngle, GLightmassIni));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:1347

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculateIrradianceGradients

Source code excerpt:

	FVector4f AccumulatedRotationalGradient(0,0,0);
	FVector4f AccumulatedTranslationalGradient(0,0,0);
	if (IrradianceCachingSettings.bUseIrradianceGradients)
	{
		// Extract Theta and Phi steps from the number of hemisphere samples requested
		const float NumThetaStepsFloat = FMath::Sqrt(GetNumUniformHemisphereSamples(BounceNumber) / (float)PI);
		const int32 NumThetaSteps = FMath::TruncToInt(NumThetaStepsFloat);
		// Using PI times more Phi steps as Theta steps
		const int32 NumPhiSteps = FMath::TruncToInt(NumThetaStepsFloat * (float)PI);

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingCache.cpp:9

Scope (from outer to inner):

file
namespace    Lightmass
function     FLightingCacheBase::FLightingCacheBase

Source code excerpt:

	MinCosPointBehindPlane(FMath::Cos((InSystem.IrradianceCachingSettings.PointBehindRecordMaxAngle + 90.0f) * (float)PI / 180.0f)),
	DistanceSmoothFactor(FMath::Max(InSystem.IrradianceCachingSettings.DistanceSmoothFactor * InSystem.GeneralSettings.IndirectLightingSmoothness, 1.0f)),
	bUseIrradianceGradients(InSystem.IrradianceCachingSettings.bUseIrradianceGradients),
	bShowGradientsOnly(InSystem.IrradianceCachingSettings.bShowGradientsOnly),
	bVisualizeIrradianceSamples(InSystem.IrradianceCachingSettings.bVisualizeIrradianceSamples),
	BounceNumber(InBounceNumber),
	NextRecordId(0),
	System(InSystem)
{

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingCache.h:130

Scope (from outer to inner):

file
namespace    Lightmass
class        class FLightingCacheBase

Source code excerpt:

	const float MinCosPointBehindPlane;
	const float DistanceSmoothFactor;
	const bool bUseIrradianceGradients;
	const bool bShowGradientsOnly;
	const bool bVisualizeIrradianceSamples;
	const int32 BounceNumber;
	int32 NextRecordId;
	mutable FIrradianceCacheStats Stats;
	const class FStaticLightingSystem& System;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingCache.h:414

Scope (from outer to inner):

file
namespace    Lightmass
function     bool TLightingCache<SampleType>::InterpolateLighting

Source code excerpt:

		float TranslationalGradientContribution = 0.0f;

		if (bUseIrradianceGradients)
		{
			// Calculate the gradient's contribution
			RotationalGradientContribution = Dot3((LightingRecord.Vertex.WorldTangentZ ^ Vertex.WorldTangentZ), LightingRecord.RotationalGradient);
			TranslationalGradientContribution = Dot3((Vertex.WorldPosition - LightingRecord.Vertex.WorldPosition), LightingRecord.TranslationalGradient);
		}

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:927

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings

Source code excerpt:

	if (!InScene.IrradianceCachingSettings.bAllowIrradianceCaching)
	{
		InScene.IrradianceCachingSettings.bUseIrradianceGradients = false;
	}

	if (InScene.IrradianceCachingSettings.bUseIrradianceGradients)
	{
		// Irradiance gradients require stratified sampling because the information from each sampled cell is used to calculate the gradient
		InScene.ImportanceTracingSettings.bUseStratifiedSampling = true;
	}
	else
	{

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:720

Scope (from outer to inner):

file
namespace    Lightmass
class        class FIrradianceCachingSettings

Source code excerpt:


	/** Debugging - whether to use irradiance gradients, which effectively allows higher order irradiance cache interpolation. */
	bool bUseIrradianceGradients;

	/** Debugging - whether to only show irradiance gradients. */
	bool bShowGradientsOnly;

	/** Debugging - whether to draw debug elements in the editor showing which irradiance cache samples were used to shade the selected texel. */
	bool bVisualizeIrradianceSamples;