r.Nanite.StatsFilter

r.Nanite.StatsFilter

#Overview

name: r.Nanite.StatsFilter

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.StatsFilter is to set the name of a specific Nanite raster pass from which to capture statistics. This setting variable is primarily used for debugging and performance analysis of the Nanite rendering system in Unreal Engine 5.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, specifically the Nanite rendering system. This can be seen from the file location where the variable is defined and used: ‘Engine/Source/Runtime/Renderer/Private/Nanite/Nanite.cpp’.

The value of this variable is set through the console command system. It’s defined as an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands.

The associated variable that interacts with r.Nanite.StatsFilter is GNaniteStatsFilter. They share the same value, with GNaniteStatsFilter being the actual string that stores the filter name, while r.Nanite.StatsFilter is the console variable that allows for modifying this value.

Developers must be aware that this variable is intended for debugging and performance analysis purposes. It should be used when trying to isolate performance issues or gather statistics about specific Nanite raster passes. The variable is marked as ECVF_RenderThreadSafe, which means it’s safe to modify from the render thread.

Best practices when using this variable include:

  1. Use it in conjunction with the ‘NaniteStats List’ command to see available filters.
  2. Set it to an empty string to show stats for the primary view.
  3. Be aware that enabling stats gathering may have a performance impact, so it should be used judiciously in production environments.

Regarding the associated variable GNaniteStatsFilter:

The purpose of GNaniteStatsFilter is to store the actual string value of the Nanite raster pass name for which stats are being gathered.

It’s used within the Nanite rendering system to determine which pass should have its stats captured. This can be seen in the IsStatFilterActive function, which checks if GNaniteStatsFilter matches a given FilterName.

The value of GNaniteStatsFilter is set either through the r.Nanite.StatsFilter console variable or programmatically in the NaniteStatsFilterExec function.

GNaniteStatsFilter interacts directly with the r.Nanite.StatsFilter console variable, as well as other parts of the Nanite rendering system that need to check which pass is currently being monitored.

Developers should be aware that modifying GNaniteStatsFilter directly (rather than through the console variable) could lead to inconsistencies in the stats gathering system.

Best practices for GNaniteStatsFilter include accessing it through the proper channels (i.e., the console variable system) rather than modifying it directly, and ensuring it’s only used for its intended purpose of filtering Nanite rendering stats.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

FString GNaniteStatsFilter;
FAutoConsoleVariableRef CVarNaniteStatsFilter(
	TEXT("r.Nanite.StatsFilter"),
	GNaniteStatsFilter,
	TEXT("Sets the name of a specific Nanite raster pass to capture stats from - enumerate available filters with `NaniteStats List` cmd."),
	ECVF_RenderThreadSafe
);

extern TAutoConsoleVariable<int32> CVarNaniteShadows;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

FString GNaniteStatsFilter;
FAutoConsoleVariableRef CVarNaniteStatsFilter(
	TEXT("r.Nanite.StatsFilter"),
	GNaniteStatsFilter,
	TEXT("Sets the name of a specific Nanite raster pass to capture stats from - enumerate available filters with `NaniteStats List` cmd."),
	ECVF_RenderThreadSafe
);

extern TAutoConsoleVariable<int32> CVarNaniteShadows;

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

Scope (from outer to inner):

file
function     void NaniteStatsFilterExec

Source code excerpt:

		else
		{
			GNaniteStatsFilter = Parameter;
		}

		++ParameterCount;
	}

	if (!ParameterCount)
	{
		// Default to showing stats for the primary view
		GNaniteStatsFilter.Empty();
	}
}

class FEmitShadowMapPS : public FNaniteGlobalShader
{
	DECLARE_GLOBAL_SHADER(FEmitShadowMapPS);

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

Scope (from outer to inner):

file
namespace    Nanite
function     bool IsStatFilterActive

Source code excerpt:

	}

	return (GNaniteStatsFilter == FilterName);
}

bool IsStatFilterActiveForLight(const FLightSceneProxy* LightProxy)
{
	if (GNaniteShowStats == 0)
	{