Compat.UseDXT5NormalMaps

Compat.UseDXT5NormalMaps

#Overview

name: Compat.UseDXT5NormalMaps

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

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of Compat.UseDXT5NormalMaps is to control the texture format used for normal maps in Unreal Engine 5. It determines whether to use DXT5 or BC5 compression for normal map textures.

This setting variable is primarily used by the rendering system and texture compression modules. Based on the callsites, it affects the following Unreal Engine subsystems and modules:

  1. Texture compression (TextureFormatOodle plugin)
  2. Shader compilation
  3. Renderer settings
  4. Texture loading and processing

The value of this variable is set in multiple ways:

  1. Through the console variable system (CVarUseDXT5NormalMaps)
  2. In the RendererSettings class as a config property (bUseDXT5NormalMaps)
  3. Via the engine configuration file (GEngineIni)

This variable interacts with other parts of the engine, particularly:

  1. Shader compilation, where it affects the DXT5_NORMALMAPS define
  2. Texture format selection when loading or compressing textures

Developers must be aware of the following when using this variable:

  1. Changing this setting requires restarting the editor
  2. It affects texture compression quality and hardware compatibility
  3. BC5 is the preferred format (higher quality) but may not be supported on all hardware

Best practices when using this variable include:

  1. Use BC5 (default, value 0) unless there are specific hardware compatibility issues
  2. Consider the target platforms and their texture format support when setting this variable
  3. Be aware that changing this setting will cause normal maps to be recompressed on the next load
  4. Test thoroughly on target hardware to ensure compatibility and visual quality

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/HAL/ConsoleManager.cpp:3724

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarUseDXT5NormalMaps(
	TEXT("Compat.UseDXT5NormalMaps"),
	0,
	TEXT("Whether to use DXT5 for normal maps, otherwise BC5 will be used, which is not supported on all hardware.\n"
		 "Both formats require the same amount of memory (if driver doesn't emulate the format).\n"
		 "Changing this will cause normal maps to be recompressed on next load (or when using recompile shaders)\n"
		 " 0: Use BC5 texture format (default)\n"
		 " 1: Use DXT5 texture format (lower quality)"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:380

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:


	UPROPERTY(config, EditAnywhere, Category=Textures, meta=(
		ConsoleVariable="Compat.UseDXT5NormalMaps",DisplayName="Use DXT5 Normal Maps",
		ToolTip="Whether to use DXT5 for normal maps, otherwise BC5 will be used, which is not supported on all hardware. Changing this setting requires restarting the editor.",
		ConfigRestartRequired=true))
	uint32 bUseDXT5NormalMaps:1;

	/**
	 * Virtual Texture

#Loc: <Workspace>/Engine/Plugins/Developer/TextureFormatOodle/Source/Private/TextureFormatOodle.cpp:676

Scope (from outer to inner):

file
class        class FTextureFormatOodleConfig
function     void GetOodleCompressParameters

Source code excerpt:

		{
			// Unreal already has global UseDXT5NormalMap config option
			// EngineSettings.GetString(TEXT("SystemSettings"), TEXT("Compat.UseDXT5NormalMaps")
			//	if that is false (which is the default) they use BC5
			// so this should be rarely use
			// (we prefer BC5 over DXT5n)
			CompressedPixelFormat = PF_DXT5;
		}
		else if (TextureFormatName == GTextureFormatNameBC4)

#Loc: <Workspace>/Engine/Plugins/Developer/TextureFormatOodle/Source/Private/TextureFormatOodle.cpp:1319

Scope (from outer to inner):

file
class        class FTextureFormatOodle : public ITextureFormat
function     virtual bool CompressImage

Source code excerpt:

			TextureFormatName == GTextureFormatNameDXT5n)
		{
			// this is only used if Compat.UseDXT5NormalMaps

			// normal map comes in as RG , B&A can be ignored
			// in the optional use BC5 path, only the source RG pass through
			// normal was in RG , move to GA
			if ( OodlePF == OodleTex_PixelFormat_4_U8_BGRx )
			{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:8317

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:


	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("Compat.UseDXT5NormalMaps"));
		SET_SHADER_DEFINE(Input.Environment, DXT5_NORMALMAPS, CVar ? (CVar->GetValueOnAnyThread() != 0) : 0);
	}

	if (bAllowDevelopmentShaderCompile)
	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.CompileShadersForDevelopment"));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderGenerationUtil.cpp:338

Scope (from outer to inner):

file
function     static FShaderGlobalDefines FetchShaderGlobalDefines

Source code excerpt:


	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("Compat.UseDXT5NormalMaps"));
		Ret.DXT5_NORMALMAPS = CVar ? (CVar->GetValueOnAnyThread() != 0) : 0;
	}

	Ret.SELECTIVE_BASEPASS_OUTPUTS = IsUsingSelectiveBasePassOutputs((EShaderPlatform)TargetPlatform) ? 1 : 0;
	Ret.USE_DBUFFER = IsUsingDBuffers((EShaderPlatform)TargetPlatform) ? 1 : 0;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Texture.cpp:3728

Scope (from outer to inner):

file
function     FName GetDefaultTextureFormatName

Source code excerpt:

	FString UseDXT5NormalMapsString;

	if (TargetPlatformSettings->GetConfigSystem()->GetString(TEXT("SystemSettings"), TEXT("Compat.UseDXT5NormalMaps"), UseDXT5NormalMapsString, GEngineIni))
	{
		bUseDXT5NormalMap = FCString::ToBool(*UseDXT5NormalMapsString);
	}

	// Determine the pixel format of the (un/)compressed texture

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:1523

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:


	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("Compat.UseDXT5NormalMaps"));
		KeyString += (CVar && CVar->GetValueOnAnyThread() != 0) ? TEXT("_DXTN") : TEXT("_BC5N");
	}

	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.ClearCoatNormal"));
		KeyString += (CVar && CVar->GetValueOnAnyThread() != 0) ? TEXT("_CCBN") : TEXT("_NoCCBN");