r.LumenScene.SurfaceCache.CardCaptureEnableInvalidation

r.LumenScene.SurfaceCache.CardCaptureEnableInvalidation

#Overview

name: r.LumenScene.SurfaceCache.CardCaptureEnableInvalidation

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.CardCaptureEnableInvalidation is to control the manual card recapture functionality in the Lumen Scene rendering system. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically the surface cache component.

This setting variable is primarily used in the Renderer module, particularly in the Lumen Scene rendering subsystem. Based on the callsites, it’s clear that this variable is utilized in the LumenSceneRendering.cpp file, which is a core part of the Lumen rendering pipeline.

The value of this variable is set through a console variable (TAutoConsoleVariable) with a default value of 1. This means that by default, manual card recapture through InvalidateSurfaceCacheForPrimitive() is enabled.

The associated variable CVarLumenSceneCardCaptureEnableInvalidation directly interacts with this setting. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable controls whether manual card recapture is allowed through the InvalidateSurfaceCacheForPrimitive() function. When set to 0, it will clear the PagesToRecaptureHeap for all GPU indices, effectively disabling the manual recapture functionality.

Best practices when using this variable include:

  1. Only disable it (set to 0) if you’re certain that manual card recapture is not needed in your specific use case.
  2. Be mindful of performance implications when enabling or disabling this feature, as it can affect the Lumen Scene rendering process.
  3. Use it in conjunction with other Lumen Scene settings for optimal performance and visual quality.

Regarding the associated variable CVarLumenSceneCardCaptureEnableInvalidation:

The purpose of CVarLumenSceneCardCaptureEnableInvalidation is to provide a programmatic way to access and modify the r.LumenScene.SurfaceCache.CardCaptureEnableInvalidation setting within the C++ code.

This variable is used in the Renderer module, specifically in the Lumen Scene rendering system. It’s accessed in the ProcessLumenSurfaceCacheRequests function of the FLumenSceneData class.

The value of this variable is set through the TAutoConsoleVariable declaration, which ties it to the r.LumenScene.SurfaceCache.CardCaptureEnableInvalidation console variable.

This variable directly controls the behavior of the manual card recapture functionality. When its value is 0, the PagesToRecaptureHeap is cleared for all GPU indices.

Developers should be aware that changes to this variable will immediately affect the Lumen Scene rendering process, potentially impacting performance and visual quality.

Best practices for using this variable include:

  1. Use GetValueOnRenderThread() when accessing the variable to ensure thread-safe operations.
  2. Consider the performance implications of enabling or disabling this feature in different scenarios.
  3. Use it in combination with other Lumen Scene settings for optimal results.

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarLumenSceneCardCaptureEnableInvalidation(
	TEXT("r.LumenScene.SurfaceCache.CardCaptureEnableInvalidation"),
	1,
	TEXT("Whether to enable manual card recapture through InvalidateSurfaceCacheForPrimitive().\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenSceneCardFixedDebugResolution = -1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarLumenSceneCardCaptureEnableInvalidation(
	TEXT("r.LumenScene.SurfaceCache.CardCaptureEnableInvalidation"),
	1,
	TEXT("Whether to enable manual card recapture through InvalidateSurfaceCacheForPrimitive().\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FLumenSceneData::ProcessLumenSurfaceCacheRequests

Source code excerpt:

		QUICK_SCOPE_CYCLE_COUNTER(SceneCardCaptureInvalidation);

		if (CVarLumenSceneCardCaptureEnableInvalidation.GetValueOnRenderThread() == 0)
		{
			for (uint32 GPUIndex = 0; GPUIndex < GNumExplicitGPUsForRendering; GPUIndex++)
			{
				PagesToRecaptureHeap[GPUIndex].Clear();
			}
		}