r.Nanite.MaxVisibleClusters

r.Nanite.MaxVisibleClusters

#Overview

name: r.Nanite.MaxVisibleClusters

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Nanite.MaxVisibleClusters is to control the maximum number of visible Nanite clusters in the rendering system. This setting is crucial for the Nanite virtualized geometry system in Unreal Engine 5.

This setting variable is primarily used by the Nanite subsystem within the Renderer module of Unreal Engine 5. It’s specifically utilized in the NaniteShared and NaniteFeedback components.

The value of this variable is set through the console variable system. It’s initialized with a default value of 4 * 1048576 (4 million) clusters and can be modified at runtime.

The associated variable GNaniteMaxVisibleClusters directly interacts with r.Nanite.MaxVisibleClusters. They share the same value, with GNaniteMaxVisibleClusters being the actual integer variable used in the C++ code.

Developers must be aware that this variable has a significant impact on memory usage and rendering performance. Setting it too low might cause visual artifacts, while setting it too high could lead to unnecessary memory consumption.

Best practices when using this variable include:

  1. Monitor the actual usage of visible clusters in your scenes.
  2. Adjust the value based on the complexity of your geometry and the target hardware capabilities.
  3. Be cautious when increasing this value, as it directly affects memory usage.
  4. Use the feedback system (as seen in NaniteFeedback.cpp) to detect and respond to overflow situations.

Regarding the associated variable GNaniteMaxVisibleClusters:

The purpose of GNaniteMaxVisibleClusters is to provide a C++ accessible integer representation of the r.Nanite.MaxVisibleClusters setting.

This variable is used directly in the Nanite subsystem of the Renderer module, particularly in the FGlobalResources class.

The value of GNaniteMaxVisibleClusters is set by the console variable system when r.Nanite.MaxVisibleClusters is modified.

GNaniteMaxVisibleClusters interacts directly with r.Nanite.MaxVisibleClusters and is used in various Nanite-related calculations and checks.

Developers should be aware that modifying GNaniteMaxVisibleClusters directly in code is not recommended. Instead, they should use the console variable r.Nanite.MaxVisibleClusters to ensure proper synchronization.

Best practices for GNaniteMaxVisibleClusters include:

  1. Use it for read-only operations in C++ code.
  2. Ensure that any code using this variable can handle potential runtime changes to its value.
  3. Use the FGlobalResources::GetMaxVisibleClusters() method to access this value, as it provides additional safety checks.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteShared.cpp:47

Scope: file

Source code excerpt:

int32 GNaniteMaxVisibleClusters = 4 * 1048576;
FAutoConsoleVariableRef CVarNaniteMaxVisibleClusters(
	TEXT("r.Nanite.MaxVisibleClusters"),
	GNaniteMaxVisibleClusters,
	TEXT("Maximum number of visible Nanite clusters."),
	ECVF_RenderThreadSafe
);

int32 GNaniteMaxCandidatePatches = 2 * 1048576;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteFeedback.cpp:91

Scope (from outer to inner):

file
function     FFeedbackManager::FFeedbackManager
lambda-function

Source code excerpt:

				FText::Format(LOCTEXT("NaniteVisibleClusterOverflow",
					"Nanite visible cluster buffer overflow detected: {0} / {1}. High-water mark is {2}. "
					"Increase r.Nanite.MaxVisibleClusters to prevent potential visual artifacts."),
					VisibleClusterState.LatestOverflowPeak, MaxVisibleClusters, VisibleClusterState.HighWaterMark));
		}

		if (CVarEmitMaterialPerformanceWarnings.GetValueOnAnyThread() != 0)
		{
			FScopeLock Lock(&DelgateCallbackCS);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteShared.cpp:45

Scope: file

Source code excerpt:

);

int32 GNaniteMaxVisibleClusters = 4 * 1048576;
FAutoConsoleVariableRef CVarNaniteMaxVisibleClusters(
	TEXT("r.Nanite.MaxVisibleClusters"),
	GNaniteMaxVisibleClusters,
	TEXT("Maximum number of visible Nanite clusters."),
	ECVF_RenderThreadSafe
);

int32 GNaniteMaxCandidatePatches = 2 * 1048576;
FAutoConsoleVariableRef CVarNaniteMaxCandidatePatches(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteShared.cpp:320

Scope (from outer to inner):

file
namespace    Nanite
function     uint32 FGlobalResources::GetMaxVisibleClusters

Source code excerpt:

uint32 FGlobalResources::GetMaxVisibleClusters()
{
	checkf(GNaniteMaxVisibleClusters <= MAX_CLUSTERS, TEXT("r.Nanite.MaxVisibleClusters must be <= MAX_CLUSTERS"));
	return GNaniteMaxVisibleClusters;
}

uint32 FGlobalResources::GetMaxNodes()
{
	return GNaniteMaxNodes & -NANITE_MAX_BVH_NODES_PER_GROUP;
}