r.Water.OceanFallbackDepth

r.Water.OceanFallbackDepth

#Overview

name: r.Water.OceanFallbackDepth

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Water.OceanFallbackDepth is to provide a default depth value for ocean water bodies when no terrain is found under the query location. This setting is primarily used in the water simulation system of Unreal Engine 5.

This setting variable is relied upon by the Water plugin, specifically within the WaterBodyComponent and WaterBodyTypes modules. These are part of the experimental Water system in Unreal Engine 5.

The value of this variable is set as a console variable with a default value of 3000.0f. It can be modified at runtime through the console or configuration files.

The associated variable CVarWaterOceanFallbackDepth directly interacts with r.Water.OceanFallbackDepth. They share the same value and purpose.

Developers must be aware that this variable is only used when its value is greater than 0. If set to 0 or a negative value, the fallback depth mechanism will not be used.

Best practices when using this variable include:

  1. Ensure it’s set to a reasonable depth value that matches your game’s ocean scale.
  2. Consider adjusting this value if your game features unusually deep or shallow oceans.
  3. Be aware that this is a fallback value and should not replace proper terrain setup under ocean areas where possible.
  4. Monitor performance impacts if querying ocean depth frequently, as this fallback might be used more often than intended.

Regarding the associated variable CVarWaterOceanFallbackDepth:

The purpose of CVarWaterOceanFallbackDepth is identical to r.Water.OceanFallbackDepth. It’s the C++ representation of the console variable.

This variable is used within the Water plugin, specifically in the WaterBodyComponent and WaterBodyTypes modules.

The value is set when the TAutoConsoleVariable is initialized, but can be modified at runtime using console commands.

CVarWaterOceanFallbackDepth directly interacts with r.Water.OceanFallbackDepth, as they represent the same setting.

Developers should be aware that this variable is accessed using GetValueOnAnyThread(), which suggests it can be safely read from any thread.

Best practices for using CVarWaterOceanFallbackDepth include:

  1. Use it for reading the current fallback depth value in C++ code.
  2. Avoid frequently changing this value during gameplay, as it might affect consistency in water depth calculations.
  3. Consider caching the value if used frequently in performance-critical code sections.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<float> CVarWaterOceanFallbackDepth(
	TEXT("r.Water.OceanFallbackDepth"),
	3000.0f,
	TEXT("Depth to report for the ocean when no terrain is found under the query location. Not used when <= 0."),
	ECVF_Default);

TAutoConsoleVariable<int32> CVarWaterBodyBuildConservativeRasterizationMesh(
	TEXT("r.Water.BuildConservativeRasterizationMesh"), 1,

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

// ----------------------------------------------------------------------------------

TAutoConsoleVariable<float> CVarWaterOceanFallbackDepth(
	TEXT("r.Water.OceanFallbackDepth"),
	3000.0f,
	TEXT("Depth to report for the ocean when no terrain is found under the query location. Not used when <= 0."),
	ECVF_Default);

TAutoConsoleVariable<int32> CVarWaterBodyBuildConservativeRasterizationMesh(

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

Scope (from outer to inner):

file
function     FWaterBodyQueryResult UWaterBodyComponent::QueryWaterInfoClosestToWorldLocation

Source code excerpt:

				{
					// Fallback value when landscape is not found under the ocean water.
					WaterPlaneDepth = CVarWaterOceanFallbackDepth.GetValueOnAnyThread();
				}
				else
				{
					check(GetWaterBodyType() == EWaterBodyType::Lake);
					// For an underwater lake, consider an uniform depth across the projection segment on the lake spline :
					WaterPlaneDepth = WaterSplineMetadata->Depth.Eval(Result.LazilyComputeSplineKey(*this, InWorldLocation), 0.f);

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

Scope (from outer to inner):

file
function     FWaterBodyQueryResult FSolverSafeWaterBodyData::QueryWaterInfoClosestToWorldLocation

Source code excerpt:

				{
					// Fallback value when landscape is not found under the ocean water.
					WaterPlaneDepth = CVarWaterOceanFallbackDepth.GetValueOnAnyThread();
				}
				else
				{
					check(WaterBodyType == EWaterBodyType::Lake);
					// For an underwater lake, consider an uniform depth across the projection segment on the lake spline :
					WaterPlaneDepth = WaterSplineMetadata.Depth.Eval(Result.LazilyComputeSplineKey(WaterSpline, InWorldLocation), 0.f);

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Public/WaterBodyTypes.h:11

Scope: file

Source code excerpt:

struct FWaterSplineDataPhysics;

extern TAutoConsoleVariable<float> CVarWaterOceanFallbackDepth;

UENUM(BlueprintType)
enum class EWaterBodyType : uint8
{
	/** Rivers defined by a spline down the middle */
	River,