r.GeometryCollection.Nanite

r.GeometryCollection.Nanite

#Overview

name: r.GeometryCollection.Nanite

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GeometryCollection.Nanite is to control the rendering of geometry collections using Nanite, Unreal Engine’s virtualized geometry system. This setting variable is used to enable or disable Nanite rendering for geometry collections.

The Unreal Engine subsystem that relies on this setting variable is the Experimental GeometryCollectionEngine module, specifically within the rendering and scene proxy creation for geometry collections.

The value of this variable is set through the console variable system. It’s initialized with a default value of 1 (enabled) and can be changed at runtime.

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

Developers must be aware that changing this variable will trigger a recreation of render states for affected components. This is evident from the FGlobalComponentRecreateRenderStateContext being created when the console variable changes.

Best practices when using this variable include:

  1. Be cautious when changing it at runtime, as it will impact performance due to render state recreation.
  2. Consider the hardware capabilities of target platforms, as Nanite has specific requirements.
  3. Test thoroughly with both enabled and disabled states to ensure your geometry collections render correctly in all scenarios.

Regarding the associated variable GGeometryCollectionNanite:

The purpose of GGeometryCollectionNanite is to provide a C++ accessible integer that reflects the state of the r.GeometryCollection.Nanite console variable.

It’s used within the GeometryCollectionComponent to determine whether to create a Nanite-based scene proxy or a traditional one. This decision is made in the CreateSceneProxy() function and is also checked in the UpdateRenderSystemsIfNeeded() function to determine if the proxy needs to be recreated.

The value of GGeometryCollectionNanite is set automatically when r.GeometryCollection.Nanite changes, thanks to the console variable system.

Developers should be aware that this variable is checked in performance-critical areas like scene proxy creation and updates. Therefore, frequent changes to this value could impact performance.

Best practices for GGeometryCollectionNanite include:

  1. Treat it as read-only in most cases, modifying it through the console variable instead.
  2. Be aware of its impact on render proxy creation and updates when optimizing performance.
  3. Consider it in conjunction with other Nanite-related settings and the EnableNanite property of the RestCollection when debugging rendering issues with geometry collections.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GGeometryCollectionNanite = 1;
FAutoConsoleVariableRef CVarGeometryCollectionNanite(
	TEXT("r.GeometryCollection.Nanite"),
	GGeometryCollectionNanite,
	TEXT("Render geometry collections using Nanite."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

}

int32 GGeometryCollectionNanite = 1;
FAutoConsoleVariableRef CVarGeometryCollectionNanite(
	TEXT("r.GeometryCollection.Nanite"),
	GGeometryCollectionNanite,
	TEXT("Render geometry collections using Nanite."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_RenderThreadSafe

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

Scope (from outer to inner):

file
function     FPrimitiveSceneProxy* UGeometryCollectionComponent::CreateSceneProxy

Source code excerpt:

			RestCollection->EnableNanite &&
			RestCollection->HasNaniteData() &&
			GGeometryCollectionNanite != 0)
		{
			FNaniteGeometryCollectionSceneProxy* NaniteProxy = new FNaniteGeometryCollectionSceneProxy(this);
			LocalSceneProxy = NaniteProxy;

			// ForceMotionBlur means we maintain bIsMoving, regardless of actual state.
			if (bForceMotionBlur)

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

Scope (from outer to inner):

file
function     void UGeometryCollectionComponent::UpdateRenderSystemsIfNeeded

Source code excerpt:

	if (IsRegistered() && SceneProxy && RestCollection)
	{
		const bool bWantNanite = RestCollection->EnableNanite && GGeometryCollectionNanite != 0;
		const bool bHaveNanite = SceneProxy->IsNaniteMesh();
		bool bRecreateProxy = bWantNanite != bHaveNanite;
		if (bRecreateProxy)
		{
			// Wait until resources are released
			FlushRenderingCommands();

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

Scope (from outer to inner):

file
function     void UGeometryCollectionComponent::CollectPSOPrecacheData

Source code excerpt:

		RestCollection->EnableNanite &&
		RestCollection->HasNaniteData() &&
		GGeometryCollectionNanite != 0)
	{
		if (NaniteLegacyMaterialsSupported())
		{
			VFDataList.Add(FPSOPrecacheVertexFactoryData(&Nanite::FVertexFactory::StaticType));
		}