r.Shadow.AlwaysAllocateMaxResolutionAtlases

r.Shadow.AlwaysAllocateMaxResolutionAtlases

#Overview

name: r.Shadow.AlwaysAllocateMaxResolutionAtlases

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.AlwaysAllocateMaxResolutionAtlases is to control the allocation of shadow map atlases in Unreal Engine’s rendering system. This setting variable is specifically related to memory management and optimization of shadow rendering.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the shadow setup and allocation process. It’s referenced in the ShadowSetup.cpp file, which is part of the rendering subsystem.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0, meaning it’s disabled by default. Developers can change this value at runtime using console commands or through configuration files.

The associated variable CVarAlwaysAllocateMaxResolutionAtlases directly interacts with r.Shadow.AlwaysAllocateMaxResolutionAtlases. They share the same value and purpose.

Developers must be aware that enabling this variable (setting it to a non-zero value) will cause the engine to always allocate shadow map atlases at the maximum resolution, even if some space is unused. This can lead to increased memory usage but may help reduce render target pool fragmentation and thrashing.

Best practices when using this variable include:

  1. Only enable it if you’re experiencing issues with render target pool fragmentation or thrashing.
  2. Monitor memory usage closely when this is enabled, as it will increase memory consumption.
  3. Consider the trade-off between memory usage and potential performance improvements in specific scenarios.
  4. Use it in conjunction with profiling tools to determine if it’s actually beneficial for your specific use case.

Regarding the associated variable CVarAlwaysAllocateMaxResolutionAtlases:

The purpose of CVarAlwaysAllocateMaxResolutionAtlases is identical to r.Shadow.AlwaysAllocateMaxResolutionAtlases. It’s the internal representation of the console variable in the C++ code.

This variable is used in the Renderer module, specifically in the shadow allocation process. It’s checked in the FSceneRenderer::AllocateAtlasedShadowDepthTargets function to determine whether to use the maximum texture size for shadow map atlases.

The value of this variable is set through the CVar system, initialized with the same default value (0) and description as r.Shadow.AlwaysAllocateMaxResolutionAtlases.

CVarAlwaysAllocateMaxResolutionAtlases directly interacts with the shadow allocation logic. When its value is non-zero, it forces the AtlasSize to be set to the MaxTextureSize.

Developers should be aware that this variable’s value is accessed on the render thread (GetValueOnRenderThread()), which is important for thread safety in rendering operations.

The best practices for using CVarAlwaysAllocateMaxResolutionAtlases are the same as those for r.Shadow.AlwaysAllocateMaxResolutionAtlases, as they represent the same setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:301

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarAlwaysAllocateMaxResolutionAtlases(
	TEXT("r.Shadow.AlwaysAllocateMaxResolutionAtlases"),
	0,
	TEXT("If enabled, will always allocate shadow map atlases at the maximum resolution rather than trimming unused space. This will waste more memory but can possibly reduce render target pool fragmentation and thrash."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarVsmUseFarShadowRules(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:300

Scope: file

Source code excerpt:

	);

static TAutoConsoleVariable<int32> CVarAlwaysAllocateMaxResolutionAtlases(
	TEXT("r.Shadow.AlwaysAllocateMaxResolutionAtlases"),
	0,
	TEXT("If enabled, will always allocate shadow map atlases at the maximum resolution rather than trimming unused space. This will waste more memory but can possibly reduce render target pool fragmentation and thrash."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:5771

Scope (from outer to inner):

file
function     void FSceneRenderer::AllocateAtlasedShadowDepthTargets

Source code excerpt:

			FMath::Min((uint32)MaxTextureSize.Y, FMath::RoundUpToPowerOfTwo(CurrentLayout.TextureLayout.GetSizeY())));

		if (CVarAlwaysAllocateMaxResolutionAtlases.GetValueOnRenderThread() != 0)
		{
			AtlasSize = MaxTextureSize;
		}

		FPooledRenderTargetDesc ShadowMapDesc2D = FPooledRenderTargetDesc::Create2DDesc(AtlasSize, PF_ShadowDepth, FClearValueBinding::DepthOne, TexCreate_None, TexCreate_DepthStencilTargetable | TexCreate_ShaderResource, false);
		ShadowMapDesc2D.Flags |= GFastVRamConfig.ShadowPerObject;