bShowGradientsOnly

bShowGradientsOnly

#Overview

name: bShowGradientsOnly

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 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of bShowGradientsOnly is to provide a debugging option for the irradiance caching system in Unreal Engine’s lightmass calculations. It allows developers to visualize only the irradiance gradients, which can be helpful for understanding and troubleshooting the lighting calculations.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for global illumination and static lighting calculations in Unreal Engine. It is specifically part of the irradiance caching settings, which are used to optimize and improve the quality of indirect lighting calculations.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It is read from the configuration file in the FLightmassExporter::WriteSceneSettings function and then passed to the Lightmass system.

This variable interacts with other irradiance caching settings, such as bUseIrradianceGradients and bVisualizeIrradianceSamples. It is often used in conjunction with these settings to provide different debugging and visualization options for the irradiance caching system.

Developers must be aware that this is a debugging option and should not be enabled in production builds. When enabled, it will only show the irradiance gradients, which can significantly alter the appearance of the lighting in the scene.

Best practices for using this variable include:

  1. Only enable it during development and debugging phases.
  2. Use it in conjunction with other irradiance caching visualization tools to get a comprehensive understanding of the lighting calculations.
  3. Disable it before final lighting builds or when preparing the game for release.
  4. Be cautious when interpreting the results, as showing only gradients can be misleading if not properly understood in the context of the overall lighting system.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:209, 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:2401

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("PointBehindRecordMaxAngle"), Scene.IrradianceCachingSettings.PointBehindRecordMaxAngle, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("DistanceSmoothFactor"), Scene.IrradianceCachingSettings.DistanceSmoothFactor, GLightmassIni));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FLightingCacheBase::FLightingCacheBase

Source code excerpt:

	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)
{
	InterpolationAngleNormalization = 1.0f / FMath::Sqrt(1.0f - FMath::Cos(InSystem.IrradianceCachingSettings.InterpolationMaxAngle * (float)PI / 180.0f));

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FLightingCacheBase

Source code excerpt:

	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:410

Scope (from outer to inner):

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

Source code excerpt:

		const float NormalDot = Dot3(LightingRecord.Vertex.WorldTangentZ, Vertex.WorldTangentZ);

		const float NonGradientLighting = bShowGradientsOnly ? 0.0f : 1.0f;
		float RotationalGradientContribution = 0.0f;
		float TranslationalGradientContribution = 0.0f;

		if (bUseIrradianceGradients)
		{
			// Calculate the gradient's contribution

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings

Source code excerpt:

	else
	{
		InScene.IrradianceCachingSettings.bShowGradientsOnly = false;
	}

	if (InScene.DynamicObjectSettings.bVisualizeVolumeLightInterpolation)
	{
		// Disable irradiance caching if we are visualizing volume light interpolation, otherwise we will be getting a twice interpolated result.
		InScene.IrradianceCachingSettings.bAllowIrradianceCaching = false;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FIrradianceCachingSettings

Source code excerpt:


	/** 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;

	/** Scale applied to the radius of irradiance cache records.  This directly affects sample placement and therefore quality. */
	float RecordRadiusScale;