r.Water.SingleLayer.Reflection

r.Water.SingleLayer.Reflection

#Overview

name: r.Water.SingleLayer.Reflection

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.SingleLayer.Reflection is to control the reflection technique used on single layer water in Unreal Engine 5’s rendering system. This console variable allows developers to adjust how water reflections are rendered, offering different options for performance and visual quality.

The Unreal Engine subsystem that relies on this setting variable is primarily the Renderer module, specifically the single layer water rendering system. This can be seen from the file location “Engine/Source/Runtime/Renderer/Private/SingleLayerWaterRendering.cpp”.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with default value 1, but can be changed at runtime or through configuration files.

This variable interacts closely with the ESingleLayerWaterReflections enum, which defines the possible reflection techniques. It also interacts with other rendering systems like Lumen reflections, as seen in the ShouldRenderLumenReflectionsWater function.

Developers must be aware that this variable offers four options: 0: Disabled 1: Enabled (same as rest of scene) 2: Force Reflection Captures and Sky 3: Force SSR (Screen Space Reflections)

Each option will have different performance implications and visual results. The choice may depend on the specific needs of the project, target hardware, and desired visual fidelity.

Best practices when using this variable include:

  1. Consider performance implications of each option, especially on lower-end hardware.
  2. Test thoroughly with different settings to ensure the best balance of visual quality and performance.
  3. Be aware that forcing certain reflection types (options 2 and 3) may not always produce the best results in all scenarios.
  4. Remember that Lumen reflections for water are only available when using the default reflection method (option 1).

The associated variable CVarWaterSingleLayerReflection is the actual console variable that stores and manages the value of r.Water.SingleLayer.Reflection. It’s defined as a static TAutoConsoleVariable, which means it’s a global variable that can be accessed and modified from the console or through C++ code.

The purpose of CVarWaterSingleLayerReflection is to provide a programmatic way to access and modify the r.Water.SingleLayer.Reflection setting. It’s used internally by the rendering system to determine which reflection technique to use for single layer water.

This variable is typically accessed using the GetValueOnRenderThread() method, as seen in the GetSingleLayerWaterReflectionTechnique() function. This ensures thread-safe access to the variable’s value.

Developers should be aware that modifying CVarWaterSingleLayerReflection directly in C++ code will have the same effect as changing r.Water.SingleLayer.Reflection through the console. They should also note that the value is clamped between 0 and the maximum value defined in ESingleLayerWaterReflections to prevent invalid settings.

Best practices for using CVarWaterSingleLayerReflection include:

  1. Use the GetValueOnRenderThread() method when accessing the value to ensure thread safety.
  2. Consider using the GetSingleLayerWaterReflectionTechnique() function instead of accessing the variable directly, as it handles value clamping.
  3. Be cautious when modifying this variable at runtime, as it can have immediate effects on rendering performance and visual quality.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarWaterSingleLayerReflection(
	TEXT("r.Water.SingleLayer.Reflection"), 1,
	TEXT("Reflection technique to use on single layer water. 0: Disabled, 1: Enabled (same as rest of scene), 2: Force Reflection Captures and Sky, 3: Force SSR"),
	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarWaterSingleLayerTiledComposite(
	TEXT("r.Water.SingleLayer.TiledComposite"), 1,
	TEXT("Enable tiled optimization of the single layer water reflection rendering system."),

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

Scope (from outer to inner):

file
function     bool ShouldRenderLumenReflectionsWater

Source code excerpt:

bool ShouldRenderLumenReflectionsWater(const FViewInfo& View, bool bSkipTracingDataCheck, bool bSkipProjectCheck)
{
	// This only returns true if using the default reflections method and having Lumen enabled in the scene. It can't be forced with r.Water.SingleLayer.Reflection.
	return !View.bIsReflectionCapture 
		&& GetSingleLayerWaterReflectionTechnique() == ESingleLayerWaterReflections::Enabled
		&& ShouldRenderLumenReflections(View, bSkipTracingDataCheck, bSkipProjectCheck);
}

bool ShouldUseBilinearSamplerForDepthWithoutSingleLayerWater(EPixelFormat DepthTextureFormat)

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

}

static TAutoConsoleVariable<int32> CVarWaterSingleLayerReflection(
	TEXT("r.Water.SingleLayer.Reflection"), 1,
	TEXT("Reflection technique to use on single layer water. 0: Disabled, 1: Enabled (same as rest of scene), 2: Force Reflection Captures and Sky, 3: Force SSR"),
	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarWaterSingleLayerTiledComposite(
	TEXT("r.Water.SingleLayer.TiledComposite"), 1,

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

Scope (from outer to inner):

file
function     static int32 GetSingleLayerWaterReflectionTechnique

Source code excerpt:

static int32 GetSingleLayerWaterReflectionTechnique()
{
	const int32 Value = CVarWaterSingleLayerReflection.GetValueOnRenderThread();
	return FMath::Clamp(Value, 0, ESingleLayerWaterReflections::MaxValue);
}

// This is to have platforms use the simple single layer water shading similar to mobile: no dynamic lights, only sun and sky, no distortion, no colored transmittance on background, no custom depth read.
bool SingleLayerWaterUsesSimpleShading(EShaderPlatform ShaderPlatform)
{

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

Scope: file

Source code excerpt:

		}

		// ReflectionsMethodWater can also be Disabled when only reflection captures are requested, so check CVarWaterSingleLayerReflection directly before early exiting.
		if (GetSingleLayerWaterReflectionTechnique() == ESingleLayerWaterReflections::Disabled)
		{
			continue;
		}

		if (ViewPipelineState.ReflectionsMethodWater == EReflectionsMethod::Lumen)