r.Shadow.PerObjectCastDistanceRadiusScale

r.Shadow.PerObjectCastDistanceRadiusScale

#Overview

name: r.Shadow.PerObjectCastDistanceRadiusScale

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.PerObjectCastDistanceRadiusScale is to control the maximum distance that a per-object directional shadow can reach. It is used in the rendering system, specifically for shadow calculations.

This setting variable is primarily used in the Engine module, particularly in the DirectionalLightComponent. It’s part of the rendering subsystem, focusing on shadow rendering for directional lights.

The value of this variable is set as a console variable with a default value of 8.0f. It can be modified at runtime through the console or configuration files.

The variable interacts closely with CVarPerObjectCastDistanceMin, which sets a minimum distance for shadow casting. Together, these variables determine the range of shadow casting for objects.

Developers must be aware that this variable scales with the radius of the object. It’s particularly important for large objects, as it affects how far their shadows can be cast. The actual maximum distance is calculated by multiplying this scale factor with the object’s radius.

Best practices when using this variable include:

  1. Adjusting it carefully to balance between shadow quality and performance.
  2. Considering the scale of objects in your scene when modifying this value.
  3. Testing with various object sizes to ensure desired shadow behavior across different scales.

Regarding the associated variable CVarPerObjectCastDistanceRadiusScale:

This is the C++ implementation of the console variable. It’s defined using TAutoConsoleVariable, which allows for runtime modification. The variable is used directly in the FDirectionalLightSceneProxy class to calculate the MaxDistanceToCastInLightW.

The value is retrieved using GetValueOnRenderThread(), ensuring thread-safe access in the rendering pipeline. It’s multiplied with the object’s sphere radius and then clamped between the minimum distance (CVarPerObjectCastDistanceMin) and WORLD_MAX.

Developers should note that changes to this variable will affect all directional lights in the scene. It’s a global setting that can have a significant impact on both visual quality and performance, especially in scenes with many large objects casting shadows.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/DirectionalLightComponent.cpp:47

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarPerObjectCastDistanceRadiusScale(
	TEXT("r.Shadow.PerObjectCastDistanceRadiusScale"),
	8.0f,
	TEXT("PerObjectCastDistanceRadiusScale The scale factor multiplied with the radius of the object to calculate the maximum distance a per-object directional shadow can reach. This will only take effect after a certain (large) radius. Default is 8 times the object radius."),
	ECVF_RenderThreadSafe
	);
static TAutoConsoleVariable<float> CVarPerObjectCastDistanceMin(
	TEXT("r.Shadow.PerObjectCastDistanceMin"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/DirectionalLightComponent.cpp:46

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_Scalability );

static TAutoConsoleVariable<float> CVarPerObjectCastDistanceRadiusScale(
	TEXT("r.Shadow.PerObjectCastDistanceRadiusScale"),
	8.0f,
	TEXT("PerObjectCastDistanceRadiusScale The scale factor multiplied with the radius of the object to calculate the maximum distance a per-object directional shadow can reach. This will only take effect after a certain (large) radius. Default is 8 times the object radius."),
	ECVF_RenderThreadSafe
	);
static TAutoConsoleVariable<float> CVarPerObjectCastDistanceMin(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/DirectionalLightComponent.cpp:542

Scope (from outer to inner):

file
class        class FDirectionalLightSceneProxy : public FLightSceneProxy
function     virtual bool GetPerObjectProjectedShadowInitializer

Source code excerpt:

		// This is necessary to improve floating point precision in several places, especially when deriving frustum verts from InvReceiverMatrix
		// This takes the object size into account to ensure that large objects get an extended distance
		OutInitializer.MaxDistanceToCastInLightW = FMath::Clamp(SubjectBounds.SphereRadius * CVarPerObjectCastDistanceRadiusScale.GetValueOnRenderThread(), CVarPerObjectCastDistanceMin.GetValueOnRenderThread(), (float)WORLD_MAX);

		return true;
	}

	virtual bool ShouldCreateRayTracedCascade(ERHIFeatureLevel::Type InFeatureLevel, bool bPrecomputedLightingIsValid, int32 MaxNearCascades) const override
	{