NumPenumbraShadowRays
NumPenumbraShadowRays
#Overview
name: NumPenumbraShadowRays
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 5
C++ source files.
#Summary
#Usage in the C++ source code
The purpose of NumPenumbraShadowRays is to control the quality of shadow penumbra calculations in Unreal Engine 5’s static lighting system. It specifically determines the number of shadow rays to trace to each area light for texels that are identified to be in a shadow penumbra region.
This setting variable is primarily used by the Lightmass system, which is Unreal Engine’s global illumination and static lighting solution. It is part of the static shadow settings and is utilized in both the editor (UnrealEd) and the Lightmass computation program.
The value of this variable is typically set in the Lightmass configuration file (GLightmassIni). It’s read from the “DevOptions.StaticShadows” section of this configuration file and can be adjusted based on different quality levels.
NumPenumbraShadowRays interacts with other shadow-related variables such as NumShadowRays and NumBounceShadowRays. It’s also affected by the IndirectLightingQuality setting, which can scale the number of penumbra shadow rays.
Developers should be aware that increasing this value will improve the quality of shadow penumbras but at the cost of increased computation time during lightmap generation. It’s particularly important for area lights, where soft shadows are more prominent.
Best practices when using this variable include:
- Adjusting it based on the project’s specific needs for shadow quality vs. build time.
- Considering the scale of your scenes and the prominence of area lights when setting this value.
- Testing different values to find the optimal balance between quality and performance for your specific project.
- Remember that it’s scaled by the square root of IndirectLightingQuality, so changes to that setting will also affect the effective number of penumbra shadow rays.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseLightmass.ini:138, section: [DevOptions.StaticShadows]
- INI Section:
DevOptions.StaticShadows
- Raw value:
8
- 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:2308
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
Scene.ShadowSettings.bUseZeroAreaLightmapSpaceFilteredLights = bConfigBool;
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;
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2432
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
float NumPenumbraShadowRaysScale;
VERIFYLIGHTMASSINI(GConfig->GetFloat(QualitySectionNames[QualityLevel], TEXT("NumPenumbraShadowRaysScale"), NumPenumbraShadowRaysScale, GLightmassIni));
Scene.ShadowSettings.NumPenumbraShadowRays = FMath::TruncToInt(Scene.ShadowSettings.NumPenumbraShadowRays * NumPenumbraShadowRaysScale);
float ApproximateHighResTexelsPerMaxTransitionDistanceScale;
VERIFYLIGHTMASSINI(GConfig->GetFloat(QualitySectionNames[QualityLevel], TEXT("ApproximateHighResTexelsPerMaxTransitionDistanceScale"), ApproximateHighResTexelsPerMaxTransitionDistanceScale, GLightmassIni));
Scene.ShadowSettings.ApproximateHighResTexelsPerMaxTransitionDistance = FMath::TruncToInt(Scene.ShadowSettings.ApproximateHighResTexelsPerMaxTransitionDistance * ApproximateHighResTexelsPerMaxTransitionDistanceScale);
VERIFYLIGHTMASSINI(GConfig->GetInt(QualitySectionNames[QualityLevel], TEXT("MinDistanceFieldUpsampleFactor"), Scene.ShadowSettings.MinDistanceFieldUpsampleFactor, GLightmassIni));
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:822
Scope (from outer to inner):
file
namespace Lightmass
function int32 FStaticLightingSystem::GetNumShadowRays
Source code excerpt:
if (BounceNumber == 0 && bPenumbra)
{
NumShadowRaysResult = ShadowSettings.NumPenumbraShadowRays;
}
else if (BounceNumber == 0 && !bPenumbra)
{
NumShadowRaysResult = ShadowSettings.NumShadowRays;
}
else if (BounceNumber > 0)
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:967
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::ValidateSettings
Source code excerpt:
InScene.ShadowSettings.NumShadowRays = FMath::TruncToInt(InScene.ShadowSettings.NumShadowRays * FMath::Sqrt(InScene.GeneralSettings.IndirectLightingQuality));
InScene.ShadowSettings.NumPenumbraShadowRays = FMath::TruncToInt(InScene.ShadowSettings.NumPenumbraShadowRays * FMath::Sqrt(InScene.GeneralSettings.IndirectLightingQuality));
InScene.ImportanceTracingSettings.NumAdaptiveRefinementLevels = FMath::Min(InScene.ImportanceTracingSettings.NumAdaptiveRefinementLevels, MaxNumRefiningDepths);
}
/** Logs solver stats */
void FStaticLightingSystem::DumpStats(float TotalStaticLightingTime) const
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:447
Scope (from outer to inner):
file
namespace Lightmass
class class FStaticShadowSettings
Source code excerpt:
/** Number of shadow rays to trace to each area light once a texel has been determined to lie in a shadow penumbra. */
int32 NumPenumbraShadowRays;
/**
* Number of shadow rays to trace to each area light for bounced lighting.
* This number is divided by bounce number for successive bounces.
*/
int32 NumBounceShadowRays;