r.RayTracing.Shadows.MaxBatchSize

r.RayTracing.Shadows.MaxBatchSize

#Overview

name: r.RayTracing.Shadows.MaxBatchSize

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.RayTracing.Shadows.MaxBatchSize is to control the maximum number of shadows that can be traced simultaneously in the ray tracing system of Unreal Engine 5. This setting is specifically related to the rendering system, particularly the ray tracing functionality for shadows.

This setting variable is primarily used in the Renderer module of Unreal Engine, as evidenced by its location in the LightRendering.cpp file within the Runtime/Renderer/Private directory.

The value of this variable is set through a console variable (CVar) system, which allows for runtime configuration. It’s initialized with a default value of 8, but can be changed during runtime or through configuration files.

The variable interacts with other ray tracing and shadow-related variables, particularly in the context of batching shadow calculations. It’s used in conjunction with CVarMaxShadowDenoisingBatchSize to determine whether to perform shadow batching and how many shadows to process in each batch.

Developers should be aware that this variable directly impacts the performance and quality trade-off in ray-traced shadow rendering. A higher value may improve performance by processing more shadows simultaneously, but it could also increase memory usage and potentially affect frame rate if set too high.

Best practices for using this variable include:

  1. Adjusting it based on the specific needs of the scene and target hardware capabilities.
  2. Testing different values to find the optimal balance between performance and visual quality.
  3. Considering it in conjunction with other shadow and ray tracing settings for holistic optimization.

Regarding the associated variable CVarMaxShadowRayTracingBatchSize:

This is the actual console variable that stores and provides access to the r.RayTracing.Shadows.MaxBatchSize setting. It’s defined using the TAutoConsoleVariable template, which is part of Unreal Engine’s configuration system.

The purpose of CVarMaxShadowRayTracingBatchSize is to provide a runtime-configurable way to access and modify the maximum shadow ray tracing batch size.

This variable is used directly in the rendering code to determine the batch size for shadow ray tracing operations. It’s accessed using the GetValueOnRenderThread() method, ensuring thread-safe access to the current value.

Developers should be aware that changes to this variable will take effect on the render thread, which means there might be a slight delay between changing the value and seeing the effect in the rendered output.

Best practices for using CVarMaxShadowRayTracingBatchSize include:

  1. Using it for performance tuning and debugging.
  2. Considering its impact on both CPU and GPU performance when adjusting its value.
  3. Documenting any non-default values used in production to ensure consistency across development and deployment environments.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:100

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarMaxShadowRayTracingBatchSize(
	TEXT("r.RayTracing.Shadows.MaxBatchSize"), 8,
	TEXT("Maximum number of shadows to trace at the same time."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarAllowClearLightSceneExtentsOnly(
	TEXT("r.AllowClearLightSceneExtentsOnly"), 1,
	TEXT(""),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:99

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarMaxShadowRayTracingBatchSize(
	TEXT("r.RayTracing.Shadows.MaxBatchSize"), 8,
	TEXT("Maximum number of shadows to trace at the same time."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarAllowClearLightSceneExtentsOnly(
	TEXT("r.AllowClearLightSceneExtentsOnly"), 1,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:1504

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderLights

Source code excerpt:


			const int32 MaxDenoisingBatchSize = FMath::Clamp(CVarMaxShadowDenoisingBatchSize.GetValueOnRenderThread(), 1, IScreenSpaceDenoiser::kMaxBatchSize);
			const int32 MaxRTShadowBatchSize = CVarMaxShadowRayTracingBatchSize.GetValueOnRenderThread();
			const bool bDoShadowDenoisingBatching = DenoiserMode != 0 && MaxDenoisingBatchSize > 1;

			//#dxr_todo: support multiview for the batching case
			const bool bDoShadowBatching = (bDoShadowDenoisingBatching || MaxRTShadowBatchSize > 1) && Views.Num() == 1;

			// Optimizations: batches all shadow ray tracing denoising. Definitely could be smarter to avoid high VGPR pressure if this entire