LightBrightnessSubdivideThreshold

LightBrightnessSubdivideThreshold

#Overview

name: LightBrightnessSubdivideThreshold

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

#Summary

#Usage in the C++ source code

The purpose of LightBrightnessSubdivideThreshold is to control the subdivision of bricks in Unreal Engine 5’s volumetric lightmap system. It is used to determine when a brick should be subdivided based on the brightness of static point or spot lights affecting that brick.

This setting variable is primarily used in the lighting and rendering systems of Unreal Engine, specifically within the Lightmass subsystem, which is responsible for precomputed lighting calculations.

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

LightBrightnessSubdivideThreshold interacts with other lighting-related variables and systems, particularly those involved in volumetric lightmap generation and static lighting calculations.

Developers should be aware that this threshold directly affects the level of detail in volumetric lightmaps. A lower threshold will result in more subdivisions, potentially increasing lighting quality but also increasing memory usage and computation time. Conversely, a higher threshold will reduce subdivisions, which may decrease quality but improve performance.

Best practices when using this variable include:

  1. Carefully balancing the threshold value to achieve the desired trade-off between lighting quality and performance.
  2. Testing different values in various lighting scenarios to find the optimal setting for your specific project.
  3. Considering the impact on build times and memory usage when adjusting this value, especially for large scenes.
  4. Documenting any changes made to this setting to ensure consistency across the development team.
  5. Using version control for the Lightmass configuration file to track changes to this and other related settings.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::SetVolumetricLightmapSettings

Source code excerpt:

	VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumetricLightmaps"), TEXT("SurfaceLightmapMinTexelsPerVoxelAxis"), OutSettings.SurfaceLightmapMinTexelsPerVoxelAxis, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.VolumetricLightmaps"), TEXT("bCullBricksBelowLandscape"), OutSettings.bCullBricksBelowLandscape, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumetricLightmaps"), TEXT("LightBrightnessSubdivideThreshold"), OutSettings.LightBrightnessSubdivideThreshold, GLightmassIni));

	const FLightmassWorldInfoSettings& WorldInfoSettings = World->GetWorldSettings()->LightmassSettings;

	float Smoothing = FMath::Clamp(WorldInfoSettings.VolumetricLightmapSphericalHarmonicSmoothing, SMALL_NUMBER, 1000.0f);
	OutSettings.WindowingTargetLaplacian = 1.0f / Smoothing;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/AdaptiveVolumetricLightmap.cpp:333

Scope (from outer to inner):

file
namespace    Lightmass
function     bool FStaticLightingSystem::ShouldRefineVoxel

Source code excerpt:

						FLinearColor DirectLighting = Light->GetDirectIntensity(SamplePosition, false);

						if (DirectLighting.GetLuminance() > VolumetricLightmapSettings.LightBrightnessSubdivideThreshold)
						{
							// Only subdivide if the light has a significant effect on this voxel
							bVoxelIntersectsScene = true;
							break;
						}
					}

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FVolumetricLightmapSettings

Source code excerpt:


	/** Subdivide bricks when a static point or spot light affects some part of the brick with brightness higher than this. */
	float LightBrightnessSubdivideThreshold;

	/** Maximum desired curvature in the lighting stored in Volumetric Lightmaps, used to reduce Spherical Harmonic ringing via a windowing filter. */
	float WindowingTargetLaplacian;
};

/** Settings for precomputed visibility. */