NumSurfaceSampleLayers
NumSurfaceSampleLayers
#Overview
name: NumSurfaceSampleLayers
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 NumSurfaceSampleLayers is to control the number of layers of samples placed above surfaces in the precomputed dynamic object lighting system. This setting is part of Unreal Engine 5’s lighting and rendering system, specifically for the Lightmass global illumination solver.
The Unreal Engine subsystem that relies on this setting variable is primarily the Lightmass system, which is responsible for precomputed lighting calculations. It’s used in the UnrealEd module and the UnrealLightmass program, which are both critical components for lighting calculations in Unreal Engine.
The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the config file in the FLightmassExporter::WriteSceneSettings function in Lightmass.cpp.
NumSurfaceSampleLayers interacts with other variables in the FDynamicObjectSettings struct, such as FirstSurfaceSampleLayerHeight and SurfaceSampleLayerHeightSpacing. These variables work together to determine the placement and distribution of light samples above surfaces.
Developers must be aware that increasing NumSurfaceSampleLayers will increase the number of light samples and, consequently, the memory usage and computation time. It’s directly multiplied with other factors to determine the total number of samples, as seen in the BeginCalculateVolumeSamples function.
Best practices when using this variable include:
- Balancing it with other settings like SurfaceLightSampleSpacing to achieve the desired lighting quality without excessive performance cost.
- Considering the MaxSurfaceLightSamples limit when adjusting this value, as the engine may automatically adjust other parameters if the total sample count exceeds this limit.
- Testing different values to find the optimal balance between lighting quality and performance for your specific scene.
- Documenting any changes made to this setting, as it can significantly impact the lighting calculation process and results.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseLightmass.ini:82, section: [DevOptions.PrecomputedDynamicObjectLighting]
- INI Section:
DevOptions.PrecomputedDynamicObjectLighting
- Raw value:
2
- 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:2259
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("FirstSurfaceSampleLayerHeight"), Scene.DynamicObjectSettings.FirstSurfaceSampleLayerHeight, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("SurfaceSampleLayerHeightSpacing"), Scene.DynamicObjectSettings.SurfaceSampleLayerHeightSpacing, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("NumSurfaceSampleLayers"), Scene.DynamicObjectSettings.NumSurfaceSampleLayers, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("DetailVolumeSampleSpacing"), Scene.DynamicObjectSettings.DetailVolumeSampleSpacing, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("VolumeLightSampleSpacing"), Scene.DynamicObjectSettings.VolumeLightSampleSpacing, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("MaxVolumeSamples"), Scene.DynamicObjectSettings.MaxVolumeSamples, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("bUseMaxSurfaceSampleNum"), bConfigBool, GLightmassIni));
Scene.DynamicObjectSettings.bUseMaxSurfaceSampleNum = bConfigBool;
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("MaxSurfaceLightSamples"), Scene.DynamicObjectSettings.MaxSurfaceLightSamples, GLightmassIni));
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/SampleVolume.cpp:117
Scope (from outer to inner):
file
namespace Lightmass
class class FVolumeSamplePlacementRasterPolicy
function FVolumeSamplePlacementRasterPolicy
Source code excerpt:
ProximityOctree(InProximityOctree)
{
LayerHeightOffsets.Empty(System.DynamicObjectSettings.NumSurfaceSampleLayers);
LayerHeightOffsets.Add(System.DynamicObjectSettings.FirstSurfaceSampleLayerHeight);
for (int32 i = 1; i < System.DynamicObjectSettings.NumSurfaceSampleLayers; i++)
{
LayerHeightOffsets.Add(System.DynamicObjectSettings.FirstSurfaceSampleLayerHeight + i * System.DynamicObjectSettings.SurfaceSampleLayerHeightSpacing);
}
TArray<FVector2f> UniformHemisphereSampleUniforms;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/SampleVolume.cpp:267
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::BeginCalculateVolumeSamples
Source code excerpt:
}
}
LandscapeEstimateNum *= DynamicObjectSettings.NumSurfaceSampleLayers;
if (LandscapeEstimateNum > DynamicObjectSettings.MaxSurfaceLightSamples)
{
// Increase DynamicObjectSettings.SurfaceLightSampleSpacing to reduce light sample number
float OldMaxSurfaceLightSamples = DynamicObjectSettings.SurfaceLightSampleSpacing;
DynamicObjectSettings.SurfaceLightSampleSpacing = DynamicObjectSettings.SurfaceLightSampleSpacing * FMath::Sqrt((float)LandscapeEstimateNum / DynamicObjectSettings.MaxSurfaceLightSamples);
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:318
Scope (from outer to inner):
file
namespace Lightmass
class class FDynamicObjectSettings
Source code excerpt:
float SurfaceSampleLayerHeightSpacing;
/** Number of layers to place above surfaces. */
int32 NumSurfaceSampleLayers;
/** Distance between samples placed in a 3d uniform grid inside detail volumes. */
float DetailVolumeSampleSpacing;
/** Distance between samples placed in a 3d uniform grid inside the importance volume. */
float VolumeLightSampleSpacing;
/** Maximum samples placed in the 3d volume, used to limit memory usage. */
int32 MaxVolumeSamples;