r.VT.RVT.DirtyPagesKeptMappedFrames

r.VT.RVT.DirtyPagesKeptMappedFrames

#Overview

name: r.VT.RVT.DirtyPagesKeptMappedFrames

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.VT.RVT.DirtyPagesKeptMappedFrames is to control the behavior of Runtime Virtual Texture (RVT) page invalidation in Unreal Engine 5’s rendering system. Specifically, it determines how long dirty pages are kept mapped after they have provided feedback.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically in the Runtime Virtual Texture (RVT) subsystem. It’s referenced in the RuntimeVirtualTextureSceneProxy.cpp file, which suggests it’s closely tied to the management of virtual textures in the scene.

The value of this variable is set through a console variable (CVarDirtyPagesKeptMappedFrames) with a default value of 8. This means that by default, dirty pages are kept mapped if they provided feedback in the last 8 frames.

The associated variable CVarDirtyPagesKeptMappedFrames directly interacts with r.VT.RVT.DirtyPagesKeptMappedFrames. They share the same value and purpose.

Developers should be aware that this variable affects the trade-off between update flicker and performance. Keeping dirty pages mapped for longer can reduce update flicker due to the latency in the unmap/feedback/map sequence. However, it may also create more page update work since more pages may get updated.

Best practices when using this variable include:

  1. Adjusting the value based on the specific needs of the project. A higher value might be beneficial for scenes with rapidly changing virtual textures to reduce flickering, while a lower value might be preferred for performance-critical scenarios.
  2. Monitoring performance metrics when changing this value, as it can impact the workload of the virtual texturing system.
  3. Using this in conjunction with other virtual texturing settings for optimal results.

Regarding the associated variable CVarDirtyPagesKeptMappedFrames:

The purpose of CVarDirtyPagesKeptMappedFrames is identical to r.VT.RVT.DirtyPagesKeptMappedFrames. It’s the actual console variable that controls the behavior described above.

This variable is used in the Renderer module, specifically in the Runtime Virtual Texture system. It’s accessed in the FlushDirtyPages function of the FRuntimeVirtualTextureSceneProxy class.

The value is set when the console variable is initialized, with a default value of 8. It can be changed at runtime through console commands.

CVarDirtyPagesKeptMappedFrames directly determines the MaxAgeToKeepMapped value used in the page flushing logic.

Developers should be aware that this variable is marked as ECVF_RenderThreadSafe, meaning it can be safely accessed from the render thread.

Best practices for using CVarDirtyPagesKeptMappedFrames include:

  1. Using the GetValueOnRenderThread() method to access its value, as shown in the code snippet.
  2. Considering the impact on both visual quality (flickering) and performance when adjusting this value.
  3. Testing different values in various scenarios to find the optimal setting for your specific use case.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/RuntimeVirtualTextureSceneProxy.cpp:26

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarDirtyPagesKeptMappedFrames(
	TEXT("r.VT.RVT.DirtyPagesKeptMappedFrames"),
	8,
	TEXT("When invalidating RVT pages, we keep them mapped if they gave feedback in the last N frames."),
	ECVF_RenderThreadSafe);

int32 FRuntimeVirtualTextureSceneProxy::ProducerIdGenerator = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/RuntimeVirtualTextureSceneProxy.cpp:25

Scope: file

Source code excerpt:

	ECVF_Default);

static TAutoConsoleVariable<int32> CVarDirtyPagesKeptMappedFrames(
	TEXT("r.VT.RVT.DirtyPagesKeptMappedFrames"),
	8,
	TEXT("When invalidating RVT pages, we keep them mapped if they gave feedback in the last N frames."),
	ECVF_RenderThreadSafe);

int32 FRuntimeVirtualTextureSceneProxy::ProducerIdGenerator = 1;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/RuntimeVirtualTextureSceneProxy.cpp:205

Scope (from outer to inner):

file
function     void FRuntimeVirtualTextureSceneProxy::FlushDirtyPages

Source code excerpt:

			// Keeping visible pages mapped reduces update flicker due to the latency in the unmap/feedback/map sequence.
			// But it potentially creates more page update work since more pages may get updated.
			const uint32 MaxAgeToKeepMapped = CVarDirtyPagesKeptMappedFrames.GetValueOnRenderThread();

			//todo[vt]: 
			// Profile to work out best heuristic for when we should use the CombinedDirtyRect
			// Also consider using some other structure to represent dirty area such as a course 2D bitfield
			const bool bCombinedFlush = (DirtyRects.Num() > 2 || CombinedDirtyRect == FIntRect(0, 0, VirtualTextureSize.X, VirtualTextureSize.Y));