r.Nanite.MaxCandidateClusters

r.Nanite.MaxCandidateClusters

#Overview

name: r.Nanite.MaxCandidateClusters

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.MaxCandidateClusters is to set the maximum number of Nanite clusters before cluster culling occurs in the Unreal Engine 5 rendering system. This setting is crucial for controlling the performance and visual quality of Nanite-based geometry rendering.

The Unreal Engine subsystem that relies on this setting variable is the Nanite rendering system, which is part of the core rendering module. Specifically, it’s used in the cluster culling process, which is an essential optimization technique for Nanite’s geometry processing.

The value of this variable is set through the console variable system, as indicated by the FAutoConsoleVariableRef declaration. It can be modified at runtime using console commands or through configuration files.

The associated variable GNaniteMaxCandidateClusters interacts directly with r.Nanite.MaxCandidateClusters. They share the same value, with GNaniteMaxCandidateClusters being the actual integer variable used in the C++ code, while r.Nanite.MaxCandidateClusters is the console variable name used for external access and configuration.

Developers must be aware of several things when using this variable:

  1. The value directly impacts rendering performance and visual quality.
  2. Setting it too low may cause visual artifacts, as indicated by the warning message in NaniteFeedback.cpp.
  3. The value is rounded down to the nearest multiple of NANITE_PERSISTENT_CLUSTER_CULLING_GROUP_SIZE for internal use.

Best practices when using this variable include:

  1. Monitor the high-water mark of candidate clusters to determine if the current value is sufficient.
  2. Increase the value if warnings about candidate cluster buffer overflow are frequent.
  3. Balance the value with available memory and performance requirements.
  4. Consider the relationship with other Nanite settings, such as GNaniteMaxVisibleClusters.

Regarding the associated variable GNaniteMaxCandidateClusters:

The purpose of GNaniteMaxCandidateClusters is to serve as the internal C++ representation of the r.Nanite.MaxCandidateClusters setting. It’s used directly in the Nanite rendering code to control the maximum number of candidate clusters.

This variable is used in the Nanite rendering subsystem, specifically in the cluster culling and processing stages.

The value of GNaniteMaxCandidateClusters is set by the console variable system when r.Nanite.MaxCandidateClusters is modified.

GNaniteMaxCandidateClusters interacts with the console variable system and is used in calculations to determine the actual maximum number of candidate clusters.

Developers should be aware that modifying GNaniteMaxCandidateClusters directly in code is not recommended, as it may be overwritten by the console variable system.

Best practices for GNaniteMaxCandidateClusters include:

  1. Use the console variable r.Nanite.MaxCandidateClusters to modify its value instead of changing it directly in code.
  2. Consider the impact on memory usage when adjusting this value, as it directly affects the size of cluster-related buffers.
  3. Use the GetMaxCandidateClusters() function in the Nanite namespace to retrieve the properly aligned value when needed in code.

#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:39

Scope: file

Source code excerpt:

int32 GNaniteMaxCandidateClusters = 16 * 1048576;
FAutoConsoleVariableRef CVarNaniteMaxCandidateClusters(
	TEXT("r.Nanite.MaxCandidateClusters"),
	GNaniteMaxCandidateClusters,
	TEXT("Maximum number of Nanite clusters before cluster culling."),
	ECVF_RenderThreadSafe
);

int32 GNaniteMaxVisibleClusters = 4 * 1048576;

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

Scope (from outer to inner):

file
function     FFeedbackManager::FFeedbackManager
lambda-function

Source code excerpt:

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

		if (CurrentTime - VisibleClusterState.LatestOverflowTime < ShowWarningSeconds)
		{
			OutMessages.Add(FCoreDelegates::EOnScreenMessageSeverity::Warning,

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GNaniteMaxCandidateClusters = 16 * 1048576;
FAutoConsoleVariableRef CVarNaniteMaxCandidateClusters(
	TEXT("r.Nanite.MaxCandidateClusters"),
	GNaniteMaxCandidateClusters,
	TEXT("Maximum number of Nanite clusters before cluster culling."),
	ECVF_RenderThreadSafe
);

int32 GNaniteMaxVisibleClusters = 4 * 1048576;
FAutoConsoleVariableRef CVarNaniteMaxVisibleClusters(

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

Scope (from outer to inner):

file
namespace    Nanite
function     uint32 FGlobalResources::GetMaxCandidateClusters

Source code excerpt:

{
	// NOTE: Candidate clusters can currently be allowed to exceed MAX_CLUSTERS
	const uint32 MaxCandidateClusters = GNaniteMaxCandidateClusters & -NANITE_PERSISTENT_CLUSTER_CULLING_GROUP_SIZE;
	return MaxCandidateClusters;
}

uint32 FGlobalResources::GetMaxClusterBatches()
{
	const uint32 MaxCandidateClusters = GetMaxCandidateClusters();