r.Shadow.UnbuiltPreviewInGame

r.Shadow.UnbuiltPreviewInGame

#Overview

name: r.Shadow.UnbuiltPreviewInGame

This variable is created as a Console Variable (cvar).

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.UnbuiltPreviewInGame is to control the rendering of unbuilt preview shadows in game. This setting is part of the rendering system, specifically related to shadow rendering.

This variable is primarily used in the Renderer and Engine modules of Unreal Engine 5. It affects the behavior of directional light components and how they handle shadow mapping.

The value of this variable is set in the URendererSettings class, which is part of the Engine’s configuration settings. It can be modified through the project settings or via console commands.

The associated variable GUnbuiltPreviewShadowsInGame interacts directly with r.Shadow.UnbuiltPreviewInGame. They share the same value and are used interchangeably in the code.

Developers should be aware that enabling this variable can lead to expensive preview shadows being rendered in-game when lighting is not built. This can have performance implications, especially in larger scenes or on lower-end hardware.

Best practices for using this variable include:

  1. Keeping it disabled for release builds to optimize performance.
  2. Using it during development to ensure lighting consistency between the editor and the game.
  3. Being mindful of its performance impact when enabled, especially in complex scenes.

Regarding the associated variable GUnbuiltPreviewShadowsInGame:

The purpose of GUnbuiltPreviewShadowsInGame is to serve as the internal representation of the r.Shadow.UnbuiltPreviewInGame console variable. It’s used directly in the rendering code to determine whether unbuilt preview shadows should be rendered in-game.

This variable is primarily used in the Renderer module, specifically in the SceneCore.cpp file. It affects the behavior of light-primitive interactions and how they handle shadow casting.

The value of GUnbuiltPreviewShadowsInGame is set through the console variable system, and it’s initialized to 1 (enabled) by default.

Developers should be aware that this variable directly impacts rendering performance and visual consistency between the editor and the game. When disabled, it can lead to visual discrepancies that might be mistaken for bugs.

Best practices for using GUnbuiltPreviewShadowsInGame include:

  1. Using it in conjunction with other debugging tools when investigating lighting issues.
  2. Considering its state when profiling game performance, especially in scenes with complex lighting.
  3. Ensuring it’s properly handled in any custom rendering code that deals with shadow casting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:759

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:


	UPROPERTY(config, EditAnywhere, Category=Optimizations, meta=(
		ConsoleVariable="r.Shadow.UnbuiltPreviewInGame",DisplayName="Render Unbuilt Preview Shadows in game",
		ToolTip="Whether to render unbuilt preview shadows in game.  When enabled and lighting is not built, expensive preview shadows will be rendered in game.  When disabled, lighting in game and editor won't match which can appear to be a bug."))
	uint32 bRenderUnbuiltPreviewShadowsInGame:1;

	UPROPERTY(config, EditAnywhere, Category=Optimizations, meta=(
		ConsoleVariable="r.StencilForLODDither",DisplayName="Use Stencil for LOD Dither Fading",
		ToolTip="Whether to use stencil for LOD dither fading.  This saves GPU time in the base pass for materials with dither fading enabled, but forces a full prepass. Changing this setting requires restarting the editor.",

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCore.cpp:22

Scope: file

Source code excerpt:

int32 GUnbuiltPreviewShadowsInGame = 1;
FAutoConsoleVariableRef CVarUnbuiltPreviewShadowsInGame(
	TEXT("r.Shadow.UnbuiltPreviewInGame"),
	GUnbuiltPreviewShadowsInGame,
	TEXT("Whether to render unbuilt preview shadows in game.  When enabled and lighting is not built, expensive preview shadows will be rendered in game.  When disabled, lighting in game and editor won't match which can appear to be a bug."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

/**

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

Scope (from outer to inner):

file
class        class FDirectionalLightSceneProxy : public FLightSceneProxy
function     uint32 GetNumShadowMappedCascades

Source code excerpt:

			EffectiveNumDynamicShadowCascades = FMath::Max(0, CVarUnbuiltNumWholeSceneDynamicShadowCascades.GetValueOnAnyThread());

			static const auto CVarUnbuiltPreviewShadowsInGame = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.UnbuiltPreviewInGame"));
			bool bUnbuiltPreviewShadowsInGame = CVarUnbuiltPreviewShadowsInGame->GetInt() != 0;

			if (!bUnbuiltPreviewShadowsInGame && !GetSceneInterface()->IsEditorScene())
			{
				EffectiveNumDynamicShadowCascades = 0;
			}

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCore.cpp:20

Scope: file

Source code excerpt:

#include "HAL/LowLevelMemTracker.h"

int32 GUnbuiltPreviewShadowsInGame = 1;
FAutoConsoleVariableRef CVarUnbuiltPreviewShadowsInGame(
	TEXT("r.Shadow.UnbuiltPreviewInGame"),
	GUnbuiltPreviewShadowsInGame,
	TEXT("Whether to render unbuilt preview shadows in game.  When enabled and lighting is not built, expensive preview shadows will be rendered in game.  When disabled, lighting in game and editor won't match which can appear to be a bug."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

/**
 * Fixed Size pool allocator for FLightPrimitiveInteractions

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCore.cpp:221

Scope (from outer to inner):

file
function     FLightPrimitiveInteraction::FLightPrimitiveInteraction

Source code excerpt:

			bUncachedStaticLighting = true;

			if (!GUnbuiltPreviewShadowsInGame && !InLightSceneInfo->Scene->IsEditorScene())
			{
				bCastShadow = false;
			}
	#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
			LightSceneInfo->NumUnbuiltInteractions++;
	#endif