r.Nanite.VSMInvalidateOnLODDelta

r.Nanite.VSMInvalidateOnLODDelta

#Overview

name: r.Nanite.VSMInvalidateOnLODDelta

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Nanite.VSMInvalidateOnLODDelta is to control the invalidation of Virtual Shadow Maps (VSM) based on Level of Detail (LOD) changes in Nanite geometry. This setting is part of Unreal Engine’s Nanite rendering system, which is responsible for highly detailed and efficient geometry rendering.

The Nanite rendering system within Unreal Engine 5 relies on this setting variable. It is specifically used in the renderer module, as evidenced by its implementation in the NaniteCullRaster.cpp file.

The value of this variable is set through a console variable (CVarNaniteVSMInvalidateOnLODDelta) using the TAutoConsoleVariable template. It is initialized with a default value of 0, meaning the feature is disabled by default.

This variable interacts with the RenderFlags bitfield, specifically setting the NANITE_RENDER_FLAG_INVALIDATE_VSM_ON_LOD_DELTA flag when enabled.

Developers must be aware that this is an experimental feature, as indicated in the variable’s description. Enabling this feature may cause a significant increase in VSM invalidations, especially in scenarios where the streaming system is struggling to keep up with demand.

Best practices when using this variable include:

  1. Use it cautiously in production environments due to its experimental nature.
  2. Monitor performance closely when enabled, as it may impact rendering performance.
  3. Consider implementing additional logic to throttle invalidations or add thresholds if using this feature, as suggested in the variable’s description.

Regarding the associated variable CVarNaniteVSMInvalidateOnLODDelta:

The purpose of CVarNaniteVSMInvalidateOnLODDelta is to serve as the actual console variable that controls the r.Nanite.VSMInvalidateOnLODDelta setting. It is used to expose the setting to the engine’s console system, allowing runtime modification of the behavior.

This console variable is defined in the Nanite renderer subsystem and is used to determine whether to set the NANITE_RENDER_FLAG_INVALIDATE_VSM_ON_LOD_DELTA flag in the renderer’s RenderFlags.

The value of CVarNaniteVSMInvalidateOnLODDelta is set through the console system and can be modified at runtime.

When using this console variable, developers should be aware that changes will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag used in its declaration.

Best practices for using CVarNaniteVSMInvalidateOnLODDelta include:

  1. Use it for debugging and performance tuning purposes.
  2. Be cautious when enabling it in production builds due to its potential performance impact.
  3. Consider exposing it as a configurable option in development builds for easier testing and optimization.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarNaniteVSMInvalidateOnLODDelta(
	TEXT("r.Nanite.VSMInvalidateOnLODDelta"),
	0,
	TEXT("Experimental: Clusters that are not streamed in to LOD matching the computed Nanite LOD estimate will trigger VSM invalidation such that they are re-rendered when streaming completes.\n")
	TEXT("  NOTE: May cause a large increase in invalidations in cases where the streamer has difficulty keeping up (a future version will need to throttle the invalidations and/or add a threshold)."),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarNaniteVSMInvalidateOnLODDelta(
	TEXT("r.Nanite.VSMInvalidateOnLODDelta"),
	0,
	TEXT("Experimental: Clusters that are not streamed in to LOD matching the computed Nanite LOD estimate will trigger VSM invalidation such that they are re-rendered when streaming completes.\n")
	TEXT("  NOTE: May cause a large increase in invalidations in cases where the streamer has difficulty keeping up (a future version will need to throttle the invalidations and/or add a threshold)."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
namespace    Nanite
function     FRenderer::FRenderer

Source code excerpt:

	}

	if (CVarNaniteVSMInvalidateOnLODDelta.GetValueOnRenderThread() != 0)
	{
		RenderFlags |= NANITE_RENDER_FLAG_INVALIDATE_VSM_ON_LOD_DELTA;
	}

	// TODO: Exclude from shipping builds
	{