r.Water.SingleLayer.DistanceFieldShadow

r.Water.SingleLayer.DistanceFieldShadow

#Overview

name: r.Water.SingleLayer.DistanceFieldShadow

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.Water.SingleLayer.DistanceFieldShadow is to enable or disable distance field shadow tracing on single layer water when using deferred rendering in Unreal Engine 5.

This setting variable is primarily used by the rendering system, specifically for water rendering and shadow calculations. It is part of the SingleLayerWater rendering module within the Unreal Engine.

The value of this variable is set through a console variable (CVar) in the engine’s configuration. It can be toggled on or off at runtime, with a default value of 1 (enabled).

The associated variable CVarWaterSingleLayerDistanceFieldShadow directly interacts with r.Water.SingleLayer.DistanceFieldShadow. They share the same value and purpose.

Developers must be aware that this variable only affects single layer water rendering when using deferred rendering. It won’t have any effect on forward rendering or other water rendering techniques.

Best practices when using this variable include:

  1. Consider performance implications when enabling distance field shadow tracing on water.
  2. Test the visual quality and performance with this setting both enabled and disabled to determine the best option for your project.
  3. Be aware that this setting can be changed at runtime, which allows for dynamic adjustments based on performance needs or visual requirements.

Regarding the associated variable CVarWaterSingleLayerDistanceFieldShadow:

The purpose of CVarWaterSingleLayerDistanceFieldShadow is identical to r.Water.SingleLayer.DistanceFieldShadow. It’s an internal representation of the console variable used within the engine’s C++ code.

This variable is used in the SingleLayerWaterRendering module of the Unreal Engine renderer. It’s specifically used in the IsWaterDistanceFieldShadowEnabled_Runtime function to determine if distance field shadow tracing should be applied to single layer water at runtime.

The value of this variable is set through the console variable system and can be accessed using the GetValueOnAnyThread() method.

CVarWaterSingleLayerDistanceFieldShadow directly interacts with r.Water.SingleLayer.DistanceFieldShadow, as they represent the same setting.

Developers should be aware that this variable is checked on the render thread, which means changes to its value will be reflected in the next frame render.

Best practices for using this variable include:

  1. Use the IsWaterDistanceFieldShadowEnabled_Runtime function when you need to check if this feature is enabled, rather than accessing the CVar directly.
  2. Be cautious when changing this value frequently, as it may impact performance due to shader recompilation.
  3. Consider exposing this setting in your game’s graphics options menu to allow users to adjust it based on their hardware capabilities.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarWaterSingleLayerDistanceFieldShadow(
	TEXT("r.Water.SingleLayer.DistanceFieldShadow"), 1,
	TEXT("When using deferred, distance field shadow tracing is supported on single layer water. This cvar can be used to toggle it on/off at runtime."),
	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarSupportCloudShadowOnSingleLayerWater(
	TEXT("r.Water.SingleLayerWater.SupportCloudShadow"), 0,
	TEXT("Enables cloud shadows on SingleLayerWater materials."),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarWaterSingleLayerDistanceFieldShadow(
	TEXT("r.Water.SingleLayer.DistanceFieldShadow"), 1,
	TEXT("When using deferred, distance field shadow tracing is supported on single layer water. This cvar can be used to toggle it on/off at runtime."),
	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarSupportCloudShadowOnSingleLayerWater(
	TEXT("r.Water.SingleLayerWater.SupportCloudShadow"), 0,

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

Scope (from outer to inner):

file
function     bool IsWaterDistanceFieldShadowEnabled_Runtime

Source code excerpt:

bool IsWaterDistanceFieldShadowEnabled_Runtime(const FStaticShaderPlatform Platform)
{
	return IsWaterDistanceFieldShadowEnabled(Platform) && CVarWaterSingleLayerDistanceFieldShadow.GetValueOnAnyThread() > 0;
}

bool IsWaterVirtualShadowMapFilteringEnabled_Runtime(const FStaticShaderPlatform Platform)
{
	return IsWaterVirtualShadowMapFilteringEnabled(Platform) && UseVirtualShadowMaps(Platform, GetMaxSupportedFeatureLevel(Platform)) && CVarWaterSingleLayerVSMFiltering.GetValueOnRenderThread() > 0;
}