r.ForceHighestMipOnUITextures

r.ForceHighestMipOnUITextures

#Overview

name: r.ForceHighestMipOnUITextures

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

• type: Var
• help: If set to 1, texutres in the UI Group will have their highest mip level forced.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ForceHighestMipOnUITextures is to control the mip level selection for textures in the UI texture group. It is primarily used in the rendering system, specifically for texture resource management.

This setting variable is utilized in the Engine module, particularly in the texture resource management subsystem. The main file referencing this variable is Texture2DResource.cpp, which is responsible for handling 2D texture resources.

The value of this variable is set through a console variable (CVarForceHighestMipOnUITexturesEnabled) with a default value of 0. It can be changed at runtime using console commands or through game settings.

The associated variable CVarForceHighestMipOnUITexturesEnabled directly interacts with r.ForceHighestMipOnUITextures. They share the same value and purpose.

Developers must be aware that:

1. This variable is considered a backwards compatibility feature and may be removed in future versions of Unreal Engine.
2. When enabled (set to 1), it forces the highest mip level for textures in the UI Group, which can impact rendering performance and memory usage.
3. The variable is marked as render thread safe (ECVF_RenderThreadSafe), meaning it can be safely accessed from the render thread.

Best practices when using this variable include:

1. Avoid relying on this variable for new projects, as it’s intended for backwards compatibility.
2. If used, carefully consider the performance implications of forcing the highest mip level for UI textures.
3. Test thoroughly with both enabled and disabled states to ensure proper UI rendering across different scenarios.

Regarding the associated variable CVarForceHighestMipOnUITexturesEnabled:

• It is the actual console variable implementation of r.ForceHighestMipOnUITextures.
• It is used in the FTexture2DResource::CacheSamplerStateInitializer function to adjust the mip bias for UI textures when enabled.
• The variable is checked using GetValueOnAnyThread(), indicating that it can be safely accessed from multiple threads.
• When enabled, it applies a negative mip bias equal to the number of mips in the texture, effectively forcing the use of the highest resolution mip level.

Developers should treat CVarForceHighestMipOnUITexturesEnabled as the implementation detail of r.ForceHighestMipOnUITextures and follow the same best practices and considerations mentioned earlier.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/Texture2DResource.cpp:16

Scope: file

Source code excerpt:

// behavior is to NOT do this.  This variable should be removed in the future.  #ADDED 4.13
static TAutoConsoleVariable<int32> CVarForceHighestMipOnUITexturesEnabled(
	TEXT("r.ForceHighestMipOnUITextures"),
	0,
	TEXT("If set to 1, texutres in the UI Group will have their highest mip level forced."),
	ECVF_RenderThreadSafe);

/**
 * Minimal initialization constructor.

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/Texture2DResource.cpp:15

Scope: file

Source code excerpt:

// TODO Only adding this setting to allow backwards compatibility to be forced.  The default
// behavior is to NOT do this.  This variable should be removed in the future.  #ADDED 4.13
static TAutoConsoleVariable<int32> CVarForceHighestMipOnUITexturesEnabled(
	TEXT("r.ForceHighestMipOnUITextures"),
	0,
	TEXT("If set to 1, texutres in the UI Group will have their highest mip level forced."),
	ECVF_RenderThreadSafe);

/**

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/Texture2DResource.cpp:85

Scope (from outer to inner):

file
function     void FTexture2DResource::CacheSamplerStateInitializer

Source code excerpt:

{
	float DefaultMipBias = 0;
	if (PlatformData && LODGroup == TEXTUREGROUP_UI && CVarForceHighestMipOnUITexturesEnabled.GetValueOnAnyThread() > 0)
	{
		DefaultMipBias = -PlatformData->Mips.Num();
	}

	// Set FStreamableTextureResource sampler state settings as it is UTexture2D specific.
	AddressU = InOwner->AddressX == TA_Wrap ? AM_Wrap : (InOwner->AddressX == TA_Clamp ? AM_Clamp : AM_Mirror);