r.Water.FallbackDepth

r.Water.FallbackDepth

#Overview

name: r.Water.FallbackDepth

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.FallbackDepth is to provide a default depth value for water rendering when there are no ground actors defined in the scene. This setting is part of Unreal Engine 5’s water rendering system.

This setting variable is primarily used in the Experimental Water plugin, which is part of Unreal Engine’s runtime module. Specifically, it’s utilized in the WaterZoneActor.cpp file, which suggests it’s closely tied to the functionality of water zones in the engine.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 3000.0f, but can be changed at runtime through console commands or programmatically.

The associated variable CVarWaterFallbackDepth directly interacts with r.Water.FallbackDepth. They share the same value and purpose, with CVarWaterFallbackDepth being the C++ representation of the console variable.

Developers should be aware that this variable is used as a fallback value. It’s only applied when there are no ground actors defined in the scene. This means that it acts as a safety net to ensure water always has a depth, even in scenarios where the environment might not be fully set up.

Best practices when using this variable include:

  1. Consider adjusting this value based on the scale of your game world. The default 3000 units might not be suitable for all scenarios.
  2. Use this as a starting point, but define proper ground actors for more realistic water behavior when possible.
  3. Be cautious when changing this value at runtime, as it could lead to sudden visual changes in water appearance.
  4. Remember that this is part of an experimental plugin, so its behavior might change in future engine versions.

Regarding the associated variable CVarWaterFallbackDepth:

The purpose of CVarWaterFallbackDepth is to provide a C++ interface for the r.Water.FallbackDepth console variable. It allows the water system to access and use the fallback depth value within the game code.

This variable is used in the same Experimental Water plugin, specifically in the WaterZoneActor class. It’s accessed in the UpdateWaterInfoTexture function to set the minimum Z value for water when no ground actors are present.

The value of CVarWaterFallbackDepth is set through the console variable system, mirroring r.Water.FallbackDepth. It can be accessed in C++ code using the GetValueOnGameThread() method.

Developers should be aware that changes to r.Water.FallbackDepth will be reflected in CVarWaterFallbackDepth, and vice versa. This variable is used in actual calculations within the water system, so its value directly affects water rendering.

Best practices for CVarWaterFallbackDepth include:

  1. Use GetValueOnGameThread() when accessing the value to ensure thread-safety.
  2. Consider caching the value if it’s accessed frequently, to avoid potential performance overhead from repeated console variable lookups.
  3. Be aware that changes to this variable will immediately affect water rendering, so use caution when modifying it during gameplay.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterZoneActor.cpp:33

Scope: file

Source code excerpt:


TAutoConsoleVariable<float> CVarWaterFallbackDepth(
	TEXT("r.Water.FallbackDepth"),
	3000.0f,
	TEXT("Depth to use for all water when there are no ground actors defined."),
	ECVF_Default);

void OnSkipWaterInfoTextureRenderWhenWorldRenderingDisabled_Callback(IConsoleVariable*);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterZoneActor.cpp:32

Scope: file

Source code excerpt:

	TEXT("Force the water info texture to regenerate on the next N frames. A negative value will force update every frame."));

TAutoConsoleVariable<float> CVarWaterFallbackDepth(
	TEXT("r.Water.FallbackDepth"),
	3000.0f,
	TEXT("Depth to use for all water when there are no ground actors defined."),
	ECVF_Default);

void OnSkipWaterInfoTextureRenderWhenWorldRenderingDisabled_Callback(IConsoleVariable*);

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterZoneActor.cpp:564

Scope (from outer to inner):

file
function     bool AWaterZone::UpdateWaterInfoTexture

Source code excerpt:

		{
			GroundZMax = WaterZMax;
			GroundZMin = WaterZMin - CVarWaterFallbackDepth.GetValueOnGameThread();
		}

#if WITH_EDITOR
		// Check all the ground components have complete shader maps before we try to render them into the water info texture
		for (TWeakObjectPtr<UPrimitiveComponent> GroundPrimCompPtr : GroundPrimitiveComponents)
		{