r.Nanite.ProxyRenderMode

r.Nanite.ProxyRenderMode

#Overview

name: r.Nanite.ProxyRenderMode

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

• type: Var
• help: Render proxy meshes if Nanite is unsupported.\n 0: Fall back to rendering Nanite proxy meshes if Nanite is unsupported. (default)\n 1: Disable rendering if Nanite is enabled on a mesh but is unsupported.\n 2: Disable rendering if Nanite is enabled on a mesh but is unsupported, except for static mesh editor toggle.

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Nanite.ProxyRenderMode is to control the rendering behavior of Nanite proxy meshes when Nanite is unsupported or disabled. This setting variable is primarily used in the rendering system of Unreal Engine 5, specifically for handling Nanite-enabled meshes in scenarios where Nanite cannot be used.

This setting variable is utilized by various Unreal Engine subsystems and modules, including:

1. The StaticMesh rendering system
2. The HierarchicalInstancedStaticMesh component
3. The GeometryCollection component
4. The SceneRendering system

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

The variable interacts with GNaniteProxyRenderMode, which is the actual integer value that stores the setting. They share the same value, with r.Nanite.ProxyRenderMode being the console variable name and GNaniteProxyRenderMode being the C++ variable used in the code.

Developers must be aware of the following when using this variable:

1. It has three possible values (0, 1, 2), each with different behavior:

   • 0: Fall back to rendering Nanite proxy meshes if Nanite is unsupported (default)
   • 1: Disable rendering if Nanite is enabled on a mesh but is unsupported
   • 2: Same as 1, except for the static mesh editor toggle

2. Changing this value can affect the visibility and rendering of Nanite-enabled meshes when Nanite is not supported or disabled.

3. It can impact performance and visual fidelity, especially in scenarios where Nanite is not available.

Best practices when using this variable include:

1. Use the default value (0) for most production scenarios to ensure fallback rendering.
2. Consider using value 1 or 2 for debugging or specific use cases where you want to clearly identify Nanite-incompatible meshes.
3. Test thoroughly with different values to ensure desired behavior across various hardware configurations.

Regarding the associated variable GNaniteProxyRenderMode:

The purpose of GNaniteProxyRenderMode is to store the actual integer value of the Nanite proxy render mode setting. It is used internally in the C++ code to control the rendering behavior of Nanite-enabled meshes when Nanite is unsupported.

This variable is primarily used in the StaticMesh rendering system and is directly accessed in the code to determine the rendering behavior.

The value of GNaniteProxyRenderMode is set through the console variable system, specifically by the r.Nanite.ProxyRenderMode console variable.

GNaniteProxyRenderMode interacts directly with the r.Nanite.ProxyRenderMode console variable, sharing the same value and purpose.

Developers should be aware that GNaniteProxyRenderMode is the actual variable used in the C++ code, while r.Nanite.ProxyRenderMode is the console variable name used for setting and accessing the value externally.

Best practices for using GNaniteProxyRenderMode include:

1. Avoid modifying this variable directly in C++ code; instead, use the console variable system to change its value.
2. When reading the value in C++ code, consider caching it for performance reasons if it’s accessed frequently.
3. Be aware of the potential impact on rendering when changing this value, especially in performance-critical sections of code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:120

Scope: file

Source code excerpt:

