CacheTaskSize

CacheTaskSize

#Overview

name: CacheTaskSize

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 CacheTaskSize is to control the parallelization of irradiance caching calculations in Unreal Engine’s lightmass system. It is used to divide texture mappings into smaller blocks for processing, which allows for better distribution of work across multiple threads.

This setting variable is primarily used in the lightmass and static lighting systems of Unreal Engine. It is referenced in the UnrealEd module and the UnrealLightmass program, which are responsible for lighting calculations and baking.

The value of this variable is typically set in the Lightmass configuration file (GLightmassIni). It is read from the configuration file in the “DevOptions.IrradianceCache” section.

CacheTaskSize interacts with other irradiance caching settings, such as InterpolateTaskSize. Together, these variables control how the lightmass system breaks down and processes lighting calculations.

Developers should be aware that:

  1. Smaller CacheTaskSize values allow for better parallelization, potentially improving performance on multi-core systems.
  2. Larger values (e.g., 4096) can effectively make irradiance caching single-threaded for a given mapping, which can be useful for debugging purposes.
  3. The optimal value may depend on the specific hardware and scene complexity.

Best practices when using this variable include:

  1. Experiment with different values to find the optimal balance between parallelization and overhead for your specific project and hardware.
  2. Consider adjusting this value in conjunction with other irradiance caching settings for best results.
  3. Use larger values when debugging lighting issues to simplify the process and reduce potential sources of variability.
  4. Document the chosen value and the reasoning behind it for future reference and team communication.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("SkyOcclusionSmoothnessReduction"), Scene.IrradianceCachingSettings.SkyOcclusionSmoothnessReduction, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("MaxRecordRadius"), Scene.IrradianceCachingSettings.MaxRecordRadius, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.IrradianceCache"), TEXT("CacheTaskSize"), Scene.IrradianceCachingSettings.CacheTaskSize, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.IrradianceCache"), TEXT("InterpolateTaskSize"), Scene.IrradianceCachingSettings.InterpolateTaskSize, GLightmassIni));
	}

	// Modify settings based on the quality level required
	// Preview is assumed to have a scale of 1 for all settings and therefore is not in the ini
	if (QualityLevel != Quality_Preview)

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculateIndirectLightingTextureMapping

Source code excerpt:

		const double StartCacheTime = FPlatformTime::Seconds();

		const int32 CacheTaskSize = IrradianceCachingSettings.CacheTaskSize;
		int32 NumTasksSubmitted = 0;

		// Break this mapping into multiple caching tasks in texture space blocks
		for (int32 TaskY = 0; TaskY < TextureMapping->CachedSizeY; TaskY += CacheTaskSize)
		{
			for (int32 TaskX = 0; TaskX < TextureMapping->CachedSizeX; TaskX += CacheTaskSize)
			{
				FCacheIndirectTaskDescription* NewTask = new FCacheIndirectTaskDescription(TextureMapping->Mesh, *this);
				NewTask->StartX = TaskX;
				NewTask->StartY = TaskY;
				NewTask->SizeX = FMath::Min(CacheTaskSize, TextureMapping->CachedSizeX - TaskX);
				NewTask->SizeY = FMath::Min(CacheTaskSize, TextureMapping->CachedSizeY - TaskY);
				NewTask->TextureMapping = TextureMapping;
				NewTask->LightMapData = &LightMapData;
				NewTask->TexelToVertexMap = &TexelToVertexMap;
				
				NewTask->bDebugThisMapping = bDebugThisMapping
					&& (!bDebugSelectedTaskOnly 
						|| (Scene.DebugInput.LocalX >= TaskX && Scene.DebugInput.LocalX < TaskX + CacheTaskSize
						&& Scene.DebugInput.LocalY >= TaskY && Scene.DebugInput.LocalY < TaskY + CacheTaskSize));

				NumTasksSubmitted++;

				// Add to the queue so other lighting threads can pick up these tasks
				FPlatformAtomics::InterlockedIncrement(&TextureMapping->NumOutstandingCacheTasks);
				CacheIndirectLightingTasks.Push(NewTask);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FIrradianceCachingSettings

Source code excerpt:

	 * Setting this to a large value like 4096 will effectively make the irradiance caching single threaded for a given mapping, which is useful for debugging.
	 */
	int32 CacheTaskSize;

	/** 
	 * Task size for parallelization of irradiance cache interpolation within a mapping.  A mapping will be split into pieces of this size which allows other threads to help.
	 * Smaller settings allow better parallelization.
	 * Setting this to a large value like 4096 will effectively make the irradiance cache interpolation single threaded for a given mapping, which is useful for debugging.
	 */