VolumeMaxDistance
VolumeMaxDistance
#Overview
name: VolumeMaxDistance
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 11 C++ source files.
#Summary
#Usage in the C++ source code
The purpose of VolumeMaxDistance is to define the maximum world space distance stored in a precomputed volume distance field. This setting is primarily used in the rendering system, specifically for distance field calculations and lighting.
VolumeMaxDistance is primarily used by the Lightmass subsystem and the static lighting system in Unreal Engine. It’s also referenced in the level serialization process.
The value of this variable is typically set in the Lightmass configuration file (GLightmassIni) under the “DevOptions.VolumeDistanceField” section. It can be read and modified through the engine’s configuration system.
This variable interacts with other distance field-related variables such as VoxelSize and NumVoxelDistanceSamples. It’s also used in calculations involving the StaticLightingLevelScale.
Developers must be aware that:
- Changing this value affects the precision and build time of distance fields.
- It’s scaled by the StaticLightingLevelScale, which can affect its final value in calculations.
- It’s used in normalizing distance values, so extreme values might lead to precision issues.
Best practices when using this variable include:
- Balancing between precision and build time. Larger values increase build time but allow for skipping larger areas in distance field traversal.
- Considering the scale of your level when setting this value, as it represents a world space distance.
- Adjusting it in tandem with other distance field settings for optimal results.
- Testing different values to find the best balance between quality and performance for your specific use case.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseLightmass.ini:129, section: [DevOptions.VolumeDistanceField]
- INI Section:
DevOptions.VolumeDistanceField - Raw value:
900 - 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:2300
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
{
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumeDistanceField"), TEXT("VoxelSize"), Scene.VolumeDistanceFieldSettings.VoxelSize, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumeDistanceField"), TEXT("VolumeMaxDistance"), Scene.VolumeDistanceFieldSettings.VolumeMaxDistance, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.VolumeDistanceField"), TEXT("NumVoxelDistanceSamples"), Scene.VolumeDistanceFieldSettings.NumVoxelDistanceSamples, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.VolumeDistanceField"), TEXT("MaxVoxels"), Scene.VolumeDistanceFieldSettings.MaxVoxels, GLightmassIni));
}
{
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticShadows"), TEXT("bUseZeroAreaLightmapSpaceFilteredLights"), bConfigBool, GLightmassIni));
Scene.ShadowSettings.bUseZeroAreaLightmapSpaceFilteredLights = bConfigBool;
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:3981
Scope (from outer to inner):
file
function void FLightmassProcessor::ImportVolumeDistanceFieldData
Source code excerpt:
Swarm.ReadChannel(Channel, &DistanceField.VolumeSizeY, sizeof(DistanceField.VolumeSizeY));
Swarm.ReadChannel(Channel, &DistanceField.VolumeSizeZ, sizeof(DistanceField.VolumeSizeZ));
Swarm.ReadChannel(Channel, &DistanceField.VolumeMaxDistance, sizeof(DistanceField.VolumeMaxDistance));
FVector4 BoxMin;
Swarm.ReadChannel(Channel, &BoxMin, sizeof(BoxMin));
FVector4 BoxMax;
Swarm.ReadChannel(Channel, &BoxMax, sizeof(BoxMax));
DistanceField.VolumeBox = FBox(BoxMin, BoxMax);
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/Exporter.cpp:150
Scope (from outer to inner):
file
namespace Lightmass
function void FLightmassSolverExporter::ExportVolumeDistanceField
Source code excerpt:
/** Exports the volume distance field. */
void FLightmassSolverExporter::ExportVolumeDistanceField(int32 VolumeSizeX, int32 VolumeSizeY, int32 VolumeSizeZ, float VolumeMaxDistance, const FBox3f& DistanceFieldVolumeBounds, const TArray<FColor>& VolumeDistanceField) const
{
const FString ChannelName = CreateChannelName(VolumeDistanceFieldGuid, LM_MESHAREALIGHTDATA_VERSION, LM_MESHAREALIGHTDATA_EXTENSION);
const int32 ErrorCode = Swarm->OpenChannel(*ChannelName, LM_MESHAREALIGHT_CHANNEL_FLAGS, true);
if( ErrorCode >= 0 )
{
Swarm->Write(&VolumeSizeX, sizeof(VolumeSizeX));
Swarm->Write(&VolumeSizeY, sizeof(VolumeSizeY));
Swarm->Write(&VolumeSizeZ, sizeof(VolumeSizeZ));
Swarm->Write(&VolumeMaxDistance, sizeof(VolumeMaxDistance));
Swarm->Write(&DistanceFieldVolumeBounds.Min, sizeof(DistanceFieldVolumeBounds.Min));
Swarm->Write(&DistanceFieldVolumeBounds.Max, sizeof(DistanceFieldVolumeBounds.Max));
WriteArray(VolumeDistanceField);
Swarm->CloseCurrentChannel();
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/Exporter.h:63
Scope (from outer to inner):
file
namespace Lightmass
class class FLightmassSolverExporter
Source code excerpt:
/** Exports the volume distance field. */
void ExportVolumeDistanceField(int32 VolumeSizeX, int32 VolumeSizeY, int32 VolumeSizeZ, float VolumeMaxDistance, const FBox3f& DistanceFieldVolumeBounds, const TArray<FColor>& VolumeDistanceField) const;
private:
class FLightmassSwarm* Swarm;
const class FScene& Scene;
/** true if the exporter should dump out textures to disk for previewing */
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/LightmassScene.cpp:522
Scope (from outer to inner):
file
namespace Lightmass
function void FScene::ApplyStaticLightingScale
Source code excerpt:
DynamicObjectSettings.VolumeLightSampleSpacing *= SceneConstants.StaticLightingLevelScale;
VolumeDistanceFieldSettings.VoxelSize *= SceneConstants.StaticLightingLevelScale;
VolumeDistanceFieldSettings.VolumeMaxDistance *= SceneConstants.StaticLightingLevelScale;
ShadowSettings.MaxTransitionDistanceWorldSpace *= SceneConstants.StaticLightingLevelScale;
ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceX *= SceneConstants.StaticLightingLevelScale;
ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceY *= SceneConstants.StaticLightingLevelScale;
IrradianceCachingSettings.RecordRadiusScale *= SceneConstants.StaticLightingLevelScale;
IrradianceCachingSettings.MaxRecordRadius *= SceneConstants.StaticLightingLevelScale;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:805
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::ExportNonMappingTasks
Source code excerpt:
if (bShouldExportVolumeDistanceField)
{
Exporter.ExportVolumeDistanceField(VolumeSizeX, VolumeSizeY, VolumeSizeZ, VolumeDistanceFieldSettings.VolumeMaxDistance, DistanceFieldVolumeBounds, VolumeDistanceField);
// Tell Swarm the task is complete (if we're not in debugging mode).
if ( !IsDebugMode() )
{
FLightmassSwarm* Swarm = GetExporter().GetSwarm();
Swarm->TaskCompleted( VolumeDistanceFieldGuid );
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/VolumeDistanceField.cpp:122
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::CalculateVolumeDistanceFieldWorkRange
Source code excerpt:
FLightRay Ray(
VoxelPosition,
VoxelPosition + SampleDirections[SampleIndex] * VolumeDistanceFieldSettings.VolumeMaxDistance,
NULL,
NULL
);
// Trace rays in all directions to find the closest solid surface
FLightRayIntersection Intersection;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/VolumeDistanceField.cpp:158
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::CalculateVolumeDistanceFieldWorkRange
Source code excerpt:
const uint8 Mask0 = FMath::Abs(MinDistance[0]) < DistanceFieldVoxelSize * 2 ? 255 : 0;
// 0 will be -MaxDistance, .5 will be 0, 1 will be +MaxDistance
const float NormalizedDistance0 = FMath::Clamp(MinDistance[0] / VolumeDistanceFieldSettings.VolumeMaxDistance + .5f, 0.0f, 1.0f);
const uint8 Mask1 = FMath::Abs(MinDistance[1]) < DistanceFieldVoxelSize * 2 ? 255 : 0;
const float NormalizedDistance1 = FMath::Clamp(MinDistance[1] / VolumeDistanceFieldSettings.VolumeMaxDistance + .5f, 0.0f, 1.0f);
const FColor FinalValue(
FMath::Clamp<uint8>(FMath::TruncToInt(NormalizedDistance0 * 255), 0, 255),
FMath::Clamp<uint8>(FMath::TruncToInt(NormalizedDistance1 * 255), 0, 255),
Mask0,
Mask1
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:427
Scope (from outer to inner):
file
namespace Lightmass
class class FVolumeDistanceFieldSettings
Source code excerpt:
* Larger values increase build time and decrease distance field precision, but allow distance field traversal to skip larger areas.
*/
float VolumeMaxDistance;
/** Number of distance traces for each voxel. */
int32 NumVoxelDistanceSamples;
/** Upper limit on the number of voxels that can be generated. */
int32 MaxVoxels;
#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/Level.h:299
Scope (from outer to inner):
file
class class FPrecomputedVolumeDistanceField
Source code excerpt:
private:
/** Largest world space distance stored in the volume. */
float VolumeMaxDistance;
/** World space bounding box of the volume. */
FBox VolumeBox;
/** Volume dimension X. */
int32 VolumeSizeX;
/** Volume dimension Y. */
int32 VolumeSizeY;
#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Level.cpp:339
Scope (from outer to inner):
file
function FArchive& operator<<
Source code excerpt:
FArchive& operator<<( FArchive& Ar, FPrecomputedVolumeDistanceField& D )
{
Ar << D.VolumeMaxDistance;
Ar << D.VolumeBox;
Ar << D.VolumeSizeX;
Ar << D.VolumeSizeY;
Ar << D.VolumeSizeZ;
Ar << D.Data;