bAccountForTexelSize

bAccountForTexelSize

#Overview

name: bAccountForTexelSize

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

#Summary

#Usage in the C++ source code

The purpose of bAccountForTexelSize is to control whether the lighting system should consider the size of texels in various lighting calculations. This setting is primarily used in the static lighting and lightmass systems of Unreal Engine 5.

The Unreal Engine subsystems that rely on this setting variable are primarily the static lighting system and the Lightmass global illumination solver. It’s used in the UnrealEd module for scene export and in the UnrealLightmass program for lighting calculations.

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.

This variable interacts with other lighting-related variables, such as bUseConservativeTexelRasterization and bUseMaxWeight. It also affects calculations involving SampleRadius and VisibilityTangentOffsetSampleRadiusScale.

Developers must be aware that enabling this setting can significantly impact lighting calculations, especially for scenes with varying texel sizes. It’s particularly effective for large texels with high variance in incoming radiance over the area of the texel.

Best practices when using this variable include:

  1. Use it in conjunction with other lighting settings for optimal results.
  2. Be aware of its performance impact, as it can increase computation time.
  3. Test thoroughly with and without this setting enabled to ensure desired lighting quality.
  4. Consider the scale and detail of your scene when deciding whether to enable this setting.
  5. Monitor its effect on shadow penumbras and corner lighting, as it can significantly affect these areas.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseConservativeTexelRasterization"), bConfigBool, GLightmassIni));
		Scene.GeneralSettings.bUseConservativeTexelRasterization = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bAccountForTexelSize"), bConfigBool, GLightmassIni));
		Scene.GeneralSettings.bAccountForTexelSize = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseMaxWeight"), bConfigBool, GLightmassIni));
		Scene.GeneralSettings.bUseMaxWeight = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLighting"), TEXT("MaxTriangleLightingSamples"), Scene.GeneralSettings.MaxTriangleLightingSamples, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLighting"), TEXT("MaxTriangleIrradiancePhotonCacheSamples"), Scene.GeneralSettings.MaxTriangleIrradiancePhotonCacheSamples, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseEmbree"), bConfigBool, GLightmassIni));
		Scene.GeneralSettings.bUseEmbree = bConfigBool;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::IntersectLightRays

Source code excerpt:


		FVector4f SampleOffset(0,0,0);
		if (GeneralSettings.bAccountForTexelSize)
		{
			// Offset the sample's starting point in the tangent XY plane based on the sample's area of influence. 
			// This is particularly effective for large texels with high variance in the incoming radiance over the area of the texel.
			SampleOffset = Vertex.WorldTangentX * TangentPathDirection.X * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale
				+ Vertex.WorldTangentY * TangentPathDirection.Y * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FFinalGatherSample FStaticLightingSystem::CachePointIncomingRadiance

Source code excerpt:

				float OverrideRadius = 0;

				if (GeneralSettings.bAccountForTexelSize)
				{
					// 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;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:2474

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings
function     FVector2f FStaticLightingSystem::CalculatePointAreaShadowing

Source code excerpt:

			const FVector4f LightVector = CurrentSample.Position - Vertex.WorldPosition;
			FVector4f SampleOffset(0,0,0);
			if (GeneralSettings.bAccountForTexelSize)
			{
				/*
				//@todo - the rays cross over on the way to the light and mess up penumbra shapes.  
				//@todo - need to use more than texel size, otherwise BSP generates lots of texels that become half shadowed at corners
				SampleOffset = Vertex.WorldTangentX * LightPositionSamples(RayIndex).DiskPosition.X * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale
					+ Vertex.WorldTangentY * LightPositionSamples(RayIndex).DiskPosition.Y * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:


	/** Debugging - whether to use the texel size in various calculations in an attempt to compensate for point sampling a texel. */
	bool bAccountForTexelSize;

	/** Debugging - whether to use the sample with the largest weight when rasterizing texels or a linear combination. */
	bool bUseMaxWeight;

	/** Maximum lighting samples per triangle for vertex lightmaps. */
	int32 MaxTriangleLightingSamples;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSceneConstants

Source code excerpt:

	/** 
	 * Fraction of the sample radius to offset the origin of the ray in the tangent XY plane, based on the direction of the ray.
	 * This is only used when bAccountForTexelSize is true.
	 */
	float VisibilityTangentOffsetSampleRadiusScale;

	/** 
	 * Smallest texel radius allowed, useful for clamping edge cases where some texels have a radius of 0. 
	 * This should be smaller than the smallest valid texel radius in the scene.
	 */
	float SmallestTexelRadius;