r.Vulkan.DSetCacheMaxPoolLookups

r.Vulkan.DSetCacheMaxPoolLookups

#Overview

name: r.Vulkan.DSetCacheMaxPoolLookups

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

• type: Var
• help: Maximum count of pool\'s caches to lookup before allocating new descriptor.\n

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Vulkan.DSetCacheMaxPoolLookups is to control the maximum number of descriptor set pool caches to search before allocating a new descriptor in the Vulkan rendering system of Unreal Engine 5.

This setting variable is primarily used in the Vulkan RHI (Rendering Hardware Interface) subsystem of Unreal Engine 5. It specifically affects the descriptor set caching mechanism, which is crucial for efficient management of Vulkan descriptors.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as a read-only, render thread-safe variable, which means it can be set at startup or through configuration files, but not changed at runtime.

The associated variable GDSetCacheMaxPoolLookups directly interacts with r.Vulkan.DSetCacheMaxPoolLookups. They share the same value, with GDSetCacheMaxPoolLookups being the actual integer variable used in the code.

Developers must be aware that this variable affects the performance and memory usage of the Vulkan renderer. A higher value may improve the chances of finding an existing descriptor set but could also increase lookup times. A lower value might lead to more frequent allocations of new descriptors.

Best practices when using this variable include:

1. Carefully tuning it based on the specific needs of your project and target hardware.
2. Monitoring performance metrics to find the optimal balance between descriptor reuse and lookup time.
3. Considering it in conjunction with other Vulkan-related settings for holistic optimization.

Regarding the associated variable GDSetCacheMaxPoolLookups:

• It’s the actual integer variable used in the Vulkan RHI code to control the number of pool lookups.
• It’s used in the FVulkanDescriptorSetCache::GetDescriptorSets function to limit the number of cached pools to search.
• It’s also used in the FVulkanDescriptorSetCache::GC function to determine when to perform garbage collection on cached pools.
• Developers should treat it as equivalent to r.Vulkan.DSetCacheMaxPoolLookups in terms of its effect on the system.

When working with this variable, developers should consider the trade-offs between descriptor set reuse (which can improve performance) and the overhead of searching multiple pools (which can decrease performance if set too high).

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPendingState.cpp:590

Scope: file

Source code excerpt:

int32 GDSetCacheMaxPoolLookups = 2;
FAutoConsoleVariableRef CVarDSetCacheMaxPoolLookups(
	TEXT("r.Vulkan.DSetCacheMaxPoolLookups"),
	GDSetCacheMaxPoolLookups,
	TEXT("Maximum count of pool's caches to lookup before allocating new descriptor.\n"),
	ECVF_ReadOnly | ECVF_RenderThreadSafe
);

const float DefaultPoolSizes[VK_DESCRIPTOR_TYPE_RANGE_SIZE] = 

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPendingState.cpp:588

Scope: file

Source code excerpt:

);

int32 GDSetCacheMaxPoolLookups = 2;
FAutoConsoleVariableRef CVarDSetCacheMaxPoolLookups(
	TEXT("r.Vulkan.DSetCacheMaxPoolLookups"),
	GDSetCacheMaxPoolLookups,
	TEXT("Maximum count of pool's caches to lookup before allocating new descriptor.\n"),
	ECVF_ReadOnly | ECVF_RenderThreadSafe
);

const float DefaultPoolSizes[VK_DESCRIPTOR_TYPE_RANGE_SIZE] = 
{

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPendingState.cpp:726

Scope (from outer to inner):

file
function     void FVulkanDescriptorSetCache::GetDescriptorSets

Source code excerpt:

	check(CachedPools.Num() > 0);

	for (int32 Index = 0; (Index < GDSetCacheMaxPoolLookups) && (Index < CachedPools.Num()); ++Index)
	{
		if (CachedPools[Index]->FindDescriptorSets(DSetsKey, OutSets))
		{
			return;
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPendingState.cpp:747

Scope (from outer to inner):

file
function     void FVulkanDescriptorSetCache::GC

Source code excerpt:

{
	// Loop is for OOM safety. Normally there would be at most 1 loop.
	while ((CachedPools.Num() > GDSetCacheMaxPoolLookups) && CachedPools.Last()->CanGC())
	{
		const uint32 RemoveIndex = (CachedPools.Num() - 1);
		if (FreePool)
		{
			UE_LOG(LogVulkanRHI, Warning, TEXT("FVulkanDescriptorSetCache::GC() Free Pool is not empty! Too small r.Vulkan.DSetCacheTargetSetsPerPool?"));
		}