r.Nanite.MaterialBuffers.Defrag

r.Nanite.MaterialBuffers.Defrag

#Overview

name: r.Nanite.MaterialBuffers.Defrag

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.Nanite.MaterialBuffers.Defrag is to control whether defragmentation of the Nanite material data buffer is allowed. This setting is part of Unreal Engine 5’s Nanite virtualized geometry system, specifically related to the management of material data buffers.

This setting variable is primarily used in the Renderer subsystem of Unreal Engine 5, particularly within the Nanite rendering module. It’s implemented in the NaniteMaterialsSceneExtension.cpp file, which suggests it’s part of the scene extension mechanism for Nanite materials.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of true, meaning defragmentation is allowed by default. Developers can change this setting at runtime using console commands or through configuration files.

The associated variable CVarNaniteMaterialBufferDefrag directly interacts with r.Nanite.MaterialBuffers.Defrag. They share the same value and purpose, with CVarNaniteMaterialBufferDefrag being the actual C++ variable that stores and provides access to the setting’s value.

Developers should be aware that this variable affects the performance and memory management of Nanite material buffers. Enabling defragmentation (the default setting) allows the engine to optimize the use of memory for Nanite material data, potentially improving performance and reducing memory fragmentation.

Best practices when using this variable include:

  1. Leave it enabled (true) unless specific performance issues are observed.
  2. If disabling it, carefully monitor performance and memory usage of Nanite materials.
  3. Consider the impact on different hardware configurations, as the benefits of defragmentation may vary.

Regarding the associated variable CVarNaniteMaterialBufferDefrag:

The purpose of CVarNaniteMaterialBufferDefrag is to provide programmatic access to the r.Nanite.MaterialBuffers.Defrag setting within the engine’s C++ code. It’s implemented as a TAutoConsoleVariable, which is a type-safe wrapper for console variables in Unreal Engine.

This variable is used in the Renderer subsystem, specifically in the Nanite materials scene extension. It’s accessed in the ProcessBufferDefragmentation function, indicating its role in the actual defragmentation process.

The value of CVarNaniteMaterialBufferDefrag is set when the r.Nanite.MaterialBuffers.Defrag console variable is modified. It can be accessed in C++ code using the GetValueOnRenderThread() method, which ensures thread-safe access to the value.

Other variables that interact with CVarNaniteMaterialBufferDefrag include CVarNaniteMaterialDataBufferMinSizeBytes and CVarNaniteMaterialBufferDefragLowWaterMark, which are used in conjunction to determine when and how defragmentation occurs.

Developers should be aware that accessing this variable should be done on the render thread for thread safety. The ECVF_RenderThreadSafe flag ensures that changes to this variable are properly synchronized with the render thread.

Best practices for using CVarNaniteMaterialBufferDefrag include:

  1. Always access its value using GetValueOnRenderThread() in render thread code.
  2. Consider caching the value if it’s accessed frequently in performance-critical sections.
  3. Be aware of its interaction with other Nanite material buffer-related variables when modifying buffer management logic.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteMaterialsSceneExtension.cpp:36

Scope: file

Source code excerpt:


static TAutoConsoleVariable<bool> CVarNaniteMaterialBufferDefrag(
	TEXT("r.Nanite.MaterialBuffers.Defrag"),
	true,
	TEXT("Whether or not to allow defragmentation of the Nanite material data buffer."),
	ECVF_RenderThreadSafe
);

static int32 GNaniteMaterialBufferForceDefrag = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteMaterialsSceneExtension.cpp:35

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<bool> CVarNaniteMaterialBufferDefrag(
	TEXT("r.Nanite.MaterialBuffers.Defrag"),
	true,
	TEXT("Whether or not to allow defragmentation of the Nanite material data buffer."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteMaterialsSceneExtension.cpp:226

Scope (from outer to inner):

file
function     bool FMaterialsSceneExtension::ProcessBufferDefragmentation

Source code excerpt:

	//	  could be implemented in a more efficient manner if the current method proves expensive.

	const bool bAllowDefrag = CVarNaniteMaterialBufferDefrag.GetValueOnRenderThread();
	static const int32 MinMaterialBufferSizeDwords = CVarNaniteMaterialDataBufferMinSizeBytes.GetValueOnRenderThread() / 4;
	const float LowWaterMarkRatio = CVarNaniteMaterialBufferDefragLowWaterMark.GetValueOnRenderThread();
	const int32 EffectiveMaxSize = FMath::RoundUpToPowerOfTwo(MaterialBufferAllocator.GetMaxSize());
	const int32 LowWaterMark = uint32(EffectiveMaxSize * LowWaterMarkRatio);
	const int32 UsedSize = MaterialBufferAllocator.GetSparselyAllocatedSize();