r.DistanceFields.TextureUploadLimitKBytes

r.DistanceFields.TextureUploadLimitKBytes

#Overview

name: r.DistanceFields.TextureUploadLimitKBytes

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

• type: Var
• help: Max KB of distance field texture data to upload per frame from streaming requests.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields.TextureUploadLimitKBytes is to control the maximum amount of distance field texture data that can be uploaded per frame from streaming requests in the Unreal Engine rendering system.

This setting variable is primarily used by the Renderer module of Unreal Engine, specifically in the distance field streaming subsystem. It’s part of the rendering pipeline that handles distance field textures, which are used for various rendering effects such as global illumination and ambient occlusion.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 8192 KB (8 MB) but can be changed at runtime through console commands or configuration files.

The associated variable CVarTextureUploadLimitKBytes directly interacts with r.DistanceFields.TextureUploadLimitKBytes. They share the same value and purpose.

Developers must be aware that this variable affects performance and memory usage. Setting it too high might cause frame rate drops due to excessive texture uploads, while setting it too low might result in slower loading of distance field textures.

Best practices when using this variable include:

1. Monitoring performance impact when adjusting the value.
2. Balancing between smooth texture streaming and maintaining frame rate.
3. Considering the target hardware capabilities when setting this value.
4. Using profiling tools to determine the optimal value for your specific use case.

Regarding the associated variable CVarTextureUploadLimitKBytes:

The purpose of CVarTextureUploadLimitKBytes is identical to r.DistanceFields.TextureUploadLimitKBytes. It’s the actual console variable that controls the setting.

This variable is used in the Renderer module, specifically in the DistanceFieldStreaming.cpp file. It’s accessed in the ProcessReadRequests function of the FDistanceFieldSceneData class to determine the maximum amount of texture data to upload per frame.

The value is set when the console variable is initialized and can be changed at runtime using console commands.

CVarTextureUploadLimitKBytes directly interacts with r.DistanceFields.TextureUploadLimitKBytes, as they represent the same setting.

Developers should be aware that this variable is accessed on the render thread, so any changes to it should be thread-safe.

Best practices for using CVarTextureUploadLimitKBytes include:

1. Using the appropriate console commands or configuration settings to modify its value.
2. Ensuring any runtime changes are made in a thread-safe manner.
3. Considering the impact on both texture streaming performance and overall frame rate when adjusting the value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:41

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarTextureUploadLimitKBytes(
	TEXT("r.DistanceFields.TextureUploadLimitKBytes"),
	8192,	
	TEXT("Max KB of distance field texture data to upload per frame from streaming requests."),
	ECVF_RenderThreadSafe);

int32 GDistanceFieldOffsetDataStructure = 0;
static FAutoConsoleVariableRef CVarShadowOffsetDataStructure(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:40

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarTextureUploadLimitKBytes(
	TEXT("r.DistanceFields.TextureUploadLimitKBytes"),
	8192,	
	TEXT("Max KB of distance field texture data to upload per frame from streaming requests."),
	ECVF_RenderThreadSafe);

int32 GDistanceFieldOffsetDataStructure = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:908

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::ProcessReadRequests

Source code excerpt:

{
	const uint32 BrickSizeBytes = GPixelFormats[DistanceField::DistanceFieldFormat].BlockBytes * DistanceField::BrickSize * DistanceField::BrickSize * DistanceField::BrickSize;
	const SIZE_T TextureUploadLimitBytes = (SIZE_T)CVarTextureUploadLimitKBytes.GetValueOnRenderThread() * 1024;

	SIZE_T TextureUploadBytes = 0;

	// At this point DistanceFieldAssetMipAdds contains only lowest resolution mip adds which are always loaded
	// Forward these to the Requests to Upload list, with a null BulkData
	for (FDistanceFieldAssetMipId AssetMipAdd : DistanceFieldAssetMipAdds)