r.Shadow.NaniteUseHZB

r.Shadow.NaniteUseHZB

#Overview

name: r.Shadow.NaniteUseHZB

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

• type: Var
• help: Enables HZB for Nanite shadows.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.NaniteUseHZB is to enable or disable the use of Hierarchical Z-Buffer (HZB) for Nanite shadows in Unreal Engine 5’s rendering system. This setting is specifically related to the shadow rendering pipeline for Nanite geometry.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically in the shadow depth rendering subsystem. Based on the callsites, it’s clear that this variable is used in the process of rendering shadow depth maps for Nanite objects.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning HZB for Nanite shadows is enabled by default. Users can change this value at runtime using console commands.

The associated variable CVarNaniteShadowsUseHZB directly interacts with r.Shadow.NaniteUseHZB. They share the same value and purpose.

Developers must be aware that this variable affects the performance and quality of Nanite shadow rendering. Enabling HZB can potentially improve performance by reducing the amount of shadow computations, but it might have some impact on shadow quality in certain scenarios.

Best practices when using this variable include:

1. Test the performance and visual impact with HZB enabled and disabled for your specific use case.
2. Consider exposing this setting to end-users if shadow quality vs. performance is a critical aspect of your game.
3. Be cautious when changing this value during runtime, as it may cause noticeable changes in shadow appearance.

Regarding the associated variable CVarNaniteShadowsUseHZB:

The purpose of CVarNaniteShadowsUseHZB is identical to r.Shadow.NaniteUseHZB. It’s an internal representation of the console variable used in the C++ code.

This variable is used in the Renderer module, specifically in the shadow depth rendering system for Nanite geometry.

The value is set through the CVar system and can be accessed using GetValueOnRenderThread() method.

CVarNaniteShadowsUseHZB directly interacts with r.Shadow.NaniteUseHZB, as they represent the same setting.

Developers should be aware that this is the actual variable used in the code to check whether HZB should be used for Nanite shadows.

Best practices include using this variable consistently throughout the codebase when checking for HZB usage in Nanite shadows, and ensuring thread-safety when accessing its value (which is handled by the GetValueOnRenderThread() method).

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowDepthRendering.cpp:127

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarNaniteShadowsUseHZB(
	TEXT("r.Shadow.NaniteUseHZB"),
	1,
	TEXT("Enables HZB for Nanite shadows."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarNaniteShadowsUpdateStreaming(
	TEXT("r.Shadow.NaniteUpdateStreaming"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowDepthRendering.cpp:126

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarNaniteShadowsUseHZB(
	TEXT("r.Shadow.NaniteUseHZB"),
	1,
	TEXT("Enables HZB for Nanite shadows."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarNaniteShadowsUpdateStreaming(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowDepthRendering.cpp:1397

Scope (from outer to inner):

file
function     static void RenderShadowDepthAtlasNanite

Source code excerpt:

	const FIntPoint AtlasSize = ShadowMapAtlas.RenderTargets.DepthTarget->GetDesc().Extent;

	const bool bUseHZB = (CVarNaniteShadowsUseHZB.GetValueOnRenderThread() != 0);
	TArray<TRefCountPtr<IPooledRenderTarget>>&	PrevAtlasHZBs = Scene.PrevAtlasHZBs;

	auto& StaticShadowsToEmit = *GraphBuilder.AllocObject<TArray<FProjectedShadowInfo*, SceneRenderingAllocator>>();
	auto& MovableShadowsToEmit = *GraphBuilder.AllocObject<TArray<FProjectedShadowInfo*, SceneRenderingAllocator>>();
	auto& OtherShadowsToEmit = *GraphBuilder.AllocObject<TArray<FProjectedShadowInfo*, SceneRenderingAllocator>>();

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowDepthRendering.cpp:1770

Scope (from outer to inner):

file
function     void FSceneRenderer::RenderShadowDepthMaps

Source code excerpt:

		if (bNaniteEnabled && CVarNaniteShadows.GetValueOnRenderThread())
		{
			const bool bUseHZB = (CVarNaniteShadowsUseHZB.GetValueOnRenderThread() != 0);

			FString LightName;
			GetLightNameForDrawEvent(ProjectedShadowInfo->GetLightSceneInfo().Proxy, LightName);

			{
				RDG_EVENT_SCOPE( GraphBuilder, "Nanite Cubemap %s %ux%u", *LightName, ProjectedShadowInfo->ResolutionX, ProjectedShadowInfo->ResolutionY );