bUseStratifiedSampling

bUseStratifiedSampling

#Overview

name: bUseStratifiedSampling

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 bUseStratifiedSampling is to control the sampling strategy used in Unreal Engine’s lighting system, specifically for importance tracing in static lighting calculations. It is primarily used for improving the quality and efficiency of lighting calculations in the Lightmass system.

This setting variable is primarily used by the Unreal Engine’s Lightmass subsystem, which is responsible for static lighting calculations. It is referenced in both the editor-side code (UnrealEd module) and the standalone Lightmass application.

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

bUseStratifiedSampling interacts with other importance tracing settings, such as NumHemisphereSamples, NumAdaptiveRefinementLevels, and MaxHemisphereRayAngle. It also has a direct impact on the irradiance gradient calculations.

Developers should be aware that:

  1. When irradiance gradients are enabled, bUseStratifiedSampling is forced to true.
  2. This setting affects the distribution of sample points on the hemisphere during lighting calculations, which can impact both the quality and performance of the lighting results.

Best practices when using this variable include:

  1. Generally, keep it enabled (true) as it tends to reduce variance in lighting calculations.
  2. If you’re experiencing performance issues with lighting builds, you might experiment with disabling it, but be aware that this could potentially reduce lighting quality.
  3. When working with irradiance gradients, remember that this setting will be automatically set to true.
  4. Always test the lighting results after changing this setting, as its impact can vary depending on the specific characteristics of your scene.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

	}
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bUseStratifiedSampling"), bConfigBool, GLightmassIni));
		Scene.ImportanceTracingSettings.bUseStratifiedSampling = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.ImportanceTracing"), TEXT("NumHemisphereSamples"), Scene.ImportanceTracingSettings.NumHemisphereSamples, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.ImportanceTracing"), TEXT("NumAdaptiveRefinementLevels"), Scene.ImportanceTracingSettings.NumAdaptiveRefinementLevels, GLightmassIni));
		float MaxHemisphereAngleDegrees;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.ImportanceTracing"), TEXT("MaxHemisphereRayAngle"), MaxHemisphereAngleDegrees, GLightmassIni));
		Scene.ImportanceTracingSettings.MaxHemisphereRayAngle = MaxHemisphereAngleDegrees * (float)PI / 180.0f;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.ImportanceTracing"), TEXT("AdaptiveBrightnessThreshold"), Scene.ImportanceTracingSettings.AdaptiveBrightnessThreshold, GLightmassIni));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings

Source code excerpt:

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

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings
function     void FStaticLightingSystem::CacheSamples

Source code excerpt:

	CachedHemisphereSampleUniforms.Empty(NumUniformHemisphereSamples);

	if (ImportanceTracingSettings.bUseStratifiedSampling)
	{
		// Split the sampling domain up into cells with equal area
		// Using PI times more Phi steps as Theta steps, but the relationship between them could be anything
		const float NumThetaStepsFloat = FMath::Sqrt(NumUniformHemisphereSamples / (float)PI);
		const int32 NumThetaSteps = FMath::TruncToInt(NumThetaStepsFloat);
		const int32 NumPhiSteps = FMath::TruncToInt(NumThetaStepsFloat * (float)PI);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FImportanceTracingSettings

Source code excerpt:

	 * Debugging - whether to stratify hemisphere samples, which reduces variance. 
	 */
	bool bUseStratifiedSampling;

	/** 
	 * Number of hemisphere samples to evaluate from each irradiance cache sample when not using path tracing.
	 * When photon mapping is enabled, these are called final gather rays.
	 */
	int32 NumHemisphereSamples;