r.Shadow.Virtual.Nanite.MaterialVisibility

r.Shadow.Virtual.Nanite.MaterialVisibility

#Overview

name: r.Shadow.Virtual.Nanite.MaterialVisibility

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

• type: Var
• help: Enable Nanite CPU-side visibility filtering of draw commands, depends on r.Nanite.MaterialVisibility being enabled.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.Nanite.MaterialVisibility is to enable CPU-side visibility filtering of draw commands for Nanite in the context of virtual shadows. This setting is part of the rendering system, specifically related to shadow rendering and Nanite technology in Unreal Engine 5.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the shadow rendering subsystem. Based on the callsites, it’s referenced in the ShadowSceneRenderer.cpp file, which is responsible for rendering shadows in the scene.

The value of this variable is set through a console variable (CVarVSMMaterialVisibility) with a default value of 0, meaning it’s disabled by default. It can be changed at runtime using console commands or through project settings.

This variable interacts with another setting, r.Nanite.MaterialVisibility. The description states that r.Shadow.Virtual.Nanite.MaterialVisibility depends on r.Nanite.MaterialVisibility being enabled.

Developers must be aware that:

1. This setting is render thread safe, meaning it can be changed safely during runtime without causing threading issues.
2. It’s specifically for Nanite-based rendering and may not affect traditional rendering methods.
3. Enabling this feature may have performance implications, as it introduces CPU-side filtering.

Best practices when using this variable include:

1. Only enable it when using Nanite and virtual shadow maps together.
2. Test the performance impact in your specific use case, as CPU-side filtering can be expensive.
3. Ensure that r.Nanite.MaterialVisibility is also enabled for this feature to work correctly.

Regarding the associated variable CVarVSMMaterialVisibility:

• It’s the actual console variable that controls the r.Shadow.Virtual.Nanite.MaterialVisibility setting.
• It’s used in the FShadowSceneRenderer::PostInitDynamicShadowsSetup function to determine whether to dispatch an async Nanite culling job.
• When using this variable, developers should access its value using GetValueOnRenderThread() to ensure thread-safe access in render code.
• The variable is defined with ECVF_RenderThreadSafe flag, which allows it to be changed safely at runtime.

Developers should be cautious when modifying this setting, as it can affect the performance and visual quality of shadow rendering in Nanite-based scenes. It’s recommended to profile the application with and without this setting enabled to determine the optimal configuration for your specific use case.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:18

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarVSMMaterialVisibility(
	TEXT("r.Shadow.Virtual.Nanite.MaterialVisibility"),
	0,
	TEXT("Enable Nanite CPU-side visibility filtering of draw commands, depends on r.Nanite.MaterialVisibility being enabled."),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarMaxDistantLightsPerFrame(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:17

Scope: file

Source code excerpt:

extern int32 GForceInvalidateDirectionalVSM;

TAutoConsoleVariable<int32> CVarVSMMaterialVisibility(
	TEXT("r.Shadow.Virtual.Nanite.MaterialVisibility"),
	0,
	TEXT("Enable Nanite CPU-side visibility filtering of draw commands, depends on r.Nanite.MaterialVisibility being enabled."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:285

Scope (from outer to inner):

file
function     void FShadowSceneRenderer::PostInitDynamicShadowsSetup

Source code excerpt:

{
	// Dispatch async Nanite culling job if appropriate
	if (CVarVSMMaterialVisibility.GetValueOnRenderThread() != 0)
	{
		TArray<FConvexVolume, SceneRenderingAllocator> NaniteCullingViewsVolumes;
		// If we have a clipmap that can't be culled, it'd be a complete waste of time to cull the local lights.
		bool bUnboundedClipmap = false;
		
		for (const FDirectionalLightShadowFrameSetup& DirectionalLightShadowFrameSetup : DirectionalLights)