r.Nanite.UseSceneInstanceHierarchy

r.Nanite.UseSceneInstanceHierarchy

#Overview

name: r.Nanite.UseSceneInstanceHierarchy

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

• type: Var
• help: Control Nanite use of the scene instance culling hierarchy. Has no effect unless r.SceneCulling is also enabled.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Nanite.UseSceneInstanceHierarchy is to control Nanite’s use of the scene instance culling hierarchy. This setting is part of the Nanite rendering system in Unreal Engine 5, which is responsible for efficient rendering of highly detailed meshes.

This setting variable is primarily used in the Nanite rendering subsystem, specifically in the culling and rasterization process. It’s defined in the NaniteCullRaster.cpp file, which suggests its involvement in the culling and rasterization stages of Nanite rendering.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning it’s enabled by default. Developers can change this value at runtime using console commands or through project settings.

This variable interacts closely with another setting, r.SceneCulling. As noted in the description, r.Nanite.UseSceneInstanceHierarchy has no effect unless r.SceneCulling is also enabled. This suggests that these two settings work together to optimize the scene culling process for Nanite-rendered objects.

Developers must be aware that this setting is render thread safe (ECVF_RenderThreadSafe), meaning it can be safely changed at runtime without causing rendering issues. However, they should also note that changing this setting alone may not have the desired effect if r.SceneCulling is not enabled.

Best practices when using this variable include:

1. Ensure r.SceneCulling is enabled if you want this setting to take effect.
2. Monitor performance when enabling or disabling this setting, as its impact may vary depending on the scene complexity.
3. Consider leaving it enabled (default value of 1) unless specific performance issues are observed.

Regarding the associated variable CVarNaniteCullInstanceHierarchy, it’s an internal representation of the r.Nanite.UseSceneInstanceHierarchy setting. This variable is used in the C++ code to actually implement the behavior controlled by the setting. It’s initialized with the same parameters as the console variable, ensuring they always have the same value.

The CVarNaniteCullInstanceHierarchy variable is used in the FRenderer::DrawGeometry function to initialize the InstanceHierarchyDriver. This suggests that the setting directly affects how Nanite handles instance culling during the geometry drawing process.

When working with CVarNaniteCullInstanceHierarchy, developers should be aware that it’s accessed on the render thread (GetValueOnRenderThread()), which is consistent with its thread-safe nature. Any code interacting with this variable should also be render thread safe to prevent potential race conditions or rendering artifacts.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:63

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarNaniteCullInstanceHierarchy(
	TEXT("r.Nanite.UseSceneInstanceHierarchy"),
	1,
	TEXT("Control Nanite use of the scene instance culling hierarchy. Has no effect unless  r.SceneCulling is also enabled."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarNaniteComputeRasterization(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:62

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarNaniteCullInstanceHierarchy(
	TEXT("r.Nanite.UseSceneInstanceHierarchy"),
	1,
	TEXT("Control Nanite use of the scene instance culling hierarchy. Has no effect unless  r.SceneCulling is also enabled."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:5111

Scope (from outer to inner):

file
namespace    Nanite
function     void FRenderer::DrawGeometry

Source code excerpt:

	}

	InstanceHierarchyDriver.Init(GraphBuilder, CVarNaniteCullInstanceHierarchy.GetValueOnRenderThread() != 0, Configuration.bTwoPassOcclusion, SharedContext.ShaderMap, SceneInstanceCullingQuery);

	{
		FNaniteStats Stats;
		FMemory::Memzero(Stats);
		// The main pass instances are produced on the GPU if the hierarchy is active.
		if (IsDebuggingEnabled() && !InstanceHierarchyDriver.bIsEnabled)