r.IESAtlas.ForceUpdate

r.IESAtlas.ForceUpdate

#Overview

name: r.IESAtlas.ForceUpdate

This variable is created as a Console Variable (cvar).

• type: Var
• help: Force IES atlas to update very frame.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.IESAtlas.ForceUpdate is to force the IES (Illuminating Engineering Society) atlas to update every frame in Unreal Engine 5’s rendering system. This setting is primarily used for debugging and performance testing purposes.

This setting variable is used in the Renderer module of Unreal Engine 5, specifically within the IES texture management system. The IES atlas is a texture atlas that stores multiple IES light profiles, which are used to define the distribution of light from light sources.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with an initial value of 0, meaning it’s disabled by default.

The associated variable CVarIESForceUpdate interacts directly with r.IESAtlas.ForceUpdate. They share the same value and are used interchangeably in the code.

Developers must be aware that enabling this variable (setting it to a value greater than 0) will cause the IES atlas to update every frame, which can have significant performance implications. This should only be used for debugging or testing purposes, not in production builds.

Best practices when using this variable include:

1. Only enable it when necessary for debugging or testing.
2. Be aware of the performance impact when enabled.
3. Always disable it (set to 0) before creating production builds.
4. Use in conjunction with other IES-related console variables for comprehensive debugging.

Regarding the associated variable CVarIESForceUpdate:

The purpose of CVarIESForceUpdate is the same as r.IESAtlas.ForceUpdate. It’s the C++ variable that directly controls the behavior defined by the console variable.

This variable is used in the same Renderer module and IES texture management system. It’s typically accessed using the GetValueOnRenderThread() method to determine if forced updates are enabled.

The value of CVarIESForceUpdate is set automatically by the console variable system when r.IESAtlas.ForceUpdate is modified.

CVarIESForceUpdate interacts with other variables in the IES texture management system, such as CVarIESTextureResolution and CVarIESTextureMaxProfileCount, to control the behavior of the IES atlas updates.

Developers should be aware that this variable is accessed on the render thread, so any changes to it will affect rendering in the next frame.

Best practices for CVarIESForceUpdate are the same as for r.IESAtlas.ForceUpdate, with the addition that developers should avoid directly modifying this variable in code, instead using the console variable r.IESAtlas.ForceUpdate to control its value.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IESTextureManager.cpp:44

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarIESForceUpdate(
	TEXT("r.IESAtlas.ForceUpdate"),
	0,
	TEXT("Force IES atlas to update very frame."),
	ECVF_RenderThreadSafe);

namespace IESAtlas
{

#Associated Variable and Callsites

This variable is associated with another variable named CVarIESForceUpdate. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IESTextureManager.cpp:43

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarIESForceUpdate(
	TEXT("r.IESAtlas.ForceUpdate"),
	0,
	TEXT("Force IES atlas to update very frame."),
	ECVF_RenderThreadSafe);

namespace IESAtlas

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IESTextureManager.cpp:152

Scope (from outer to inner):

file
namespace    IESAtlas
function     static FRDGTextureRef AddIESDebugPass

Source code excerpt:

	Parameters->UsedSliceCount = 0;
	Parameters->TotalSlotCount = 0;
	Parameters->bForceUpdate = CVarIESForceUpdate.GetValueOnRenderThread() > 0 ? 1u : 0u;
	Parameters->OutputResolution = OutputResolution;
	Parameters->AtlasSampler = TStaticSamplerState<SF_Bilinear, AM_Clamp, AM_Clamp, AM_Clamp>::GetRHI();
	Parameters->AtlasTexture = AtlasTexture;
	Parameters->ViewUniformBuffer = View.ViewUniformBuffer;
	ShaderPrint::SetParameters(GraphBuilder, View.ShaderPrintData, Parameters->ShaderPrintParameters);
	Parameters->OutputTexture = GraphBuilder.CreateUAV(OutputTexture);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IESTextureManager.cpp:508

Scope (from outer to inner):

file
namespace    IESAtlas
function     void UpdateAtlasTexture

Source code excerpt:

	// * If a global update is requested, invalid all slots
	// * Otherwise invalid slots which have new texture data (e.g., streamed in)
	const bool bForceUpdate = CVarIESForceUpdate.GetValueOnRenderThread() > 0 || bForceRecreate;
	if (bForceUpdate)
	{
		CachedAtlasResolution = CVarIESTextureResolution.GetValueOnRenderThread();
		CachedAtlasMaxSlice = CVarIESTextureMaxProfileCount.GetValueOnRenderThread();
		InvalidateSlots(GIESTextureManager, RequestedSliceCount);
	}