int32 GNaniteProxyRenderMode = 0;
FAutoConsoleVariableRef CVarNaniteProxyRenderMode(
	TEXT("r.Nanite.ProxyRenderMode"),
	GNaniteProxyRenderMode,
	TEXT("Render proxy meshes if Nanite is unsupported.\n")
	TEXT(" 0: Fall back to rendering Nanite proxy meshes if Nanite is unsupported. (default)\n")
	TEXT(" 1: Disable rendering if Nanite is enabled on a mesh but is unsupported.\n")
	TEXT(" 2: Disable rendering if Nanite is enabled on a mesh but is unsupported, except for static mesh editor toggle."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HierarchicalInstancedStaticMesh.cpp:2958

Scope: file

Source code excerpt:

FPrimitiveSceneProxy* UHierarchicalInstancedStaticMeshComponent::CreateSceneProxy()
{
	static const auto NaniteProxyRenderModeVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Nanite.ProxyRenderMode"));
	const int32 NaniteProxyRenderMode = (NaniteProxyRenderModeVar != nullptr) ? (NaniteProxyRenderModeVar->GetInt() != 0) : 0;

	QUICK_SCOPE_CYCLE_COUNTER(STAT_HierarchicalInstancedStaticMeshComponent_CreateSceneProxy);
	SCOPE_CYCLE_COUNTER(STAT_FoliageCreateProxy);

	PrimitiveInstanceDataManager.ResetComponentDirtyTracking();

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionComponent.cpp:1101

Scope (from outer to inner):

file
function     FPrimitiveSceneProxy* UGeometryCollectionComponent::CreateSceneProxy

Source code excerpt:

FPrimitiveSceneProxy* UGeometryCollectionComponent::CreateSceneProxy()
{
	static const auto NaniteProxyRenderModeVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Nanite.ProxyRenderMode"));
	const int32 NaniteProxyRenderMode = (NaniteProxyRenderModeVar != nullptr) ? (NaniteProxyRenderModeVar->GetInt() != 0) : 0;

	FPrimitiveSceneProxy* LocalSceneProxy = nullptr;

	const bool bNotUsingRootProxyComponents = RootProxyStaticMeshComponents.IsEmpty();
	if (RestCollection && !CanUseCustomRenderer() && bNotUsingRootProxyComponents)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:3760

Scope (from outer to inner):

file
function     void FSceneRenderer::OnRenderFinish

Source code excerpt:

		// 2: show error if Nanite is present in the scene but unsupported, even if fallback meshes are used for rendering

		static const auto NaniteProxyRenderModeVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Nanite.ProxyRenderMode"));
		const int32 NaniteProxyRenderMode = (NaniteProxyRenderModeVar != nullptr) ? (NaniteProxyRenderModeVar->GetInt() != 0) : 0;
		// 0: Fall back to rendering Nanite proxy meshes if Nanite is unsupported.
		// 1: Disable rendering if Nanite is enabled on a mesh but is unsupported
		// 2: Disable rendering if Nanite is enabled on a mesh but is unsupported, except for static mesh editor toggle

		bool bNaniteEnabledButNoAtomics = false;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:118

Scope: file

Source code excerpt:

);

int32 GNaniteProxyRenderMode = 0;
FAutoConsoleVariableRef CVarNaniteProxyRenderMode(
	TEXT("r.Nanite.ProxyRenderMode"),
	GNaniteProxyRenderMode,
	TEXT("Render proxy meshes if Nanite is unsupported.\n")
	TEXT(" 0: Fall back to rendering Nanite proxy meshes if Nanite is unsupported. (default)\n")
	TEXT(" 1: Disable rendering if Nanite is enabled on a mesh but is unsupported.\n")
	TEXT(" 2: Disable rendering if Nanite is enabled on a mesh but is unsupported, except for static mesh editor toggle."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:2729

Scope (from outer to inner):

file
function     FPrimitiveSceneProxy* UStaticMeshComponent::CreateSceneProxy

Source code excerpt:

	else if (HasValidNaniteData() && NaniteMaterials.IsValid(bIsMaskingAllowed))
	{
		const bool bAllowProxyRender = GNaniteProxyRenderMode == 0
	#if WITH_EDITORONLY_DATA
			// Check for specific case of static mesh editor "proxy toggle"
			|| (bDisplayNaniteFallbackMesh && GNaniteProxyRenderMode == 2)
	#endif
		;

		if (!bAllowProxyRender) // Never render proxies
		{
			// We don't want to fall back to Nanite proxy rendering, so just make the mesh invisible instead.