r.Shadow.Virtual.NonNanite.UseHZB

r.Shadow.Virtual.NonNanite.UseHZB

#Overview

name: r.Shadow.Virtual.NonNanite.UseHZB

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

• type: Var
• help: Cull Non-Nanite instances using HZB.\n Set to 0 to disable.\n Set to 1 to use HZB from previous frame. Can incorrectly cull in some cases due to outdated data.\n Set to 2 to use two-pass Nanite culling with HZB from the current frame.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.NonNanite.UseHZB is to control the culling method for Non-Nanite instances in virtual shadow maps using Hierarchical Z-Buffer (HZB) techniques. This setting is part of the rendering system, specifically focusing on shadow rendering optimization.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the Virtual Shadow Maps subsystem. It’s referenced in the VirtualShadowMapArray.cpp file, which suggests it’s crucial for managing virtual shadow map rendering for non-Nanite objects.

The value of this variable is set through a console variable (CVarNonNaniteVsmUseHzb) with a default value of 2. It can be changed at runtime through console commands or programmatically.

The associated variable CVarNonNaniteVsmUseHzb interacts directly with r.Shadow.Virtual.NonNanite.UseHZB. They share the same value and purpose.

Developers must be aware of the following when using this variable:

1. It has three possible values (0, 1, 2), each with different implications for culling accuracy and performance.
2. Using value 1 (HZB from the previous frame) can lead to incorrect culling in some cases due to outdated data.
3. The HZB culling is automatically disabled if the HZB data hasn’t been built in the current frame.

Best practices when using this variable include:

1. Use the default value (2) for optimal balance between performance and accuracy.
2. If experiencing culling artifacts, try setting it to 0 to disable HZB culling.
3. Monitor performance and visual quality when changing this setting, as it can significantly impact both.

Regarding the associated variable CVarNonNaniteVsmUseHzb:

• It’s a TAutoConsoleVariable that directly controls the r.Shadow.Virtual.NonNanite.UseHZB setting.
• It’s used in the RenderVirtualShadowMapsNonNanite function to determine the HZB mode for culling.
• The value is retrieved on the render thread, indicating its performance-critical nature.
• Developers should use this variable when they need programmatic control over the HZB culling mode in C++ code.

When working with CVarNonNaniteVsmUseHzb, developers should ensure thread safety and consider the impact on rendering performance and shadow quality. It’s crucial to test different values in various scenarios to find the optimal setting for specific use cases.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:186

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarNonNaniteVsmUseHzb(
	TEXT("r.Shadow.Virtual.NonNanite.UseHZB"),
	2,
	TEXT("Cull Non-Nanite instances using HZB.\n")
	TEXT("  Set to 0 to disable.\n")
	TEXT("  Set to 1 to use HZB from previous frame. Can incorrectly cull in some cases due to outdated data.\n")
	TEXT("  Set to 2 to use two-pass Nanite culling with HZB from the current frame."),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:185

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarNonNaniteVsmUseHzb(
	TEXT("r.Shadow.Virtual.NonNanite.UseHZB"),
	2,
	TEXT("Cull Non-Nanite instances using HZB.\n")
	TEXT("  Set to 0 to disable.\n")
	TEXT("  Set to 1 to use HZB from previous frame. Can incorrectly cull in some cases due to outdated data.\n")
	TEXT("  Set to 2 to use two-pass Nanite culling with HZB from the current frame."),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:2694

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::RenderVirtualShadowMapsNonNanite

Source code excerpt:

	FGPUScene& GPUScene = Scene.GPUScene;
		
	int32 HZBMode = CVarNonNaniteVsmUseHzb.GetValueOnRenderThread();
	// When disabling Nanite, there may be stale data in the Nanite-HZB causing incorrect culling.
	if (!bHZBBuiltThisFrame)
	{
		HZBMode = 0; /* Disable HZB culling */
	}
	FRDGTextureRef HZBTexture = (HZBMode > 0 && CacheManager->IsHZBDataAvailable()) ? HZBPhysicalRDG : nullptr;