SmallestTexelRadius

SmallestTexelRadius

#Overview

name: SmallestTexelRadius

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 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of SmallestTexelRadius is to define a minimum threshold for texel radius calculations in Unreal Engine’s lightmass system, which is part of the static lighting and global illumination solution. It’s primarily used in the rendering system, specifically for static lighting calculations.

This setting variable is primarily used in the Lightmass module of Unreal Engine, which is responsible for precomputing static lighting information. It’s referenced in both the editor-side code (UnrealEd) and the Lightmass program itself.

The value of this variable is typically set in the Lightmass configuration file (Lightmass.ini). It’s read from the configuration file in the FLightmassExporter::WriteSceneSettings function.

SmallestTexelRadius interacts with several other variables in the lighting system, such as VisibilityNormalOffsetSampleRadiusScale, StaticLightingLevelScale, and various sample radius calculations.

Developers should be aware that this variable affects the precision and performance of static lighting calculations. Setting it too low might increase computation time and memory usage, while setting it too high might result in loss of lighting detail in small or intricate areas of the scene.

Best practices when using this variable include:

  1. Adjust it carefully based on the scale and detail level of your scene.
  2. Consider the performance implications of very small values.
  3. Use it in conjunction with other lighting settings for optimal results.
  4. Test different values to find the right balance between lighting quality and performance for your specific project.

#Setting Variables

#References In INI files

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

#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:2185

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("VisibilityNormalOffsetSampleRadiusScale"), Scene.SceneConstants.VisibilityNormalOffsetSampleRadiusScale, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("VisibilityTangentOffsetSampleRadiusScale"), Scene.SceneConstants.VisibilityTangentOffsetSampleRadiusScale, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("SmallestTexelRadius"), Scene.SceneConstants.SmallestTexelRadius, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("LightGridSize"), Scene.SceneConstants.LightGridSize, GLightmassIni));
	}
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLightingMaterial"), TEXT("bUseDebugMaterial"), bConfigBool, GLightmassIni));
		Scene.MaterialSettings.bUseDebugMaterial = bConfigBool;
		FString ShowMaterialAttributeName;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/LightmassScene.cpp:513

Scope (from outer to inner):

file
namespace    Lightmass
function     void FScene::ApplyStaticLightingScale

Source code excerpt:

	SceneConstants.VisibilityRayOffsetDistance *= SceneConstants.StaticLightingLevelScale;
	SceneConstants.VisibilityNormalOffsetDistance *= SceneConstants.StaticLightingLevelScale;
	SceneConstants.SmallestTexelRadius *= SceneConstants.StaticLightingLevelScale;
	MeshAreaLightSettings.MeshAreaLightSimplifyCornerDistanceThreshold *= SceneConstants.StaticLightingLevelScale;
	MeshAreaLightSettings.MeshAreaLightGeneratedDynamicLightSurfaceOffset *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.FirstSurfaceSampleLayerHeight *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.SurfaceLightSampleSpacing *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.SurfaceSampleLayerHeightSpacing *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.DetailVolumeSampleSpacing *= SceneConstants.StaticLightingLevelScale;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:1624

Scope (from outer to inner):

file
namespace    Lightmass
function     FFinalGatherSample FStaticLightingSystem::CachePointIncomingRadiance

Source code excerpt:

					// Make the irradiance cache sample radius very small for texels whose radius is close to the minimum, 
					// Since those texels are usually in corners and not representative of their neighbors.
					if (SampleRadius < SceneConstants.SmallestTexelRadius * 2.0f)
					{
						OverrideRadius = SceneConstants.SmallestTexelRadius;
					}
					else if (GatherInfo.MinDistance > SampleRadius)
					{
						// When uniform final gather rays are offset from the center of the texel, 
						// It's possible for a perpendicular surface to intersect the center of the texel and none of the final gather rays detect it.
						// The lighting cache sample will be assigned a large radius and the artifact will be interpolated a large distance.

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:483

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::AdjustRepresentativeSurfelForTexelsTextureMapping

Source code excerpt:

				else
				{
					MinDistanceSquared = SceneConstants.SmallestTexelRadius;
				}
				TexelToVertex.TexelRadius = FMath::Max(FMath::Sqrt(MinDistanceSquared), SceneConstants.SmallestTexelRadius);
				TexelToVertex.SampleRadius = TexelToVertex.TexelRadius;
				MappingContext.Stats.NumMappedTexels++;

				{
					const FFullStaticLightingVertex FullVertex = TexelToVertex.GetFullVertex();
					const FVector4f TexelCenterOffset = FullVertex.WorldPosition + FullVertex.TriangleNormal * TexelToVertex.TexelRadius * SceneConstants.VisibilityNormalOffsetSampleRadiusScale;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:540

Scope: file

Source code excerpt:

							}

							if (bHitBackfaces[CornerIndex] && (DistanceSquared < ClosestBackfacingIntersectionDistanceSq && !FMath::IsNearlyEqual(DistanceSquared, ClosestBackfacingIntersectionDistanceSq, SceneConstants.SmallestTexelRadius)))
							{
								ClosestBackfacingIntersectionDistanceSq = DistanceSquared;
								ClosestBackfacingIntersectionIndex = CornerIndex;

								// Mark the texel as intersecting another surface so we can avoid filtering across it later
								TexelToVertex.bIntersectingSurface = true;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:583

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::AdjustRepresentativeSurfelForTexelsTextureMapping

Source code excerpt:

					}

					TexelToVertex.SampleRadius = FMath::Max(TexelToVertex.SampleRadius, SceneConstants.SmallestTexelRadius);
				}
			}
			else
			{
				if (LightMapData != nullptr)
				{

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSceneConstants

Source code excerpt:

	 * This should be smaller than the smallest valid texel radius in the scene.
	 */
	float SmallestTexelRadius;

	/** 
	 * Size of the grid that each light will use to cache information.  
	 * Larger grids take longer to precompute, but result in accelerated light sampling.
	 */
	int32 LightGridSize;