r.ParallelSingleLayerWaterPass

r.ParallelSingleLayerWaterPass

#Overview

name: r.ParallelSingleLayerWaterPass

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ParallelSingleLayerWaterPass is to control the parallel rendering of the single layer water pass in Unreal Engine 5’s rendering system. This setting variable is specifically designed for optimizing the rendering of water surfaces.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the single layer water rendering subsystem. It’s referenced in the file ‘SingleLayerWaterRendering.cpp’, which is part of the runtime renderer.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning parallel rendering is enabled by default for the single layer water pass.

The associated variable CVarParallelSingleLayerWaterPass directly interacts with r.ParallelSingleLayerWaterPass. They share the same value and purpose.

Developers must be aware that this variable only has an effect when parallel rendering is enabled in the engine. The comment in the code explicitly states: “Parallel rendering must be enabled for this to have an effect.”

Best practices when using this variable include:

  1. Ensure that parallel rendering is enabled in the engine for this setting to take effect.
  2. Monitor performance when toggling this setting, as parallel rendering may not always be beneficial depending on the specific scene and hardware.
  3. Use in conjunction with other water rendering settings for optimal results.

Regarding the associated variable CVarParallelSingleLayerWaterPass:

The purpose of CVarParallelSingleLayerWaterPass is identical to r.ParallelSingleLayerWaterPass. It’s an internal representation of the console variable within the C++ code.

This variable is used directly in the rendering code to determine whether to use parallel rendering for the single layer water pass. It’s checked in both the depth pre-pass (RenderSingleLayerWaterDepthPrepass) and the main rendering pass (RenderSingleLayerWaterInner) of the single layer water system.

The value of this variable is retrieved on the render thread using GetValueOnRenderThread(), indicating that it’s designed to be changed dynamically during runtime.

Developers should be aware that changing this variable will immediately affect the rendering pipeline for single layer water. It’s thread-safe for the render thread, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using CVarParallelSingleLayerWaterPass include:

  1. Use it in conjunction with GRHICommandList.UseParallelAlgorithms() to ensure parallel rendering is fully enabled.
  2. Consider exposing this setting to artists or in performance settings to allow fine-tuning of water rendering performance.
  3. Profile the impact of this setting on different hardware configurations to determine the optimal default value for your project.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarParallelSingleLayerWaterPass(
	TEXT("r.ParallelSingleLayerWaterPass"), 1,
	TEXT("Toggles parallel single layer water pass rendering. Parallel rendering must be enabled for this to have an effect."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRHICmdFlushRenderThreadTasksSingleLayerWater(
	TEXT("r.RHICmdFlushRenderThreadTasksSingleLayerWater"), 0,
	TEXT("Wait for completion of parallel render thread tasks at the end of Single layer water. A more granular version of r.RHICmdFlushRenderThreadTasks. If either r.RHICmdFlushRenderThreadTasks or r.RHICmdFlushRenderThreadTasksSingleLayerWater is > 0 we will flush."));

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarParallelSingleLayerWaterPass(
	TEXT("r.ParallelSingleLayerWaterPass"), 1,
	TEXT("Toggles parallel single layer water pass rendering. Parallel rendering must be enabled for this to have an effect."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRHICmdFlushRenderThreadTasksSingleLayerWater(
	TEXT("r.RHICmdFlushRenderThreadTasksSingleLayerWater"), 0,

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

Scope (from outer to inner):

file
function     FSingleLayerWaterPrePassResult* FDeferredShadingSceneRenderer::RenderSingleLayerWaterDepthPrepass

Source code excerpt:

	}

	const bool bRenderInParallel = GRHICommandList.UseParallelAlgorithms() && CVarParallelSingleLayerWaterPass.GetValueOnRenderThread() == 1;

	for (int32 ViewIndex = 0; ViewIndex < Views.Num(); ++ViewIndex)
	{
		FViewInfo& View = Views[ViewIndex];

		if (!View.ShouldRenderView())

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderSingleLayerWaterInner

Source code excerpt:

	RDG_EVENT_SCOPE(GraphBuilder, "SLW::Draw");

	const bool bRenderInParallel = GRHICommandList.UseParallelAlgorithms() && CVarParallelSingleLayerWaterPass.GetValueOnRenderThread() == 1;

	const FRDGSystemTextures& SystemTextures = FRDGSystemTextures::Get(GraphBuilder);

	TStaticArray<FTextureRenderTargetBinding, MaxSimultaneousRenderTargets> BasePassTextures;
	uint32 BasePassTextureCount = SceneTextures.GetGBufferRenderTargets(BasePassTextures);
	if(NeedsSeparatedMainDirectionalLightTexture(Scene->GetShaderPlatform()))