r.Shadow.PerObjectCastDistanceMin

r.Shadow.PerObjectCastDistanceMin

#Overview

name: r.Shadow.PerObjectCastDistanceMin

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.PerObjectCastDistanceMin is to set the minimum cast distance for Per-Object shadows in Unreal Engine’s rendering system. This setting is crucial for controlling the shadow rendering behavior of individual objects in the scene.

This setting variable is primarily used by the rendering system, specifically in the shadow casting calculations for directional lights. It’s part of the Engine module and is utilized within the DirectionalLightComponent.

The value of this variable is set through a console variable (CVarPerObjectCastDistanceMin) with a default value of UE_FLOAT_HUGE_DISTANCE / 32.0f. This setting can be modified at runtime through console commands or programmatically.

The r.Shadow.PerObjectCastDistanceMin variable interacts with another variable called r.Shadow.PerObjectCastDistanceRadiusScale. Together, they determine the final cast distance for per-object shadows. The actual cast distance is calculated as the maximum of (r.Shadow.PerObjectCastDistanceRadiusScale * object-radius) and r.Shadow.PerObjectCastDistanceMin.

Developers should be aware that this variable affects the performance and visual quality of shadows in the scene. Setting it too low might result in shadow popping or other artifacts, while setting it too high might unnecessarily increase the shadow draw distance for small objects, potentially impacting performance.

Best practices when using this variable include:

  1. Adjusting it based on the scale of your scene and objects within it.
  2. Balancing it with r.Shadow.PerObjectCastDistanceRadiusScale for optimal shadow quality and performance.
  3. Testing different values in various scenarios to find the best trade-off between visual quality and performance.

Regarding the associated variable CVarPerObjectCastDistanceMin:

This is the actual console variable that stores and manages the r.Shadow.PerObjectCastDistanceMin setting. It’s defined in the DirectionalLightComponent.cpp file and is used to retrieve the current value of the setting at runtime.

The CVarPerObjectCastDistanceMin variable is accessed using GetValueOnRenderThread() method, ensuring thread-safe access to the value in rendering code. This variable is used directly in the shadow distance calculations for per-object shadows cast by directional lights.

Developers should note that modifying this console variable will have an immediate effect on the shadow rendering behavior. It’s important to use this variable consistently across the project and consider its impact on both visual quality and performance when adjusting its value.

#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:53

Scope: file

Source code excerpt:

	);
static TAutoConsoleVariable<float> CVarPerObjectCastDistanceMin(
	TEXT("r.Shadow.PerObjectCastDistanceMin"),
	(float)UE_FLOAT_HUGE_DISTANCE / 32.0f,
	TEXT("Minimum cast distance for Per-Object shadows, i.e., CastDistDance = Max(r.Shadow.PerObjectCastDistanceRadiusScale * object-radius, r.Shadow.PerObjectCastDistanceMin).\n")
	TEXT("  Default: UE_FLOAT_HUGE_DISTANCE / 32.0f"),
	ECVF_RenderThreadSafe
	);
static TAutoConsoleVariable<int32> CVarMaxNumFarShadowCascades(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe
	);
static TAutoConsoleVariable<float> CVarPerObjectCastDistanceMin(
	TEXT("r.Shadow.PerObjectCastDistanceMin"),
	(float)UE_FLOAT_HUGE_DISTANCE / 32.0f,
	TEXT("Minimum cast distance for Per-Object shadows, i.e., CastDistDance = Max(r.Shadow.PerObjectCastDistanceRadiusScale * object-radius, r.Shadow.PerObjectCastDistanceMin).\n")
	TEXT("  Default: UE_FLOAT_HUGE_DISTANCE / 32.0f"),
	ECVF_RenderThreadSafe
	);

#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
	{