r.Shadow.PreshadowExpand

r.Shadow.PreshadowExpand

#Overview

name: r.Shadow.PreshadowExpand

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.Shadow.PreshadowExpand is to control the expansion of bounds when rendering cached preshadows in Unreal Engine’s rendering system. This setting variable is used to improve shadow caching efficiency by allowing a larger area to be covered by the preshadow, potentially increasing cache hits at the cost of lower resolution and including more objects in the depth pass.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the shadow setup and rendering subsystem. Based on the callsites, it’s clear that this variable is utilized in the ShadowSetup.cpp file, which is part of the core rendering pipeline.

The value of this variable is set as a console variable with a default value of 0.15 (15% larger). It can be modified at runtime through the console or configuration files.

The associated variable CVarPreshadowExpandFraction directly interacts with r.Shadow.PreshadowExpand. They share the same value and purpose, with CVarPreshadowExpandFraction being the C++ representation of the console variable.

Developers must be aware that increasing this value will result in more cache hits for preshadows, which can improve performance in some scenarios. However, it comes with the trade-off of lower shadow resolution and potentially including more objects in the depth pass, which could impact performance in other ways.

Best practices when using this variable include:

  1. Carefully balancing the value to find the optimal trade-off between cache hits and shadow quality for your specific game or application.
  2. Testing different values in various scenarios to ensure it doesn’t negatively impact overall performance or visual quality.
  3. Considering the target hardware and adjusting the value accordingly, as lower-end devices might benefit from higher values to improve performance.
  4. Monitoring the impact on memory usage, as larger preshadow areas may require more memory.

Regarding the associated variable CVarPreshadowExpandFraction:

The purpose of CVarPreshadowExpandFraction is to provide a C++ interface for the r.Shadow.PreshadowExpand console variable. It allows the engine code to access and use the preshadow expand value in shadow-related calculations.

This variable is used in the same Renderer module and shadow setup subsystem as r.Shadow.PreshadowExpand. It’s primarily used in the CreatePerObjectProjectedShadow function to calculate the expanded bounds for preshadows.

The value of CVarPreshadowExpandFraction is set by the r.Shadow.PreshadowExpand console variable. It directly reflects any changes made to r.Shadow.PreshadowExpand.

CVarPreshadowExpandFraction interacts closely with the shadow bounds calculations, affecting the SphereRadius and BoxExtent of the shadow Bounds object.

Developers should be aware that this variable is accessed on the render thread, so any modifications should be thread-safe and consider potential race conditions.

Best practices for using CVarPreshadowExpandFraction include:

  1. Accessing the value using GetValueOnRenderThread() to ensure thread safety.
  2. Clamping the value to a minimum of 0.0f to prevent negative expansions.
  3. Considering the performance implications of frequently accessing this value in performance-critical code paths.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:192

Scope: file

Source code excerpt:

 */
static TAutoConsoleVariable<float> CVarPreshadowExpandFraction(
	TEXT("r.Shadow.PreshadowExpand"),
	0.15f,
	TEXT("How much bounds will be expanded when rendering a cached preshadow (0.15 = 15% larger)"),
	ECVF_RenderThreadSafe
	);

static TAutoConsoleVariable<float> CVarPreShadowResolutionFactor(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:191

Scope: file

Source code excerpt:

 * Larger values result in more cache hits, but lower resolution and pull more objects into the depth pass.
 */
static TAutoConsoleVariable<float> CVarPreshadowExpandFraction(
	TEXT("r.Shadow.PreshadowExpand"),
	0.15f,
	TEXT("How much bounds will be expanded when rendering a cached preshadow (0.15 = 15% larger)"),
	ECVF_RenderThreadSafe
	);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:3407

Scope (from outer to inner):

file
function     void FSceneRenderer::CreatePerObjectProjectedShadow

Source code excerpt:

	if (bRenderPreShadow && ShouldUseCachePreshadows())
	{
		float PreshadowExpandFraction = FMath::Max(CVarPreshadowExpandFraction.GetValueOnRenderThread(), 0.0f);

		// If we're creating a preshadow, expand the bounds somewhat so that the preshadow will be cached more often as the shadow caster moves around.
		//@todo - only expand the preshadow bounds for this, not the per object shadow.
		Bounds.SphereRadius += (Bounds.BoxExtent * PreshadowExpandFraction).Size();
		Bounds.BoxExtent *= PreshadowExpandFraction + 1.0f;
	}