r.LumenScene.SurfaceCache.MeshCardsCullFaces

r.LumenScene.SurfaceCache.MeshCardsCullFaces

#Overview

name: r.LumenScene.SurfaceCache.MeshCardsCullFaces

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

• type: Var
• help: ``

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.MeshCardsCullFaces is to control the culling of mesh card faces in the Lumen global illumination system of Unreal Engine 5. This setting is specifically related to the rendering system, particularly the Lumen scene surface cache.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. It’s referenced in the LumenMeshCards.cpp file, which is part of the Renderer module.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 1 (enabled) and can be changed at runtime.

The associated variable GLumenMeshCardsCullFaces directly interacts with r.LumenScene.SurfaceCache.MeshCardsCullFaces. They share the same value, with GLumenMeshCardsCullFaces being the actual int32 variable used in the code logic.

Developers must be aware that changing this variable triggers a recreation of the global component render state. This is evident from the console variable delegate that creates an FGlobalComponentRecreateRenderStateContext when the value changes.

Best practices when using this variable include:

1. Understanding its impact on performance and visual quality. Enabling face culling (value 1) may improve performance but could potentially affect visual quality in some scenarios.
2. Testing thoroughly when changing this value, as it affects the global illumination system.
3. Being cautious when changing it at runtime, as it triggers a render state recreation which could cause a momentary performance hitch.

Regarding the associated variable GLumenMeshCardsCullFaces:

The purpose of GLumenMeshCardsCullFaces is to serve as the actual runtime variable that controls mesh card face culling in the Lumen system. It’s used directly in the rendering code to determine whether to cull mesh card faces.

This variable is used in the Lumen subsystem of the rendering module, specifically in the mesh card culling logic.

Its value is set by the console variable system through r.LumenScene.SurfaceCache.MeshCardsCullFaces.

It interacts directly with the MinFaceSurfaceArea variable in the mesh card cull test function. When GLumenMeshCardsCullFaces is true (1), mesh cards with a surface area below MinFaceSurfaceArea are culled.

Developers should be aware that this variable directly affects the culling behavior of mesh cards in the Lumen system. When it’s set to 0, no culling occurs regardless of the mesh card’s surface area.

Best practices include carefully balancing performance gains from culling with potential visual impacts, and thoroughly testing different scenarios when adjusting this value.

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

Scope: file

Source code excerpt:

int32 GLumenMeshCardsCullFaces = 1;
FAutoConsoleVariableRef CVarLumenMeshCardsCullFaces(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsCullFaces"),
	GLumenMeshCardsCullFaces,
	TEXT(""),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenMeshCardsCullFaces = 1;
FAutoConsoleVariableRef CVarLumenMeshCardsCullFaces(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsCullFaces"),
	GLumenMeshCardsCullFaces,
	TEXT(""),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_Scalability | ECVF_RenderThreadSafe

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

Scope (from outer to inner):

file
function     bool MeshCardCullTest

Source code excerpt:

	const FVector3f ScaledBoundsSize = 2.0f * CardBuildData.OBB.Extent * LocalToWorldScale;
	const float SurfaceArea = ScaledBoundsSize.X * ScaledBoundsSize.Y;
	const bool bCardPassedCulling = (!GLumenMeshCardsCullFaces || SurfaceArea > MinFaceSurfaceArea);

	return bCardPassedCulling;
}

void FLumenSceneData::AddMeshCardsFromBuildData(int32 PrimitiveGroupIndex, const FMatrix& LocalToWorld, const FMeshCardsBuildData& MeshCardsBuildData, FLumenPrimitiveGroup& PrimitiveGroup)
{