r.LumenScene.SurfaceCache.CardFixedDebugResolution

r.LumenScene.SurfaceCache.CardFixedDebugResolution

#Overview

name: r.LumenScene.SurfaceCache.CardFixedDebugResolution

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

• type: Var
• help: Lumen card resolution

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.CardFixedDebugResolution is to control the Lumen card resolution in Unreal Engine 5’s rendering system. This setting variable is specifically used for debugging purposes within the Lumen scene rendering subsystem.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the Lumen scene rendering subsystem. Based on the callsites, it’s clear that this variable is utilized in the LumenSceneRendering.cpp file, which is part of the Lumen global illumination system.

The value of this variable is set through the Unreal Engine console variable system. It’s declared as an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files.

The associated variable GLumenSceneCardFixedDebugResolution directly interacts with this console variable. They share the same value, with GLumenSceneCardFixedDebugResolution being the C++ variable that’s actually used in the code logic.

Developers must be aware that this variable is intended for debugging purposes. It’s marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating that it affects scalability and is safe to modify from the render thread.

Best practices when using this variable include:

1. Only use it for debugging purposes, not in production code.
2. Be aware that changing this value may impact performance, as it directly affects the resolution of Lumen cards.
3. Use it in conjunction with other Lumen debugging tools for a comprehensive understanding of the scene rendering.

Regarding the associated variable GLumenSceneCardFixedDebugResolution:

The purpose of GLumenSceneCardFixedDebugResolution is to store the value set by r.LumenScene.SurfaceCache.CardFixedDebugResolution for use in the actual rendering code.

This variable is used within the Lumen scene rendering system, specifically in the calculation of the maximum projected size for Lumen cards.

The value of this variable is set by the console variable system when r.LumenScene.SurfaceCache.CardFixedDebugResolution is modified.

It interacts directly with the logic that determines the size of Lumen cards. When GLumenSceneCardFixedDebugResolution is greater than 0, it overrides the calculated MaxProjectedSize for the cards.

Developers should be aware that this variable has a default value of -1, which means it’s not active by default. When it’s set to a positive value, it will override the normal card size calculation logic.

Best practices for using this variable include:

1. Use it temporarily for debugging purposes only.
2. Reset it to -1 when not actively debugging to ensure normal Lumen card sizing behavior.
3. Be cautious when setting very large values, as it could significantly impact performance and memory usage.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

float GLumenSceneCardFixedDebugResolution = -1;
FAutoConsoleVariableRef CVarLumenSceneCardFixedDebugResolution(
	TEXT("r.LumenScene.SurfaceCache.CardFixedDebugResolution"),
	GLumenSceneCardFixedDebugResolution,
	TEXT("Lumen card resolution"),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GLumenSceneCardMaxTexelDensity = .2f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneRendering.cpp:127

Scope: file

Source code excerpt:

);

float GLumenSceneCardFixedDebugResolution = -1;
FAutoConsoleVariableRef CVarLumenSceneCardFixedDebugResolution(
	TEXT("r.LumenScene.SurfaceCache.CardFixedDebugResolution"),
	GLumenSceneCardFixedDebugResolution,
	TEXT("Lumen card resolution"),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GLumenSceneCardMaxTexelDensity = .2f;
FAutoConsoleVariableRef CVarLumenSceneCardMaxTexelDensity(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneRendering.cpp:500

Scope (from outer to inner):

file
function     void AnyThreadTask

Source code excerpt:

					}

					if (GLumenSceneCardFixedDebugResolution > 0)
					{
						MaxProjectedSize = GLumenSceneCardFixedDebugResolution;
					}

					const int32 MinCardResolutionForMeshCards = MeshCardsInstance.bEmissiveLightSource ? 1 : MinCardResolution;
					const int32 MaxSnappedRes = FMath::RoundUpToPowerOfTwo(FMath::Min(FMath::TruncToInt(MaxProjectedSize), GetCardMaxResolution()));
					const bool bVisible = ViewerDistance < CardMaxDistance && MaxSnappedRes >= MinCardResolutionForMeshCards;
					const int32 ResLevel = FMath::FloorLog2(FMath::Max<uint32>(MaxSnappedRes, Lumen::MinCardResolution));