NumBounceShadowRays

NumBounceShadowRays

#Overview

name: NumBounceShadowRays

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 NumBounceShadowRays is to control the number of shadow rays used for indirect lighting bounces in Unreal Engine’s lightmass system. This setting is specifically related to the global illumination and static lighting calculations.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for pre-computing static lighting in Unreal Engine. It’s part of the static lighting and global illumination calculations.

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, which is part of the process of exporting scene settings for Lightmass calculations.

NumBounceShadowRays interacts with other shadow-related variables, such as NumShadowRays and NumPenumbraShadowRays. It’s specifically used for bounce lighting calculations, as opposed to direct lighting or penumbra calculations.

Developers should be aware that this variable affects the quality and performance of indirect lighting calculations. A higher value will result in more accurate indirect shadows but will increase computation time. The value is divided by the bounce number for successive bounces, meaning fewer rays are used for higher-order bounces.

Best practices when using this variable include:

1. Balancing quality and performance by adjusting the value based on the specific needs of the scene.
2. Consider the complexity of the scene and the importance of indirect lighting when setting this value.
3. Test different values to find the optimal balance between visual quality and build time.
4. Remember that this setting affects build times for lightmass calculations, so it should be adjusted carefully in large projects.
5. Use in conjunction with other shadow-related settings for comprehensive control over shadow quality in static lighting.

#Setting Variables

#References In INI files

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

• INI Section: DevOptions.StaticShadows
• Raw value: 1
• Is Array: False

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumShadowRays"), Scene.ShadowSettings.NumShadowRays, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumPenumbraShadowRays"), Scene.ShadowSettings.NumPenumbraShadowRays, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumBounceShadowRays"), Scene.ShadowSettings.NumBounceShadowRays, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticShadows"), TEXT("bFilterShadowFactor"), bConfigBool, GLightmassIni));
		Scene.ShadowSettings.bFilterShadowFactor = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("ShadowFactorGradientTolerance"), Scene.ShadowSettings.ShadowFactorGradientTolerance, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticShadows"), TEXT("bAllowSignedDistanceFieldShadows"), bConfigBool, GLightmassIni));
		Scene.ShadowSettings.bAllowSignedDistanceFieldShadows = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("MaxTransitionDistanceWorldSpace"), Scene.ShadowSettings.MaxTransitionDistanceWorldSpace, GLightmassIni));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     int32 FStaticLightingSystem::GetNumShadowRays

Source code excerpt:

	{
		// Use less rays for each progressive bounce, since the variance will matter less.
		NumShadowRaysResult = FMath::Max(ShadowSettings.NumBounceShadowRays / BounceNumber, 1);
	}
	return NumShadowRaysResult;
}

int32 FStaticLightingSystem::GetNumUniformHemisphereSamples(int32 BounceNumber) const
{

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticShadowSettings

Source code excerpt:

	 * This number is divided by bounce number for successive bounces.
	 */
	int32 NumBounceShadowRays;

	/**
	 * Settings for enabling and adjusting a filter pass on the computed shadow factor. The shadow factor is
	 * a value [0,1] that approximates the percentage of an area light visible at a texel. A value of 0 indicates
	 * that the texel is completely in shadow and 1 indicates that it is completely lit. The tolerance value is the
	 * maximum difference in the absolute shadow factor value allowed between any two adjacent texels before enabling