r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize

r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize

#Overview

name: r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize

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

• type: Var
• help: Maximum number of instances that may be output from the culling pass into all VSM mip/clip levels. At 12 byte per instance reference this represents a 1.5GB clamp.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize is to control the maximum number of instances that can be output from the culling pass into all Virtual Shadow Map (VSM) mip/clip levels for non-Nanite objects in Unreal Engine’s rendering system.

This setting variable is primarily used in the rendering subsystem, specifically in the Virtual Shadow Map implementation. It’s part of the shadow rendering pipeline, which is crucial for creating realistic lighting and shadows in a game or application.

The value of this variable is set through a console variable (CVar) in the Unreal Engine source code. It’s initialized with a default value of 128 * 1024 * 1024, which represents 128 MB.

The associated variable CVarNonNaniteMaxCulledInstanceAllocationSize directly interacts with r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize. They share the same value and purpose.

Developers must be aware that this variable sets a limit on the memory allocation for instance references in the Virtual Shadow Map system. As mentioned in the comment, at 12 bytes per instance reference, the default value represents a 1.5GB clamp. This limit is crucial for managing memory usage in the rendering pipeline.

Best practices when using this variable include:

1. Monitor performance and visual quality to ensure the default value is sufficient for your project.
2. If shadow artifacts appear or if the engine reports warnings about instance culling overflow, consider increasing this value.
3. Be cautious when increasing this value, as it directly impacts memory usage. Balance it with available system resources.
4. Use in conjunction with r.Shadow.Virtual.NonNanite.CulledInstanceAllocationFactor to fine-tune the instance allocation without necessarily increasing the maximum limit.

Regarding the associated variable CVarNonNaniteMaxCulledInstanceAllocationSize:

This is the actual console variable that controls the setting. It’s used in the same way as r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize and shares the same considerations. When adjusting the setting in-engine or through configuration files, you would use the r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize name, which internally modifies CVarNonNaniteMaxCulledInstanceAllocationSize.

The variable is used in the culling process to determine the maximum number of instances that can be processed. It’s important for preventing buffer overflows and managing memory usage in the Virtual Shadow Map system, particularly for non-Nanite objects.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:157

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarNonNaniteMaxCulledInstanceAllocationSize(
	TEXT("r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize"),
	128 * 1024 * 1024,
	TEXT("Maximum number of instances that may be output from the culling pass into all VSM mip/clip levels. At 12 byte per instance reference this represents a 1.5GB clamp."),
	ECVF_RenderThreadSafe
);
static TAutoConsoleVariable<int32> CVarShowClipmapStats(
	TEXT("r.Shadow.Virtual.ShowClipmapStats"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:156

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarNonNaniteMaxCulledInstanceAllocationSize(
	TEXT("r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize"),
	128 * 1024 * 1024,
	TEXT("Maximum number of instances that may be output from the culling pass into all VSM mip/clip levels. At 12 byte per instance reference this represents a 1.5GB clamp."),
	ECVF_RenderThreadSafe
);
static TAutoConsoleVariable<int32> CVarShowClipmapStats(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:2293

Scope: file

Source code excerpt:

	// TotalViewScaledInstanceCount is conservative since it is the number of instances needed if each instance was drawn into every possible mip-level.
	// This is far more than we'd expect in reasonable circumstances, so we use a scale factor to reduce memory pressure from these passes.
	const uint32 MaxCulledInstanceCount = uint32(CVarNonNaniteMaxCulledInstanceAllocationSize.GetValueOnRenderThread());
	const uint32 ScaledInstanceCount = static_cast<uint32>(static_cast<double>(TotalViewScaledInstanceCount) * CVarNonNaniteCulledInstanceAllocationFactor.GetValueOnRenderThread());
	ensureMsgf(ScaledInstanceCount <= MaxCulledInstanceCount, TEXT("Possible non-nanite VSM Instance culling overflow detected (esitmated required size: %d, if visual artifacts appear either increase the r.Shadow.Virtual.NonNanite.MaxCulledInstanceAllocationSize (%d) or reduce r.Shadow.Virtual.NonNanite.CulledInstanceAllocationFactor (%.2f)"), ScaledInstanceCount, MaxCulledInstanceCount, CVarNonNaniteCulledInstanceAllocationFactor.GetValueOnRenderThread());
	CullingResult.MaxNumInstancesPerPass = FMath::Clamp(ScaledInstanceCount, 1u, MaxCulledInstanceCount);

	FRDGBufferRef VisibleInstancesRdg = CreateStructuredBuffer(GraphBuilder, TEXT("Shadow.Virtual.VisibleInstances"), sizeof(FVSMVisibleInstanceCmd), CullingResult.MaxNumInstancesPerPass, nullptr, 0);