r.LumenScene.SurfaceCache.MeshCardsMergedResolutionScale

r.LumenScene.SurfaceCache.MeshCardsMergedResolutionScale

#Overview

name: r.LumenScene.SurfaceCache.MeshCardsMergedResolutionScale

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.MeshCardsMergedResolutionScale is to control the resolution scale for merged MeshCards in the Lumen rendering system. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically affecting the surface cache for mesh cards.

This setting variable is primarily used in the Lumen rendering subsystem, which is part of Unreal Engine 5’s advanced lighting and global illumination features. It’s referenced in the Renderer module, particularly in the Lumen-related source files.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 0.3f and can be adjusted at runtime.

The associated variable GLumenMeshCardsMergedResolutionScale directly interacts with this console variable. They share the same value, with GLumenMeshCardsMergedResolutionScale being the actual variable used in the rendering code.

Developers must be aware that this variable affects the resolution calculation for merged MeshCards. It’s used to compensate for the merged box getting a higher resolution assigned due to being closer to the viewer. Changing this value will impact the visual quality and performance of the Lumen global illumination system.

Best practices when using this variable include:

  1. Carefully adjusting the value to balance between visual quality and performance.
  2. Testing the impact of changes in various lighting scenarios and environments.
  3. Considering the interaction with other Lumen-related settings for optimal results.

Regarding the associated variable GLumenMeshCardsMergedResolutionScale:

The purpose of GLumenMeshCardsMergedResolutionScale is to store and provide the actual value used in the Lumen rendering calculations for merged MeshCards resolution scaling.

This variable is used directly in the Lumen rendering subsystem, specifically in the UpdateLumenScenePrimitives function within the LumenScene.cpp file.

Its value is set by the r.LumenScene.SurfaceCache.MeshCardsMergedResolutionScale console variable.

GLumenMeshCardsMergedResolutionScale interacts closely with other Lumen scene primitives and is used in calculations involving surface area ratios and card resolution scaling.

Developers should be aware that modifying this variable directly in the code is not recommended, as it’s meant to be controlled via the console variable system.

Best practices for this variable include accessing it only through the established console variable system and avoiding direct manipulation in the source code to maintain consistency and proper functionality of the Lumen system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenMeshCards.cpp:69

Scope: file

Source code excerpt:

float GLumenMeshCardsMergedResolutionScale = .3f;
FAutoConsoleVariableRef CVarLumenMeshCardsMergedResolutionScale(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergedResolutionScale"),
	GLumenMeshCardsMergedResolutionScale,
	TEXT("Scale on the resolution calculation for a merged MeshCards.  This compensates for the merged box getting a higher resolution assigned due to being closer to the viewer."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenMeshCards.cpp:67

Scope: file

Source code excerpt:

);

float GLumenMeshCardsMergedResolutionScale = .3f;
FAutoConsoleVariableRef CVarLumenMeshCardsMergedResolutionScale(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergedResolutionScale"),
	GLumenMeshCardsMergedResolutionScale,
	TEXT("Scale on the resolution calculation for a merged MeshCards.  This compensates for the merged box getting a higher resolution assigned due to being closer to the viewer."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_Scalability | ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:934

Scope (from outer to inner):

file
function     void UpdateLumenScenePrimitives

Source code excerpt:


							extern float GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio;
							extern float GLumenMeshCardsMergedResolutionScale;

							if (SurfaceAreaRatio < GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio)
							{
								const int32 PrimitiveGroupIndex = LumenSceneData->PrimitiveGroups.AddSpan(1);
								ScenePrimitiveInfo->LumenPrimitiveGroupIndices.Add(PrimitiveGroupIndex);
								LumenSceneData->PrimitiveGroupIndicesToUpdateInBuffer.Add(PrimitiveGroupIndex);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:944

Scope (from outer to inner):

file
function     void UpdateLumenScenePrimitives

Source code excerpt:

								FLumenPrimitiveGroup& PrimitiveGroup = LumenSceneData->PrimitiveGroups[PrimitiveGroupIndex];
								PrimitiveGroup.PrimitiveInstanceIndex = -1;
								PrimitiveGroup.CardResolutionScale = FMath::Sqrt(1.0f / SurfaceAreaRatio) * GLumenMeshCardsMergedResolutionScale;
								PrimitiveGroup.WorldSpaceBoundingBox = PrimitiveRelativeBounds.ToBox().ShiftBy(InstanceData->GetPrimitiveWorldSpaceOffset());
								PrimitiveGroup.MeshCardsIndex = -1;
								PrimitiveGroup.HeightfieldIndex = -1;
								PrimitiveGroup.bValidMeshCards = true;
								PrimitiveGroup.bFarField = SceneProxy->IsRayTracingFarField();
								PrimitiveGroup.bHeightfield = false;