bCacheFinalGatherHitPointsForRadiosity

bCacheFinalGatherHitPointsForRadiosity

#Overview

name: bCacheFinalGatherHitPointsForRadiosity

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

#Summary

#Usage in the C++ source code

The purpose of bCacheFinalGatherHitPointsForRadiosity is to control the caching of final gather hit points for radiosity calculations in Unreal Engine’s lightmass system. This setting is part of the global illumination and lighting system in Unreal Engine.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for precomputed lighting and global illumination in Unreal Engine. It’s specifically part of the ImportanceTracingSettings within the Lightmass system.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the “DevOptions.ImportanceTracing” section of the config file using the GConfig system.

This variable interacts with other ImportanceTracingSettings and GeneralSettings variables, particularly NumSkyLightingBounces. It affects the behavior of the radiosity solver and the caching of gather hit points.

Developers must be aware that enabling this option can significantly increase memory usage. As the comment in the code suggests, the memory use is proportional to the number of lightmap texels in the scene and the number of final gather rays.

Best practices when using this variable include:

  1. Only enable it when high-quality indirect lighting is required, as it can be memory-intensive.
  2. Consider the trade-off between lighting quality and performance/memory usage.
  3. Test the impact on build times and memory usage for your specific scene before enabling it in production.
  4. Use in conjunction with other radiosity and importance tracing settings for optimal results.
  5. Be cautious when enabling this for large scenes with many lightmap texels, as it could lead to excessive memory consumption.

#Setting Variables

#References In INI files

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

#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:2341

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:


		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bUseRadiositySolverForSkylightMultibounce"), Scene.ImportanceTracingSettings.bUseRadiositySolverForSkylightMultibounce, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bCacheFinalGatherHitPointsForRadiosity"), Scene.ImportanceTracingSettings.bCacheFinalGatherHitPointsForRadiosity, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bUseRadiositySolverForLightMultibounce"), Scene.ImportanceTracingSettings.bUseRadiositySolverForLightMultibounce, GLightmassIni));
	}
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bUsePhotonMapping"), bConfigBool, GLightmassIni));
		Scene.PhotonMappingSettings.bUsePhotonMapping = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bUseFinalGathering"), bConfigBool, GLightmassIni));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/Radiosity.cpp:260

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::RadiositySetupTextureMapping

Source code excerpt:

	TextureMapping->RadiositySurfaceCache[1].AddZeroed(TextureMapping->SurfaceCacheSizeX * TextureMapping->SurfaceCacheSizeY);

	const bool bCacheFinalGatherHitPoints = ImportanceTracingSettings.bCacheFinalGatherHitPointsForRadiosity && GeneralSettings.NumSkyLightingBounces > 0;

	FGatherHitPoints& GatherHitPoints = TextureMapping->UncompressedGatherHitPoints;

	if (bCacheFinalGatherHitPoints)
	{
		GatherHitPoints.GatherHitPointRanges.Empty(TextureMapping->SurfaceCacheSizeY * TextureMapping->SurfaceCacheSizeX / 4);

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/Radiosity.cpp:571

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::RadiosityIterationTextureMapping

Source code excerpt:

	RasterizeToSurfaceCacheTextureMapping(TextureMapping, bDebugThisMapping, TexelToVertexMap);

	if (ImportanceTracingSettings.bCacheFinalGatherHitPointsForRadiosity)
	{
		RadiosityIterationCachedHitpointsTextureMapping(TexelToVertexMap, TextureMapping, PassIndex);
	}
	else
	{
		const int32 SourceRadiosityBufferIndex = PassIndex % 2;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FImportanceTracingSettings

Source code excerpt:

	 * Memory use is proportional to the lightmap texels in the scene and number of final gather rays.
	 */
	bool bCacheFinalGatherHitPointsForRadiosity;

	/**
	 * Whether to use radiosity iterations for point / spot / directional lights, instead of photons. 
	 * Has lower quality than photons in difficult indoor scenarios but useful as a reference.
	 */
	bool bUseRadiositySolverForLightMultibounce;