r.Water.SingleLayer

r.Water.SingleLayer

#Overview

name: r.Water.SingleLayer

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.SingleLayer is to control the single water rendering system in Unreal Engine 5. This setting variable is used to enable or disable the single layer water rendering feature, which is part of the engine’s water rendering capabilities.

The Unreal Engine subsystem that relies on this setting variable is primarily the Renderer module, as evidenced by the callsites in the SingleLayerWaterRendering.cpp and SceneRendering.cpp files.

The value of this variable is set through a console variable (CVarWaterSingleLayer) with a default value of 1, meaning it’s enabled by default. It can be changed at runtime using console commands or through engine configuration files.

The associated variable CVarWaterSingleLayer interacts directly with r.Water.SingleLayer, as they share the same value. This console variable is used throughout the code to check whether the single layer water rendering should be performed.

Developers must be aware of the following when using this variable:

  1. Disabling this feature (setting it to 0) will cause water materials using the single layer system to become invisible.
  2. There’s a warning system in place that notifies users when single layer water rendering is disabled but water materials are present in the scene.
  3. The variable affects performance and visual quality, so it’s marked as both render thread safe and a scalability option.

Best practices when using this variable include:

  1. Ensure it’s enabled (set to 1) when using water materials that rely on the single layer water system.
  2. Consider the performance implications when enabling or disabling this feature, especially on lower-end hardware.
  3. Use it in conjunction with other water-related settings for optimal water rendering results.
  4. Be aware of its impact on visibility and adjust your scene accordingly if you need to disable it.

Regarding the associated variable CVarWaterSingleLayer:

The purpose of CVarWaterSingleLayer is to provide a programmatic way to access and modify the r.Water.SingleLayer setting within the engine’s C++ code. It’s an auto console variable that directly controls the single layer water rendering system.

This variable is used in multiple functions within the SingleLayerWaterRendering.cpp file to determine whether single layer water rendering should occur. It’s checked in functions like ShouldRenderSingleLayerWater and ShouldRenderSingleLayerWaterSkippedRenderEditorNotification to control the rendering behavior and provide appropriate notifications.

The value of CVarWaterSingleLayer is typically set through the engine’s configuration system or console commands, but it can also be modified programmatically if needed.

Developers should be aware that changes to CVarWaterSingleLayer will immediately affect the rendering pipeline, so it should be used carefully, especially in performance-critical scenarios.

Best practices for using CVarWaterSingleLayer include:

  1. Use GetValueOnRenderThread() when accessing its value in render thread code.
  2. Consider caching the value if it’s accessed frequently in performance-critical sections.
  3. Be mindful of its impact on rendering performance and visual quality when modifying it.
  4. Coordinate its usage with other water-related settings for consistent results.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarWaterSingleLayer(
	TEXT("r.Water.SingleLayer"), 1,
	TEXT("Enable the single water rendering system."),
	ECVF_RenderThreadSafe | ECVF_Scalability);

//
// Reflections

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:3969

Scope (from outer to inner):

file
lambda-function

Source code excerpt:

						if (bSingleLayerWaterWarning)
						{
							static const FText Message = NSLOCTEXT("Renderer", "SingleLayerWater", "r.Water.SingleLayer rendering is disabled with a view containing mesh(es) using water material. Meshes are not visible.");
							Writer.DrawLine(Message);
						}

						if (bLumenEnabledButHasNoDataForTracing)
						{
							static const FText Message = NSLOCTEXT("Renderer", "LumenCantDisplay", "Lumen is enabled, but has no ray tracing data and won't operate correctly.\nEither configure Lumen to use software distance field ray tracing and enable 'Generate Mesh Distancefields' in project settings\nor configure Lumen to use Hardware Ray Tracing and enable 'Support Hardware Ray Tracing' in project settings.");

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

DECLARE_CYCLE_STAT(TEXT("WaterSingleLayer"), STAT_CLP_WaterSingleLayerPass, STATGROUP_ParallelCommandListMarkers);

static TAutoConsoleVariable<int32> CVarWaterSingleLayer(
	TEXT("r.Water.SingleLayer"), 1,
	TEXT("Enable the single water rendering system."),
	ECVF_RenderThreadSafe | ECVF_Scalability);

//
// Reflections

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

Scope (from outer to inner):

file
function     bool ShouldRenderSingleLayerWater

Source code excerpt:

bool ShouldRenderSingleLayerWater(TArrayView<const FViewInfo> Views)
{
	if (CVarWaterSingleLayer.GetValueOnRenderThread() > 0)
	{
		for (const FViewInfo& View : Views)
		{
			if (View.bHasSingleLayerWaterMaterial && View.ParallelMeshDrawCommandPasses[EMeshPass::SingleLayerWaterPass].HasAnyDraw())
			{
				return true;

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

Scope (from outer to inner):

file
function     bool ShouldRenderSingleLayerWaterSkippedRenderEditorNotification

Source code excerpt:

bool ShouldRenderSingleLayerWaterSkippedRenderEditorNotification(TArrayView<const FViewInfo> Views)
{
	if (CVarWaterSingleLayer.GetValueOnRenderThread() <= 0)
	{
		for (const FViewInfo& View : Views)
		{
			if (View.bHasSingleLayerWaterMaterial)
			{
				return true;

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

Scope: file

Source code excerpt:

	FLumenSceneFrameTemporaries& LumenFrameTemporaries)
{
	if (CVarWaterSingleLayer.GetValueOnRenderThread() <= 0)
	{
		return;
	}

	const FRDGSystemTextures& SystemTextures = FRDGSystemTextures::Get(GraphBuilder);
	FRDGTextureRef SceneColorTexture = SceneTextures.Color.Resolve;