r.Nanite.MaterialBuffers.Defrag.LowWaterMark

r.Nanite.MaterialBuffers.Defrag.LowWaterMark

#Overview

name: r.Nanite.MaterialBuffers.Defrag.LowWaterMark

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

• type: Var
• help: Ratio of used to allocated memory at which to decide to defrag the Nanite material data buffer.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Nanite.MaterialBuffers.Defrag.LowWaterMark is to control the defragmentation process of the Nanite material data buffer in Unreal Engine 5’s rendering system. Specifically, it sets the ratio of used to allocated memory at which the engine decides to defragment the Nanite material data buffer.

This setting variable is primarily used in the Nanite rendering system, which is part of Unreal Engine 5’s advanced geometry system. It’s utilized within the Renderer module, specifically in the Nanite materials scene extension.

The value of this variable is set as a console variable with a default value of 0.375f (37.5%). It can be modified at runtime through the console or configuration files.

The associated variable CVarNaniteMaterialBufferDefragLowWaterMark directly interacts with r.Nanite.MaterialBuffers.Defrag.LowWaterMark. They share the same value and purpose.

Developers should be aware that this variable affects the performance and memory management of Nanite-based materials. A lower value will trigger defragmentation more frequently, potentially improving memory usage but at the cost of more frequent defragmentation operations. A higher value will allow more fragmentation before triggering a defrag operation.

Best practices when using this variable include:

1. Monitor the performance impact of different values in your specific use case.
2. Balance between memory efficiency and the overhead of frequent defragmentation.
3. Consider adjusting this value if you notice issues with Nanite material performance or memory usage.

Regarding the associated variable CVarNaniteMaterialBufferDefragLowWaterMark:

The purpose of CVarNaniteMaterialBufferDefragLowWaterMark is identical to r.Nanite.MaterialBuffers.Defrag.LowWaterMark. It’s the internal representation of the console variable in the C++ code.

This variable is used in the Nanite rendering system, specifically in the material buffer defragmentation process.

The value is set when the console variable is initialized and can be accessed using the GetValueOnRenderThread() method.

It interacts directly with r.Nanite.MaterialBuffers.Defrag.LowWaterMark and is used in conjunction with other variables like CVarNaniteMaterialBufferDefrag and CVarNaniteMaterialDataBufferMinSizeBytes to control the defragmentation process.

Developers should be aware that this variable is used in render thread-safe operations and its value should only be accessed on the render thread.

Best practices include using GetValueOnRenderThread() to access the current value of the variable, and considering the impact of changes to this value on the overall Nanite material system performance.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarNaniteMaterialBufferDefragLowWaterMark(
	TEXT("r.Nanite.MaterialBuffers.Defrag.LowWaterMark"),
	0.375f,
	TEXT("Ratio of used to allocated memory at which to decide to defrag the Nanite material data buffer."),
	ECVF_RenderThreadSafe
);

BEGIN_SHADER_PARAMETER_STRUCT(FNaniteMaterialsParameters, RENDERER_API)

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarNaniteMaterialBufferDefragLowWaterMark(
	TEXT("r.Nanite.MaterialBuffers.Defrag.LowWaterMark"),
	0.375f,
	TEXT("Ratio of used to allocated memory at which to decide to defrag the Nanite material data buffer."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     bool FMaterialsSceneExtension::ProcessBufferDefragmentation

Source code excerpt:

	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();
	
	if (!bAllowDefrag)
	{