r.LumenScene.SurfaceCache.CardMaxTexelDensity

r.LumenScene.SurfaceCache.CardMaxTexelDensity

#Overview

name: r.LumenScene.SurfaceCache.CardMaxTexelDensity

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

• type: Var
• help: Lumen card texels per world space distance

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.CardMaxTexelDensity is to control the maximum texel density for Lumen cards in the scene surface cache. This setting variable is part of the Lumen global illumination system in Unreal Engine 5’s rendering subsystem.

This setting variable is primarily used in the Lumen scene rendering module, which is part of the Renderer subsystem in Unreal Engine 5. It specifically affects the surface cache, which is a crucial component of Lumen’s real-time global illumination system.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as a float with an initial value of 0.2f, representing the maximum number of Lumen card texels per world space distance.

The associated variable GLumenSceneCardMaxTexelDensity directly interacts with r.LumenScene.SurfaceCache.CardMaxTexelDensity. They share the same value, with GLumenSceneCardMaxTexelDensity being the C++ variable that stores the console variable’s value.

Developers must be aware that this variable affects the quality and performance of Lumen’s global illumination. A higher value will result in higher quality lighting at the cost of increased memory usage and potentially lower performance. Conversely, a lower value will reduce quality but improve performance.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your project, balancing between visual quality and performance.
2. Testing different values to find the optimal setting for your scene.
3. Considering scalability options, as this variable is marked with ECVF_Scalability flag.
4. Being mindful of its impact on memory usage, especially on platforms with limited resources.

Regarding the associated variable GLumenSceneCardMaxTexelDensity:

The purpose of GLumenSceneCardMaxTexelDensity is to store the value of r.LumenScene.SurfaceCache.CardMaxTexelDensity for use in C++ code.

It’s used in the Lumen scene rendering module, specifically in the FLumenSurfaceCacheUpdateMeshCardsTask and within the AnyThreadTask function.

The value is set by the console variable system and can be modified at runtime.

This variable directly interacts with r.LumenScene.SurfaceCache.CardMaxTexelDensity, serving as its C++ representation.

Developers should be aware that modifying GLumenSceneCardMaxTexelDensity directly in code will not persist changes, as it’s controlled by the console variable system.

Best practices include using the console variable system to modify this value rather than changing it directly in code, and considering its impact on Lumen card resolution calculations.

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

Scope: file

Source code excerpt:

float GLumenSceneCardMaxTexelDensity = .2f;
FAutoConsoleVariableRef CVarLumenSceneCardMaxTexelDensity(
	TEXT("r.LumenScene.SurfaceCache.CardMaxTexelDensity"),
	GLumenSceneCardMaxTexelDensity,
	TEXT("Lumen card texels per world space distance"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneCardMaxResolution = 512;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

float GLumenSceneCardMaxTexelDensity = .2f;
FAutoConsoleVariableRef CVarLumenSceneCardMaxTexelDensity(
	TEXT("r.LumenScene.SurfaceCache.CardMaxTexelDensity"),
	GLumenSceneCardMaxTexelDensity,
	TEXT("Lumen card texels per world space distance"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneCardMaxResolution = 512;
FAutoConsoleVariableRef CVarLumenSceneCardMaxResolution(

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

Scope (from outer to inner):

file
function     FLumenSurfaceCacheUpdateMeshCardsTask

Source code excerpt:

		, MaxDistanceFromCamera(InMaxDistanceFromCamera)
		, TexelDensityScale(LumenScene::GetCardTexelDensity() * InSurfaceCacheResolution)
		, MaxTexelDensity(GLumenSceneCardMaxTexelDensity)
		, MinCardResolution(FMath::Clamp(FMath::RoundToInt(LumenScene::GetCardMinResolution(bInOrthographicCamera) / LumenSceneDetail), 1, 1024))
		, FarFieldCardMaxDistance(LumenScene::GetFarFieldCardMaxDistance())
		, FarFieldCardTexelDensity(LumenScene::GetFarFieldCardTexelDensity())
	{
	}

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

Scope (from outer to inner):

file
function     void AnyThreadTask

Source code excerpt:

					// Compute resolution based on its largest extent
					float MaxExtent = FMath::Max(LumenCard.WorldOBB.Extent.X, LumenCard.WorldOBB.Extent.Y);
					float MaxProjectedSize = FMath::Min(TexelDensityScale * MaxExtent * LumenCard.ResolutionScale / ViewerDistance, GLumenSceneCardMaxTexelDensity * MaxExtent);

					// Far field cards have constant resolution over entire range
					if (MeshCardsInstance.bFarField)
					{
						CardMaxDistance = FarFieldCardMaxDistance;
						MaxProjectedSize = FarFieldCardTexelDensity * MaxExtent * LumenCard.ResolutionScale;