MappingSurfaceCacheDownsampleFactor

MappingSurfaceCacheDownsampleFactor

#Overview

name: MappingSurfaceCacheDownsampleFactor

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

#Summary

#Usage in the C++ source code

The purpose of MappingSurfaceCacheDownsampleFactor is to control the downsample factor for the surface cache used in static lighting calculations, particularly in the Lightmass system of Unreal Engine 5.

This setting variable is primarily used in the static lighting and global illumination subsystems of Unreal Engine 5. It is specifically utilized in the Lightmass module, which is responsible for precomputed lighting calculations.

The value of this variable is set in the Unreal Engine configuration files. It is read from the “DevOptions.StaticLighting” section of the Lightmass configuration file (GLightmassIni) during the scene export process for lighting calculations.

MappingSurfaceCacheDownsampleFactor interacts with other variables related to texture mapping and surface cache calculations. It directly affects the calculation of SurfaceCacheSizeX and SurfaceCacheSizeY in the FStaticLightingTextureMapping::Initialize function.

Developers must be aware that this variable affects the resolution of the surface cache used in lighting calculations. A higher value will result in a lower resolution cache, which can improve performance but may reduce the quality of lighting details.

Best practices when using this variable include:

  1. Balancing between performance and lighting quality. Lower values provide higher quality but increase computation time.
  2. Considering the scale and detail level of your scene when adjusting this value.
  3. Testing different values to find the optimal balance for your specific project.
  4. Being cautious when modifying this value, as it can significantly impact both the quality of lighting and the time required for lightmass calculations.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseFastVoxelization"), Scene.GeneralSettings.bUseFastVoxelization, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseEmbreeInstancing"), Scene.GeneralSettings.bUseEmbreeInstancing, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLighting"), TEXT("MappingSurfaceCacheDownsampleFactor"), Scene.GeneralSettings.MappingSurfaceCacheDownsampleFactor, GLightmassIni));

		int32 CheckQualityLevel;
		GConfig->GetInt( TEXT("LightingBuildOptions"), TEXT("QualityLevel"), CheckQualityLevel, GEditorPerProjectIni);
		CheckQualityLevel = FMath::Clamp<int32>(CheckQualityLevel, Quality_Preview, Quality_Production);
		UE_LOG(LogLightmassSolver, Log, TEXT("LIGHTMASS: Writing scene settings: Quality level %d (%d in INI)"), (int32)(QualityLevel), CheckQualityLevel);
		if (CheckQualityLevel != QualityLevel)

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingTextureMapping::Initialize

Source code excerpt:

void FStaticLightingTextureMapping::Initialize(FStaticLightingSystem& System)
{
	SurfaceCacheSizeX = FMath::Max(FMath::TruncToInt((float)CachedSizeX / (float)System.GeneralSettings.MappingSurfaceCacheDownsampleFactor), 6);
	SurfaceCacheSizeY = FMath::Max(FMath::TruncToInt((float)CachedSizeY / (float)System.GeneralSettings.MappingSurfaceCacheDownsampleFactor), 6);
}

/** Caches irradiance photons on a single texture mapping. */
void FStaticLightingSystem::CacheIrradiancePhotonsTextureMapping(FStaticLightingTextureMapping* TextureMapping)
{
	checkSlow(TextureMapping);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:

	 * This controls the downsample factor for that cache, relative to the mapping's lightmap resolution.
	 */
	int32 MappingSurfaceCacheDownsampleFactor;

	/** 
	 * Smoothness factor to apply to indirect lighting.  This is useful in some lighting conditions when Lightmass cannot resolve accurate indirect lighting.
	 * 1 is default smoothness tweaked for a variety of lighting situations.
	 * Higher values like 3 smooth out the indirect lighting more, but at the cost of indirect shadows losing detail as well.
	 */