NumVoxelDistanceSamples

NumVoxelDistanceSamples

#Overview

name: NumVoxelDistanceSamples

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 NumVoxelDistanceSamples is to determine the number of distance samples used for generating a volume distance field in Unreal Engine’s lighting and mesh distance field systems.

This setting variable is primarily used in the Unreal Engine’s mesh utilities and lightmass subsystems. It is referenced in the MeshUtilities module and the UnrealLightmass program, which are responsible for generating distance fields and handling static lighting calculations.

The value of this variable is typically set in the engine configuration files, specifically in the Lightmass.ini file. It can be accessed and modified through the engine’s config system, as seen in the WriteSceneSettings function in Lightmass.cpp.

NumVoxelDistanceSamples interacts with other variables related to distance field generation, such as bUsePointQuery, which determines whether to use a point query approach or not. When bUsePointQuery is true, NumVoxelDistanceSamples is set to 49; otherwise, it’s set to 576.

Developers must be aware that this variable directly affects the quality and performance of distance field generation. A higher number of samples will result in more accurate distance fields but will also increase computation time and memory usage.

Best practices when using this variable include:

1. Balancing quality and performance by adjusting the number of samples based on the specific needs of the project.
2. Considering the target hardware capabilities when setting this value, as higher values may impact performance on less powerful devices.
3. Testing different values to find the optimal balance between quality and performance for your specific use case.
4. Being consistent with this setting across different parts of the project to ensure uniform distance field quality.

#Setting Variables

#References In INI files

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

• INI Section: DevOptions.VolumeDistanceField
• Raw value: 800
• Is Array: False

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Developer/MeshUtilities/Private/MeshDistanceFieldUtilities.cpp:287

Scope (from outer to inner):

file
function     void FMeshUtilities::GenerateSignedDistanceFieldVolumeData

Source code excerpt:

		TArray<FVector3f> SampleDirections;
		{
			const int32 NumVoxelDistanceSamples = bUsePointQuery ? 49 : 576;
			FRandomStream RandomStream(0);
			MeshUtilities::GenerateStratifiedUniformHemisphereSamples(NumVoxelDistanceSamples, RandomStream, SampleDirections);
			TArray<FVector3f> OtherHemisphereSamples;
			MeshUtilities::GenerateStratifiedUniformHemisphereSamples(NumVoxelDistanceSamples, RandomStream, OtherHemisphereSamples);

			for (int32 i = 0; i < OtherHemisphereSamples.Num(); i++)
			{
				FVector3f Sample = OtherHemisphereSamples[i];
				Sample.Z *= -1.0f;
				SampleDirections.Add(Sample);

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2301

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;
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumShadowRays"), Scene.ShadowSettings.NumShadowRays, GLightmassIni));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/VolumeDistanceField.cpp:76

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculateVolumeDistanceFieldWorkRange

Source code excerpt:

	TArray<FVector4f> SampleDirections;
	TArray<FVector2f> SampleDirectionUniforms;
	const int32 NumThetaSteps = FMath::TruncToInt(FMath::Sqrt(VolumeDistanceFieldSettings.NumVoxelDistanceSamples / (2.0f * (float)PI)));
	const int32 NumPhiSteps = FMath::TruncToInt(NumThetaSteps * (float)PI);
	FLMRandomStream RandomStream(0);
	GenerateStratifiedUniformHemisphereSamples(NumThetaSteps, NumPhiSteps, RandomStream, SampleDirections, SampleDirectionUniforms);
	TArray<FVector4f> OtherHemisphereSamples;
	TArray<FVector2f> OtherSampleDirectionUniforms;
	GenerateStratifiedUniformHemisphereSamples(NumThetaSteps, NumPhiSteps, RandomStream, OtherHemisphereSamples, OtherSampleDirectionUniforms);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FVolumeDistanceFieldSettings

Source code excerpt:

	 /** Number of distance traces for each voxel. */
	int32 NumVoxelDistanceSamples;

	/** Upper limit on the number of voxels that can be generated. */
	int32 MaxVoxels;
};

/** Shadow settings */