r.Shadow.Virtual.AccumulateStats

r.Shadow.Virtual.AccumulateStats

#Overview

name: r.Shadow.Virtual.AccumulateStats

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.Virtual.AccumulateStats is to control the collection and logging of Virtual Shadow Map (VSM) statistics over multiple frames. This setting is part of the rendering system, specifically related to the Virtual Shadow Maps feature in Unreal Engine 5.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly within the Virtual Shadow Maps subsystem. It’s defined and used in the VirtualShadowMapCacheManager.cpp file, which suggests it’s closely tied to the management and caching of virtual shadow maps.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 0, meaning the feature is disabled by default. Developers can enable it by setting it to a non-zero value.

This variable interacts directly with its associated variable CVarAccumulateStats. They share the same value and purpose, with CVarAccumulateStats being the actual TAutoConsoleVariable instance used in the code.

Developers must be aware that enabling this feature (by setting it to a non-zero value) will impact performance, as it will collect statistics over multiple frames and write them to a CSV file. This could be particularly noticeable in performance-sensitive scenarios or on lower-end hardware.

Best practices when using this variable include:

  1. Only enable it when necessary for debugging or performance analysis.
  2. Be mindful of the performance impact, especially in production builds.
  3. Ensure you have a system in place to collect and analyze the CSV files generated when this feature is enabled.
  4. Disable it when not actively debugging or profiling VSM performance.

Regarding the associated variable CVarAccumulateStats:

The purpose of CVarAccumulateStats is to provide a programmatic interface to the r.Shadow.Virtual.AccumulateStats setting. It’s the actual console variable instance used in the code to check if VSM stats accumulation is enabled.

This variable is used directly in the Renderer module, specifically in the VirtualShadowMapCacheManager class. It’s checked in the IsAccumulatingStats() method to determine if stats should be accumulated.

The value of CVarAccumulateStats is set indirectly through the r.Shadow.Virtual.AccumulateStats console command. It’s initialized with a default value of 0.

CVarAccumulateStats interacts directly with r.Shadow.Virtual.AccumulateStats, sharing the same value and purpose.

Developers should be aware that this variable is accessed on the render thread (as indicated by the GetValueOnRenderThread() call), which means changes to it will be applied on the next frame.

Best practices for using CVarAccumulateStats include:

  1. Use the IsAccumulatingStats() method rather than accessing the console variable directly when checking if stats should be accumulated.
  2. Be aware of the potential performance impact when this variable is set to a non-zero value.
  3. Consider wrapping stat accumulation code in preprocessor macros for easier debugging and to potentially strip it out of shipping builds.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:18

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarAccumulateStats(
	TEXT("r.Shadow.Virtual.AccumulateStats"),
	0,
	TEXT("When enabled, VSM stats will be collected over multiple frames and written to a CSV file"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarCacheVirtualSMs(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:17

Scope: file

Source code excerpt:

CSV_DECLARE_CATEGORY_EXTERN(VSM);

static TAutoConsoleVariable<int32> CVarAccumulateStats(
	TEXT("r.Shadow.Virtual.AccumulateStats"),
	0,
	TEXT("When enabled, VSM stats will be collected over multiple frames and written to a CSV file"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:1175

Scope (from outer to inner):

file
function     bool FVirtualShadowMapArrayCacheManager::IsAccumulatingStats

Source code excerpt:

bool FVirtualShadowMapArrayCacheManager::IsAccumulatingStats()
{
	return CVarAccumulateStats.GetValueOnRenderThread() != 0;
}

static uint32 GetPrimFlagsBufferSizeInDwords(int32 MaxPersistentPrimitiveIndex)
{
	return FMath::RoundUpToPowerOfTwo(FMath::DivideAndRoundUp(MaxPersistentPrimitiveIndex, 32));
}