r.Shadow.PerObject

r.Shadow.PerObject

#Overview

name: r.Shadow.PerObject

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.PerObject is to control whether per-object shadows are rendered in the game. Per-object shadows refer to shadows cast by individual objects, such as characters, onto the world.

This setting variable is primarily used by the rendering system in Unreal Engine 5, specifically in the shadow rendering subsystem. Based on the callsites, it’s clear that this variable is utilized within the Renderer module of the engine.

The value of this variable is set through a console variable (CVarAllowPerObjectShadows) with a default value of 1 (enabled). It can be changed at runtime through console commands or programmatically.

The associated variable CVarAllowPerObjectShadows directly interacts with r.Shadow.PerObject. They share the same value and purpose.

Developers must be aware that this variable affects rendering performance and visual quality. Enabling per-object shadows (value 1) provides more detailed and realistic shadows for individual objects but may impact performance. Disabling it (value 0) can improve performance at the cost of visual fidelity.

Best practices when using this variable include:

  1. Leaving it enabled (1) for final builds to ensure high-quality visuals.
  2. Considering disabling it (0) for performance-critical scenarios or on lower-end hardware.
  3. Using it for debugging shadow-related issues by toggling it on and off.

Regarding the associated variable CVarAllowPerObjectShadows:

The purpose of CVarAllowPerObjectShadows is identical to r.Shadow.PerObject. It’s the actual console variable implementation that controls the per-object shadow rendering.

This variable is used directly in the rendering code to determine whether to create per-object shadows. It’s checked in the FSceneRenderer::CreatePerObjectProjectedShadow function, which is part of the shadow setup process.

The value of CVarAllowPerObjectShadows is set when the console variable is initialized, but it can be changed at runtime using console commands.

As it’s the implementation of r.Shadow.PerObject, it interacts with the same systems and affects the same rendering processes.

Developers should be aware that this variable is accessed on the render thread (ECVF_RenderThreadSafe), which means changes to it will be applied on the next frame render.

Best practices for CVarAllowPerObjectShadows are the same as for r.Shadow.PerObject, as they are essentially the same setting. Developers should use the r.Shadow.PerObject console command to modify this setting rather than directly manipulating the CVarAllowPerObjectShadows variable in code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

/** Whether to allow per object shadows (character casting on world), can be disabled for debugging. */
static TAutoConsoleVariable<int32> CVarAllowPerObjectShadows(
	TEXT("r.Shadow.PerObject"),
	1,
	TEXT("Whether to render per object shadows (character casting on world)\n")
	TEXT("0: off\n")
	TEXT("1: on (default)"),
	ECVF_RenderThreadSafe
	);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:


/** Whether to allow per object shadows (character casting on world), can be disabled for debugging. */
static TAutoConsoleVariable<int32> CVarAllowPerObjectShadows(
	TEXT("r.Shadow.PerObject"),
	1,
	TEXT("Whether to render per object shadows (character casting on world)\n")
	TEXT("0: off\n")
	TEXT("1: on (default)"),
	ECVF_RenderThreadSafe

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

Scope (from outer to inner):

file
function     void FSceneRenderer::CreatePerObjectProjectedShadow

Source code excerpt:


		// Only create a shadow from this object if it hasn't completely faded away
		if (CVarAllowPerObjectShadows.GetValueOnRenderThread() && MaxFadeAlpha > 1.0f / 256.0f)
		{
			// Round down to the nearest power of two so that resolution changes are always doubling or halving the resolution, which increases filtering stability
			// Use the max resolution if the desired resolution is larger than that
			const int32 SizeX = MaxDesiredResolution >= MaxShadowResolution ? MaxShadowResolution : (1 << (FMath::CeilLogTwo(MaxDesiredResolution) - 1));

			if (bOpaque && bCreateOpaqueObjectShadow && (bOpaqueShadowIsVisibleThisFrame || bShadowIsPotentiallyVisibleNextFrame))