r.Water.SingleLayer.DepthPrepass

r.Water.SingleLayer.DepthPrepass

#Overview

name: r.Water.SingleLayer.DepthPrepass

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.Water.SingleLayer.DepthPrepass is to enable a depth prepass for single layer water rendering in Unreal Engine 5. This setting is specifically designed for the rendering system, particularly for water rendering and shadow mapping.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, as evident from the file locations where it’s referenced (SingleLayerWaterRendering.cpp and RenderUtils.cpp).

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning it’s enabled by default. The value can be changed at runtime through console commands or project settings.

This variable interacts closely with the Virtual Shadow Maps (VSM) system. In the IsSingleLayerWaterDepthPrepassEnabled function, we can see that the depth prepass is only enabled if both this setting is enabled and the platform supports Virtual Shadow Maps.

Developers should be aware that this setting is marked as ECVF_ReadOnly and ECVF_RenderThreadSafe. This means it’s intended to be set at startup and not changed during runtime, and it’s safe to read from the render thread.

Best practices when using this variable include:

  1. Ensure it’s enabled when using Virtual Shadow Maps with water rendering for proper support.
  2. Be cautious about disabling it, as it may affect the quality of water rendering and shadows.
  3. Consider performance implications, as enabling the depth prepass adds an extra rendering pass.

Regarding the associated variable CVarWaterSingleLayerDepthPrepass:

The purpose of CVarWaterSingleLayerDepthPrepass is to provide programmatic access to the r.Water.SingleLayer.DepthPrepass setting within the C++ code.

This variable is used in the Renderer module to check the current state of the depth prepass setting. It’s typically used in conditional statements to determine whether to perform certain rendering operations.

The value of CVarWaterSingleLayerDepthPrepass is set by the console variable system based on the r.Water.SingleLayer.DepthPrepass setting.

It interacts directly with the r.Water.SingleLayer.DepthPrepass setting, essentially serving as its in-code representation.

Developers should be aware that this variable is a TAutoConsoleVariable, meaning it’s automatically registered with the console variable system and can be accessed and modified through console commands.

Best practices for using CVarWaterSingleLayerDepthPrepass include:

  1. Use it for runtime checks of the depth prepass state.
  2. Remember that changes to this variable will directly affect the r.Water.SingleLayer.DepthPrepass setting.
  3. Consider caching its value if checking frequently, as console variable lookups can have some overhead.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SingleLayerWaterRendering.cpp:113

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarWaterSingleLayerDepthPrepass(
	TEXT("r.Water.SingleLayer.DepthPrepass"), 1,
	TEXT("Enable a depth prepass for single layer water. Necessary for proper Virtual Shadow Maps support."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSingleLayerWaterPassOptimizedClear(
	TEXT("r.Water.SingleLayer.OptimizedClear"), 1,
	TEXT("Toggles optimized depth clear"),

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1408

Scope (from outer to inner):

file
function     bool IsSingleLayerWaterDepthPrepassEnabled

Source code excerpt:

bool IsSingleLayerWaterDepthPrepassEnabled(const FStaticShaderPlatform Platform, const FStaticFeatureLevel FeatureLevel)
{
	static const auto CVarWaterSingleLayerDepthPrepass = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Water.SingleLayer.DepthPrepass"));
	const bool bPrepassEnabled = CVarWaterSingleLayerDepthPrepass && CVarWaterSingleLayerDepthPrepass->GetInt() > 0;
	// Currently VSM is the only feature dependent on the depth prepass which is why we only enable it if VSM could also be enabled.
	// VSM can be toggled at runtime, but we need a compile time value here, so we fall back to DoesPlatformSupportVirtualShadowMaps() to check if
	// VSM *could* be enabled.
	const bool bVSMSupported = DoesPlatformSupportVirtualShadowMaps(Platform);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1408

Scope (from outer to inner):

file
function     bool IsSingleLayerWaterDepthPrepassEnabled

Source code excerpt:

bool IsSingleLayerWaterDepthPrepassEnabled(const FStaticShaderPlatform Platform, const FStaticFeatureLevel FeatureLevel)
{
	static const auto CVarWaterSingleLayerDepthPrepass = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Water.SingleLayer.DepthPrepass"));
	const bool bPrepassEnabled = CVarWaterSingleLayerDepthPrepass && CVarWaterSingleLayerDepthPrepass->GetInt() > 0;
	// Currently VSM is the only feature dependent on the depth prepass which is why we only enable it if VSM could also be enabled.
	// VSM can be toggled at runtime, but we need a compile time value here, so we fall back to DoesPlatformSupportVirtualShadowMaps() to check if
	// VSM *could* be enabled.
	const bool bVSMSupported = DoesPlatformSupportVirtualShadowMaps(Platform);

	return bPrepassEnabled && bVSMSupported;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SingleLayerWaterRendering.cpp:112

Scope: file

Source code excerpt:

	TEXT("Wait for completion of parallel render thread tasks at the end of Single layer water. A more granular version of r.RHICmdFlushRenderThreadTasks. If either r.RHICmdFlushRenderThreadTasks or r.RHICmdFlushRenderThreadTasksSingleLayerWater is > 0 we will flush."));

static TAutoConsoleVariable<int32> CVarWaterSingleLayerDepthPrepass(
	TEXT("r.Water.SingleLayer.DepthPrepass"), 1,
	TEXT("Enable a depth prepass for single layer water. Necessary for proper Virtual Shadow Maps support."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSingleLayerWaterPassOptimizedClear(
	TEXT("r.Water.SingleLayer.OptimizedClear"), 1,