ApproximateHighResTexelsPerMaxTransitionDistance
ApproximateHighResTexelsPerMaxTransitionDistance
#Overview
name: ApproximateHighResTexelsPerMaxTransitionDistance
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 ApproximateHighResTexelsPerMaxTransitionDistance is to control the quality of distance field reconstruction in static shadow calculations within Unreal Engine’s lighting system. This variable is primarily used in the Lightmass subsystem, which is responsible for precomputed lighting and shadowing in Unreal Engine.
Based on the callsites, this setting variable is primarily used in the Lightmass module of Unreal Engine. It is particularly relevant to the static shadow generation process and affects the quality of distance field-based shadows.
The value of this variable is set in the Lightmass configuration file (GLightmassIni). It is read from the “DevOptions.StaticShadows” section of the configuration file using the GConfig system.
This variable interacts with other shadow-related settings, such as MaxTransitionDistanceWorldSpace and MinDistanceFieldUpsampleFactor. It is used to calculate the UpsampleFactor for distance field calculations.
Developers should be aware that this variable directly impacts the quality and performance trade-off in static shadow generation. Higher values will result in better quality shadows but will increase build times.
Best practices when using this variable include:
- Balancing it with other shadow settings to achieve the desired quality within acceptable build time constraints.
- Adjusting it based on the scale and detail level of the meshes in the scene.
- Using it in conjunction with MaxTransitionDistanceWorldSpace to fine-tune shadow transitions.
- Considering the performance impact on different hardware when increasing this value.
- Testing different values to find the optimal balance between shadow quality and build time for your specific project.
Remember that changes to this variable will require rebuilding lighting to take effect, which can be time-consuming for large scenes.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseLightmass.ini:144, section: [DevOptions.StaticShadows]
- INI Section:
DevOptions.StaticShadows
- Raw value:
50
- 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:2316
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
Scene.ShadowSettings.bAllowSignedDistanceFieldShadows = bConfigBool;
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("MaxTransitionDistanceWorldSpace"), Scene.ShadowSettings.MaxTransitionDistanceWorldSpace, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("ApproximateHighResTexelsPerMaxTransitionDistance"), Scene.ShadowSettings.ApproximateHighResTexelsPerMaxTransitionDistance, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("MinDistanceFieldUpsampleFactor"), Scene.ShadowSettings.MinDistanceFieldUpsampleFactor, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("StaticShadowDepthMapTransitionSampleDistanceX"), Scene.ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("StaticShadowDepthMapTransitionSampleDistanceY"), Scene.ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceY, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("StaticShadowDepthMapSuperSampleFactor"), Scene.ShadowSettings.StaticShadowDepthMapSuperSampleFactor, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("StaticShadowDepthMapMaxSamples"), Scene.ShadowSettings.StaticShadowDepthMapMaxSamples, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("MinUnoccludedFraction"), Scene.ShadowSettings.MinUnoccludedFraction, GLightmassIni));
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2436
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
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));
float NumHemisphereSamplesScale;
VERIFYLIGHTMASSINI(GConfig->GetFloat(QualitySectionNames[QualityLevel], TEXT("NumHemisphereSamplesScale"), NumHemisphereSamplesScale, GLightmassIni));
Scene.ImportanceTracingSettings.NumHemisphereSamples = FMath::TruncToInt(Scene.ImportanceTracingSettings.NumHemisphereSamples * NumHemisphereSamplesScale);
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:1928
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::CalculateDirectSignedDistanceFieldLightingTextureMappingTextureSpace
Source code excerpt:
// The result is that small, high resolution meshes will not upsample as much, since they don't need it,
// But large, low resolution meshes will upsample a lot.
const int32 TargetUpsampleFactor = FMath::TruncToInt(ShadowSettings.ApproximateHighResTexelsPerMaxTransitionDistance / (RightTriangleSide * ShadowSettings.MaxTransitionDistanceWorldSpace));
// Round up to the nearest odd factor, so each destination texel has a high resolution source texel at its center
// Clamp the upscale factor to be less than 13, since the quality improvements of upsampling higher than that are negligible.
UpsampleFactor = FMath::Clamp(TargetUpsampleFactor - TargetUpsampleFactor % 2 + 1, ShadowSettings.MinDistanceFieldUpsampleFactor, 13);
}
MappingContext.Stats.AccumulatedSignedDistanceFieldUpsampleFactors += UpsampleFactor;
MappingContext.Stats.NumSignedDistanceFieldCalculations++;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:478
Scope (from outer to inner):
file
namespace Lightmass
class class FStaticShadowSettings
Source code excerpt:
* Higher values increase the distance field reconstruction quality, at the cost of longer build times.
*/
int32 ApproximateHighResTexelsPerMaxTransitionDistance;
/**
* The minimum upsample factor to calculate the high resolution samples at.
* Larger values increase distance field reconstruction quality on small, high resolution meshes, at the cost of longer build times.
*/
int32 MinDistanceFieldUpsampleFactor;