r.Water.Enabled

r.Water.Enabled

#Overview

name: r.Water.Enabled

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Water.Enabled is to control whether all water rendering is enabled or disabled in Unreal Engine 5. This setting variable is part of the water rendering system within the engine.

The Water Plugin, which is an experimental feature in Unreal Engine 5, relies on this setting variable. Specifically, it’s used in the WaterSubsystem and WaterUtils modules.

The value of this variable is set through a console variable (CVar) named CVarWaterEnabled. It’s initialized with a default value of 1, meaning water rendering is enabled by default. The value can be changed at runtime through console commands or programmatically.

This variable interacts closely with other water-related variables such as CVarWaterMeshEnabled and CVarWaterMeshEnableRendering. These variables work together to control different aspects of water rendering.

Developers must be aware that this is a render thread safe variable, meaning it can be safely accessed from both the game and render threads. However, care should be taken when changing its value, as it affects the entire water rendering system.

Best practices when using this variable include:

  1. Use the FWaterUtils::IsWaterEnabled() function to check if water rendering is enabled, rather than accessing the CVar directly.
  2. Be cautious when disabling water rendering, as it may affect gameplay or visual elements that depend on water.
  3. Consider performance implications when enabling or disabling water rendering, especially in performance-critical scenarios.

Regarding the associated variable CVarWaterEnabled:

The purpose of CVarWaterEnabled is to provide a programmatic interface to the r.Water.Enabled setting. It’s an instance of TAutoConsoleVariable, which allows for easy management of the console variable.

This variable is used within the Water Plugin to control water rendering and to respond to changes in the water rendering state. It’s primarily used in the WaterSubsystem and WaterUtils modules.

The value of CVarWaterEnabled is set when the r.Water.Enabled console command is used. It can also be changed programmatically using the SetOnChangedCallback method.

CVarWaterEnabled interacts closely with other water-related variables and is used to determine if water rendering should occur.

Developers should be aware that changes to CVarWaterEnabled will trigger callbacks, which can affect the water rendering system’s behavior. It’s important to handle these changes appropriately in the code.

Best practices for using CVarWaterEnabled include:

  1. Use the provided callback mechanisms to respond to changes in water rendering state.
  2. Ensure that any code depending on water rendering checks the current state of this variable.
  3. Be mindful of performance implications when changing this variable’s value, especially in performance-critical code paths.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

// General purpose CVars:
TAutoConsoleVariable<int32> CVarWaterEnabled(
	TEXT("r.Water.Enabled"),
	1,
	TEXT("If all water rendering is enabled or disabled"),
	ECVF_RenderThreadSafe
);

static int32 FreezeWaves = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:


// General purpose CVars:
TAutoConsoleVariable<int32> CVarWaterEnabled(
	TEXT("r.Water.Enabled"),
	1,
	TEXT("If all water rendering is enabled or disabled"),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void UWaterSubsystem::Initialize

Source code excerpt:


	FConsoleVariableDelegate NotifyWaterVisibilityChanged = FConsoleVariableDelegate::CreateUObject(this, &UWaterSubsystem::NotifyWaterVisibilityChangedInternal);
	CVarWaterEnabled->SetOnChangedCallback(NotifyWaterVisibilityChanged);
	CVarWaterMeshEnabled->SetOnChangedCallback(NotifyWaterVisibilityChanged);
	CVarWaterMeshEnableRendering->SetOnChangedCallback(NotifyWaterVisibilityChanged);

#if WITH_EDITOR
	GetDefault<UWaterRuntimeSettings>()->OnSettingsChange.AddUObject(this, &UWaterSubsystem::ApplyRuntimeSettings);
#endif //WITH_EDITOR

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

Scope (from outer to inner):

file
function     void UWaterSubsystem::Deinitialize

Source code excerpt:

	CVarShallowWaterSimulationRenderTargetSize->SetOnChangedCallback(NullCallback);
	CVarShallowWaterSim->SetOnChangedCallback(NullCallback);
	CVarWaterEnabled->SetOnChangedCallback(NullCallback);
	CVarWaterMeshEnabled->SetOnChangedCallback(NullCallback);
	CVarWaterMeshEnableRendering->SetOnChangedCallback(NullCallback);

	World->OnBeginPostProcessSettings.RemoveAll(this);
	World->RemovePostProcessVolume(&UnderwaterPostProcessVolume);

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

Scope: file

Source code excerpt:

#include "RenderingThread.h"

extern TAutoConsoleVariable<int32> CVarWaterEnabled;
extern TAutoConsoleVariable<int32> CVarWaterMeshEnabled;
extern TAutoConsoleVariable<int32> CVarWaterMeshEnableRendering;

static TAutoConsoleVariable<float> CVarWaterMaxFlowVelocity(
	TEXT("r.Water.MaxFlowVelocity"),
	1024.0f,

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

Scope (from outer to inner):

file
function     bool FWaterUtils::IsWaterEnabled

Source code excerpt:

bool FWaterUtils::IsWaterEnabled(bool bIsRenderThread)
{
	return !!(bIsRenderThread ? CVarWaterEnabled.GetValueOnRenderThread() : CVarWaterEnabled.GetValueOnGameThread());
}

bool FWaterUtils::IsWaterMeshEnabled(bool bIsRenderThread)
{
	return IsWaterEnabled(bIsRenderThread) && !!(bIsRenderThread ? CVarWaterMeshEnabled.GetValueOnRenderThread() : CVarWaterMeshEnabled.GetValueOnGameThread());
}