r.Water.SingleLayer.OptimizedClear

r.Water.SingleLayer.OptimizedClear

#Overview

name: r.Water.SingleLayer.OptimizedClear

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.SingleLayer.OptimizedClear is to toggle an optimized depth clear for single-layer water rendering in Unreal Engine 5. This setting is part of the rendering system, specifically related to water rendering optimization.

Based on the callsites, this setting variable is used in the Renderer module of Unreal Engine, particularly in the single-layer water rendering subsystem. It’s referenced in the file SingleLayerWaterRendering.cpp, which suggests it’s closely tied to the water rendering pipeline.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning the optimized clear is enabled by default. Developers can change this value at runtime using console commands or through configuration files.

This variable interacts with a C++ variable named CVarSingleLayerWaterPassOptimizedClear, which is the actual TAutoConsoleVariable instance that holds and manages the value of r.Water.SingleLayer.OptimizedClear.

Developers should be aware that this variable affects the performance of water rendering. When enabled (set to 1), it uses an optimized method for clearing the depth buffer in the single-layer water rendering pass. However, the implementation seems to be conditional and possibly platform-dependent, as indicated by the commented-out code checking for GRHISupportsDepthUAV and GRHISupportsExplicitHTile.

Best practices when using this variable include:

  1. Testing performance with both enabled (1) and disabled (0) states to determine the optimal setting for your specific use case.
  2. Be aware that changing this setting might affect visual quality or performance, so thorough testing is recommended.
  3. Consider platform-specific behavior, as the optimized clear might not be available or beneficial on all hardware.

Regarding the associated variable CVarSingleLayerWaterPassOptimizedClear:

This is the actual C++ variable that represents the console variable in the engine’s code. It’s an instance of TAutoConsoleVariable, which means it’s an automatically registered console variable that holds an integer value.

The purpose of CVarSingleLayerWaterPassOptimizedClear is to provide a programmatic interface to access and modify the r.Water.SingleLayer.OptimizedClear setting within the C++ code of the engine.

This variable is used directly in the rendering code to check the current state of the optimization. For example, it’s queried using GetValueOnRenderThread() to determine whether to use the optimized clear path or not.

Developers working on the rendering system should use this variable when they need to read or modify the optimized clear setting in C++ code. They should be aware that changes to this variable will directly affect the behavior of the single-layer water rendering system.

Best practices for using CVarSingleLayerWaterPassOptimizedClear include:

  1. Always access its value using GetValueOnRenderThread() when in render thread code to ensure thread-safe access.
  2. Be cautious about changing its value during runtime, as it could impact performance or visual quality unexpectedly.
  3. If modifying the behavior controlled by this variable, ensure to test thoroughly across different hardware configurations.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSingleLayerWaterPassOptimizedClear(
	TEXT("r.Water.SingleLayer.OptimizedClear"), 1,
	TEXT("Toggles optimized depth clear"),
	ECVF_RenderThreadSafe);

static int32 GetSingleLayerWaterReflectionTechnique()
{
	const int32 Value = CVarWaterSingleLayerReflection.GetValueOnRenderThread();

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSingleLayerWaterPassOptimizedClear(
	TEXT("r.Water.SingleLayer.OptimizedClear"), 1,
	TEXT("Toggles optimized depth clear"),
	ECVF_RenderThreadSafe);

static int32 GetSingleLayerWaterReflectionTechnique()
{

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

Scope (from outer to inner):

file
function     FSingleLayerWaterPrePassResult* FDeferredShadingSceneRenderer::RenderSingleLayerWaterDepthPrepass

Source code excerpt:

		// TODO: replace with AddCopyTexturePass() and AddClearDepthStencilPass() once CopyTexture() supports depth buffer copies on all platforms.

		const bool bOptimizedClear = CVarSingleLayerWaterPassOptimizedClear.GetValueOnRenderThread() == 1;
		if (false)//bOptimizedClear && GRHISupportsDepthUAV && GRHISupportsExplicitHTile)
		{
			// TODO: Implement optimized copy path
		}
		else
		{