r.Water.WaterMesh.PreAllocStagingInstanceMemory

r.Water.WaterMesh.PreAllocStagingInstanceMemory

#Overview

name: r.Water.WaterMesh.PreAllocStagingInstanceMemory

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

• type: Var
• help: Pre-allocates staging instance data memory according to historical max. This reduces the overhead when the array needs to grow but may use more memory

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Water.WaterMesh.PreAllocStagingInstanceMemory is to control memory allocation for water mesh instances in the Unreal Engine 5 rendering system. Specifically, it determines whether to pre-allocate staging instance data memory based on historical maximum usage.

This setting variable is used in the Water plugin, which is part of the Unreal Engine’s rendering system. It’s primarily utilized within the WaterMeshSceneProxy class, which handles the rendering of water meshes.

The value of this variable is set through a console variable (CVar) system. It’s defined with a default value of 0, meaning pre-allocation is disabled by default.

The associated variable CVarWaterMeshPreAllocStagingInstanceMemory directly interacts with r.Water.WaterMesh.PreAllocStagingInstanceMemory. They share the same value and purpose.

Developers must be aware that enabling this variable (setting it to a non-zero value) will pre-allocate memory based on the historical maximum instance count. This can reduce overhead when the array needs to grow, but it may also use more memory than necessary if the current instance count is significantly lower than the historical maximum.

Best practices when using this variable include:

1. Enable it (set to 1) if you’re experiencing performance issues related to frequent resizing of the instance data array.
2. Monitor memory usage when enabled, as it may lead to higher memory consumption.
3. Consider disabling it (set to 0) if memory usage is a concern and the performance gain is negligible.
4. Use in conjunction with profiling tools to determine the optimal setting for your specific use case.

Regarding the associated variable CVarWaterMeshPreAllocStagingInstanceMemory:

This is the actual console variable that controls the behavior described above. It’s used in the same way as r.Water.WaterMesh.PreAllocStagingInstanceMemory, with the same considerations and best practices applying to both. The variable is checked in the GetDynamicMeshElements function of the FWaterMeshSceneProxy class to determine whether to pre-allocate memory for the StagingInstanceData array.

Developers should be aware that changes to this variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag used in its declaration.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterMeshSceneProxy.cpp:128

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarWaterMeshPreAllocStagingInstanceMemory(
	TEXT("r.Water.WaterMesh.PreAllocStagingInstanceMemory"),
	0,
	TEXT("Pre-allocates staging instance data memory according to historical max. This reduces the overhead when the array needs to grow but may use more memory"),
	ECVF_RenderThreadSafe);

#if RHI_RAYTRACING
static TAutoConsoleVariable<int32> CVarRayTracingGeometryWater(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterMeshSceneProxy.cpp:127

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarWaterMeshPreAllocStagingInstanceMemory(
	TEXT("r.Water.WaterMesh.PreAllocStagingInstanceMemory"),
	0,
	TEXT("Pre-allocates staging instance data memory according to historical max. This reduces the overhead when the array needs to grow but may use more memory"),
	ECVF_RenderThreadSafe);

#if RHI_RAYTRACING

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterMeshSceneProxy.cpp:653

Scope (from outer to inner):

file
function     void FWaterMeshSceneProxy::GetDynamicMeshElements

Source code excerpt:

			WaterInstanceData.BucketInstanceCounts.Empty(NumBuckets);
			WaterInstanceData.BucketInstanceCounts.AddZeroed(NumBuckets);
			if (!!CVarWaterMeshPreAllocStagingInstanceMemory.GetValueOnRenderThread())
			{
				WaterInstanceData.StagingInstanceData.Empty(HistoricalMaxViewInstanceCount);
			}

			FWaterQuadTree::FTraversalDesc TraversalDesc;
			TraversalDesc.LowestLOD = WaterLODParams.LowestLOD;