EnablesHLSL2021ByDefault

EnablesHLSL2021ByDefault

#Overview

name: EnablesHLSL2021ByDefault

The value of this variable can be defined or overridden in .ini config files. 6 .ini config files referencing this setting variable.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of EnablesHLSL2021ByDefault is to control the usage of HLSL 2021 features in shader compilation for different shader platforms. This setting variable is primarily used in the shader compilation system of Unreal Engine.

The Unreal Engine subsystem that relies on this setting variable is the Shader Compiler, specifically within the Engine and RHI (Rendering Hardware Interface) modules. This can be seen from the file paths where the variable is referenced: Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp and Engine/Source/Runtime/RHI/Private/DataDrivenShaderPlatformInfo.cpp.

The value of this variable is set through the data-driven shader platform information system. It’s parsed from configuration data in the FGenericDataDrivenShaderPlatformInfo::ParseDataDrivenShaderInfo function.

This variable interacts with other shader compilation flags and settings. For example, it’s used in conjunction with the CFLAG_HLSL2021 compiler flag and considers the shader frequency (e.g., SF_RayGen, SF_RayHitGroup) when determining whether to enable HLSL 2021 features.

Developers must be aware that this variable uses a 2-bit value to represent three states: 0: HLSL 2021 features are disabled 1: HLSL 2021 features are enabled for global shaders only 2: HLSL 2021 features are enabled for all shaders

Additionally, HLSL 2021 features are always enabled for ray tracing shaders (SF_RayGen and SF_RayHitGroup), regardless of this setting.

Best practices when using this variable include:

  1. Carefully consider the implications of enabling HLSL 2021 features, especially for cross-platform projects.
  2. Be aware that enabling HLSL 2021 for all shaders might affect performance or compatibility on some platforms.
  3. When working with ray tracing shaders, remember that HLSL 2021 features are always enabled, so design your shaders accordingly.
  4. Use the data-driven shader platform information system to configure this setting appropriately for each target platform in your project.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/Android/DataDrivenPlatformInfo.ini:117, section: [ShaderPlatform VULKAN_SM5_ANDROID]

Location: <Workspace>/Engine/Config/Mac/DataDrivenPlatformInfo.ini:54, section: [ShaderPlatform METAL_SM5]

Location: <Workspace>/Engine/Config/Mac/DataDrivenPlatformInfo.ini:94, section: [ShaderPlatform METAL_SM6]

Location: <Workspace>/Engine/Config/VulkanPC/DataDrivenPlatformInfo.ini:132, section: [ShaderPlatform VULKAN_SM5]

Location: <Workspace>/Engine/Config/VulkanPC/DataDrivenPlatformInfo.ini:250, section: [ShaderPlatform VULKAN_SM6]

Location: <Workspace>/Engine/Config/Windows/DataDrivenPlatformInfo.ini:133, section: [ShaderPlatform PCD3D_SM6]

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:


	// Enables HLSL 2021
	uint32 EnablesHLSL2021ByDefault = FDataDrivenShaderPlatformInfo::GetEnablesHLSL2021ByDefault(EShaderPlatform(Target.Platform));
	if((EnablesHLSL2021ByDefault == uint32(1) && DebugGroupName == TEXT("Global")) ||
		EnablesHLSL2021ByDefault == uint32(2) ||
		Target.Frequency == SF_RayGen ||			// We want to make sure that function overloads follow c++ rules for FRayDesc.
		Target.Frequency == SF_RayHitGroup)
	{
		Input.Environment.CompilerFlags.Add(CFLAG_HLSL2021);
	}

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/DataDrivenShaderPlatformInfo.cpp:285

Scope (from outer to inner):

file
function     void FGenericDataDrivenShaderPlatformInfo::ParseDataDrivenShaderInfo

Source code excerpt:

	GET_SECTION_BOOL_HELPER(bSupportsOIT);
	GET_SECTION_SUPPORT_HELPER(bSupportsRealTypes);
	GET_SECTION_INT_HELPER(EnablesHLSL2021ByDefault);
	GET_SECTION_BOOL_HELPER(bSupportsSceneDataCompressedTransforms);
	GET_SECTION_BOOL_HELPER(bSupportsSwapchainUAVs);
	GET_SECTION_BOOL_HELPER(bSupportsClipDistance);
	GET_SECTION_BOOL_HELPER(bSupportsNNEShaders);
	GET_SECTION_BOOL_HELPER(bSupportsShaderPipelines);
	GET_SECTION_BOOL_HELPER(bSupportsUniformBufferObjects);

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Public/DataDrivenShaderPlatformInfo.h:110

Scope (from outer to inner):

file
class        class FGenericDataDrivenShaderPlatformInfo

Source code excerpt:

	uint32 bSupportsOIT : 1;
	uint32 bSupportsRealTypes : int32(ERHIFeatureSupport::NumBits);
	uint32 EnablesHLSL2021ByDefault : 2; // 0: disabled, 1: global shaders only, 2: all shaders
	uint32 bSupportsSceneDataCompressedTransforms : 1;
	uint32 bIsPreviewPlatform : 1;
	uint32 bSupportsSwapchainUAVs : 1;
	uint32 bSupportsClipDistance : 1;
	uint32 bSupportsNNEShaders: 1;
	uint32 bSupportsShaderPipelines : 1;

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Public/DataDrivenShaderPlatformInfo.h:743

Scope (from outer to inner):

file
class        class FGenericDataDrivenShaderPlatformInfo
function     static const uint32 GetEnablesHLSL2021ByDefault

Source code excerpt:

	static FORCEINLINE_DEBUGGABLE const uint32 GetEnablesHLSL2021ByDefault(const FStaticShaderPlatform Platform)
	{
		return Infos[Platform].EnablesHLSL2021ByDefault;
	}
	
	static FORCEINLINE_DEBUGGABLE const bool GetSupportsClipDistance(const FStaticShaderPlatform Platform)
	{
		check(IsValid(Platform));
		return Infos[Platform].bSupportsClipDistance;