bUseMaxWeight

bUseMaxWeight

#Overview

name: bUseMaxWeight

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

#Summary

#Usage in the C++ source code

The purpose of bUseMaxWeight is to control the method of sample weighting when rasterizing texels in the static lighting system of Unreal Engine 5. It is primarily used for debugging and optimizing the lightmap generation process.

This setting variable is primarily used in the static lighting subsystem of Unreal Engine, specifically within the Lightmass module. It affects the texture mapping and rasterization processes during lightmap generation.

The value of this variable is set in the Lightmass configuration file (GLightmassIni) under the “DevOptions.StaticLighting” section. It is read and applied in the FLightmassExporter::WriteSceneSettings function.

bUseMaxWeight interacts with other variables in the texel rasterization process, such as SampleWeight, TotalSampleWeight, and MaxSampleWeight. It affects how these weights are calculated and applied during the rasterization of texels to vertices.

Developers must be aware that:

  1. This is primarily a debugging option and may affect the quality and performance of lightmap generation.
  2. When bUseMaxWeight is true, it uses the sample with the largest weight, which guarantees a valid position but may not be well-centered for texels on a UV seam.
  3. When false, it uses a weighted average approach, which may provide better centering but could potentially result in invalid positions.

Best practices when using this variable include:

  1. Use it primarily for debugging and optimization purposes.
  2. Test both true and false settings to determine which provides better results for your specific use case.
  3. Be aware of its impact on lightmap quality, especially in areas with UV seams or complex geometry.
  4. Consider the trade-off between position validity and centering when deciding which setting to use.
  5. Document the chosen setting and the reasoning behind it for future reference and team communication.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:21, 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:2131

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bVerifyEmbree"), bConfigBool, GLightmassIni));
		Scene.GeneralSettings.bVerifyEmbree = Scene.GeneralSettings.bUseEmbree && bConfigBool;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingRasterPolicy::ProcessPixel

Source code excerpt:

#endif

	if (bUseMaxWeight)
	{
		if (SampleWeight > TexelToVertex.MaxSampleWeight)
		{
			// Use the sample with the largest weight.  
			// This has the disadvantage compared averaging based on weight that it won't be well centered for texels on a UV seam,
			// But it has the advantage that the final position is guaranteed to be valid (ie actually on a triangle),

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingRasterPolicy::ProcessPixel

Source code excerpt:

		TexelToVertex.TotalSampleWeight += SampleWeight;
	}
	else if (!bUseMaxWeight)
	{
		// Update the sample weight, and compute the scales used to update the sample's averages.
		const float NewTotalSampleWeight = TexelToVertex.TotalSampleWeight + SampleWeight;		
		const float OldSampleWeight = TexelToVertex.TotalSampleWeight / NewTotalSampleWeight;	
		const float NewSampleWeight = SampleWeight / NewTotalSampleWeight;						
		TexelToVertex.TotalSampleWeight = NewTotalSampleWeight;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::RasterizeToSurfaceCacheTextureMapping

Source code excerpt:

						TriangleNormal,
						bDebugThisMapping,
						GeneralSettings.bUseMaxWeight
						));

					TexelMappingRasterizer.DrawTriangle(
						V0,
						V1,
						V2,

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::AdjustRepresentativeSurfelForTexelsTextureMapping

Source code excerpt:

					}
				}
				else if (GeneralSettings.bUseMaxWeight)
				{
					// Weighted average
					TexelToVertex.WorldTangentX = TexelToVertex.WorldTangentX / TexelToVertex.TotalSampleWeight;
					TexelToVertex.WorldTangentY = TexelToVertex.WorldTangentY / TexelToVertex.TotalSampleWeight;
					TexelToVertex.WorldTangentZ = TexelToVertex.WorldTangentZ / TexelToVertex.TotalSampleWeight;
					TexelToVertex.TriangleNormal = TexelToVertex.TriangleNormal / TexelToVertex.TotalSampleWeight;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::SetupTextureMapping

Source code excerpt:

							TriangleNormal,
							bDebugThisMapping,
							GeneralSettings.bUseMaxWeight
							));

						TexelMappingRasterizer.DrawTriangle(
							V0,
							V1,
							V2,

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMappingSetup.h:171

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingRasterPolicy
function     FStaticLightingRasterPolicy

Source code excerpt:

		TriangleNormal(InTriangleNormal),
		bDebugThisMapping(bInDebugThisMapping),
		bUseMaxWeight(bInUseMaxWeight)
	{}

protected:

	// FTriangleRasterizer policy interface.

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMappingSetup.h:196

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingRasterPolicy

Source code excerpt:

	const FVector4f TriangleNormal;
	const bool bDebugThisMapping;
	const bool bUseMaxWeight;
};

}

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:


	/** 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;

	/** Maximum samples for caching irradiance photons per triangle for vertex lightmaps. */
	int32 MaxTriangleIrradiancePhotonCacheSamples;