r.MaterialEnableNewHLSLGenerator

r.MaterialEnableNewHLSLGenerator

#Overview

name: r.MaterialEnableNewHLSLGenerator

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

It is referenced in 13 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.MaterialEnableNewHLSLGenerator is to control the usage of a new, work-in-progress (WIP) material HLSL generator in Unreal Engine 5. This setting variable is primarily used in the material system, specifically for generating HLSL code for materials.

The Unreal Engine subsystems that rely on this setting variable are primarily the Material system and the Rendering system. It’s also used in the Material Editor, which is part of the Editor subsystem.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable in MaterialInterface.cpp, which means it can be changed at runtime through console commands or configuration files.

This variable interacts closely with its associated variable CVarMaterialEnableNewHLSLGenerator. They share the same value and are used interchangeably in different parts of the code.

Developers must be aware that this variable controls a work-in-progress feature. It has three possible values: 0 - Don’t allow the new generator 1 - Allow if enabled by material 2 - Force all materials to use the new generator

Best practices when using this variable include:

  1. Use caution when enabling it, as it’s a WIP feature and may have unexpected results.
  2. Test thoroughly when changing this setting, especially in production environments.
  3. Be aware that forcing all materials to use the new generator (value 2) might have performance or compatibility implications.

Regarding the associated variable CVarMaterialEnableNewHLSLGenerator:

The purpose of CVarMaterialEnableNewHLSLGenerator is the same as r.MaterialEnableNewHLSLGenerator. It’s used to access the value of the console variable in various parts of the code.

This variable is used in multiple Unreal Engine modules, including the Material Editor and the core Engine module.

The value of this variable is set indirectly through the r.MaterialEnableNewHLSLGenerator console variable.

It interacts closely with r.MaterialEnableNewHLSLGenerator, sharing the same value and purpose.

Developers should be aware that this variable is often used to check the current state of the new HLSL generator feature, particularly in UI-related code to show or hide certain options.

Best practices include using this variable consistently when checking the state of the new HLSL generator feature, and being aware of its potential impact on material compilation and rendering.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialInterface.cpp:63

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarMaterialEnableNewHLSLGenerator(
	TEXT("r.MaterialEnableNewHLSLGenerator"),
	0,
	TEXT("Enables the new (WIP) material HLSL generator.\n")
	TEXT("0 - Don't allow\n")
	TEXT("1 - Allow if enabled by material\n")
	TEXT("2 - Force all materials to use new generator\n"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Editor/MaterialEditor/Private/MaterialEditorDetailCustomization.cpp:779

Scope (from outer to inner):

file
function     void FMaterialDetailCustomization::CustomizeDetails

Source code excerpt:

void FMaterialDetailCustomization::CustomizeDetails( IDetailLayoutBuilder& DetailLayout )
{
	static const auto CVarMaterialEnableNewHLSLGenerator = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.MaterialEnableNewHLSLGenerator"));

	TArray<TWeakObjectPtr<UObject> > Objects;
	DetailLayout.GetObjectsBeingCustomized( Objects );

	bool bUIMaterial = true;
	bool bIsShadingModelFromMaterialExpression = false;

#Loc: <Workspace>/Engine/Source/Editor/MaterialEditor/Private/MaterialEditorDetailCustomization.cpp:941

Scope (from outer to inner):

file
function     void FMaterialFunctionDetailCustomization::CustomizeDetails

Source code excerpt:

void FMaterialFunctionDetailCustomization::CustomizeDetails(IDetailLayoutBuilder& DetailLayout)
{
	static const auto CVarMaterialEnableNewHLSLGenerator = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.MaterialEnableNewHLSLGenerator"));

	// MaterialFunction category
	{
		IDetailCategoryBuilder& MaterialCategory = DetailLayout.EditCategory(TEXT("MaterialFunction"));

		TArray<TSharedRef<IPropertyHandle>> AllProperties;

#Loc: <Workspace>/Engine/Source/Editor/MaterialEditor/Private/MaterialExpressionClasses.cpp:86

Scope (from outer to inner):

file
function     void MaterialExpressionClasses::InitMaterialExpressionClasses

Source code excerpt:

	if(!bInitialized)
	{
		static const auto CVarMaterialEnableNewHLSLGenerator = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.MaterialEnableNewHLSLGenerator"));
		
		const bool bEnableControlFlow = AllowMaterialControlFlow();
		const bool bEnableNewHLSLGenerator = CVarMaterialEnableNewHLSLGenerator->GetValueOnAnyThread() != 0;

		UMaterialEditorOptions* TempEditorOptions = NewObject<UMaterialEditorOptions>();
		UClass* BaseType = UMaterialExpression::StaticClass();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialExpressions.cpp:15697

Scope (from outer to inner):

file
function     bool UMaterialFunction::IsUsingNewHLSLGenerator

Source code excerpt:

	if (bEnableNewHLSLGenerator)
	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.MaterialEnableNewHLSLGenerator"));
		return CVar->GetValueOnAnyThread() != 0;
	}
	return false;
}

void UMaterialFunction::CreateExecutionFlowExpressions()

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/MaterialEditor/Private/MaterialEditorDetailCustomization.cpp:779

Scope (from outer to inner):

file
function     void FMaterialDetailCustomization::CustomizeDetails

Source code excerpt:

void FMaterialDetailCustomization::CustomizeDetails( IDetailLayoutBuilder& DetailLayout )
{
	static const auto CVarMaterialEnableNewHLSLGenerator = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.MaterialEnableNewHLSLGenerator"));

	TArray<TWeakObjectPtr<UObject> > Objects;
	DetailLayout.GetObjectsBeingCustomized( Objects );

	bool bUIMaterial = true;
	bool bIsShadingModelFromMaterialExpression = false;

#Loc: <Workspace>/Engine/Source/Editor/MaterialEditor/Private/MaterialEditorDetailCustomization.cpp:856

Scope (from outer to inner):

file
function     void FMaterialDetailCustomization::CustomizeDetails

Source code excerpt:

			}

			if (PropertyName == GET_MEMBER_NAME_CHECKED(UMaterial, bEnableNewHLSLGenerator) && !CVarMaterialEnableNewHLSLGenerator->GetValueOnAnyThread())
			{
				DetailLayout.HideProperty(PropertyHandle);
			}

#if WITH_EDITORONLY_DATA
			// Hide the shading model

#Loc: <Workspace>/Engine/Source/Editor/MaterialEditor/Private/MaterialEditorDetailCustomization.cpp:941

Scope (from outer to inner):

file
function     void FMaterialFunctionDetailCustomization::CustomizeDetails

Source code excerpt:

void FMaterialFunctionDetailCustomization::CustomizeDetails(IDetailLayoutBuilder& DetailLayout)
{
	static const auto CVarMaterialEnableNewHLSLGenerator = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.MaterialEnableNewHLSLGenerator"));

	// MaterialFunction category
	{
		IDetailCategoryBuilder& MaterialCategory = DetailLayout.EditCategory(TEXT("MaterialFunction"));

		TArray<TSharedRef<IPropertyHandle>> AllProperties;

#Loc: <Workspace>/Engine/Source/Editor/MaterialEditor/Private/MaterialEditorDetailCustomization.cpp:960

Scope (from outer to inner):

file
function     void FMaterialFunctionDetailCustomization::CustomizeDetails

Source code excerpt:

			}

			if (PropertyName == GET_MEMBER_NAME_CHECKED(UMaterialFunction, bEnableNewHLSLGenerator) && !CVarMaterialEnableNewHLSLGenerator->GetValueOnAnyThread())
			{
				DetailLayout.HideProperty(PropertyHandle);
			}
		}
	}
}

#Loc: <Workspace>/Engine/Source/Editor/MaterialEditor/Private/MaterialExpressionClasses.cpp:86

Scope (from outer to inner):

file
function     void MaterialExpressionClasses::InitMaterialExpressionClasses

Source code excerpt:

	if(!bInitialized)
	{
		static const auto CVarMaterialEnableNewHLSLGenerator = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.MaterialEnableNewHLSLGenerator"));
		
		const bool bEnableControlFlow = AllowMaterialControlFlow();
		const bool bEnableNewHLSLGenerator = CVarMaterialEnableNewHLSLGenerator->GetValueOnAnyThread() != 0;

		UMaterialEditorOptions* TempEditorOptions = NewObject<UMaterialEditorOptions>();
		UClass* BaseType = UMaterialExpression::StaticClass();
		if( BaseType )
		{
			TArray<FStructProperty*>	ExpressionInputs;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialInterface.cpp:62

Scope: file

Source code excerpt:

UEnum* UMaterialInterface::SamplerTypeEnum = nullptr;

static TAutoConsoleVariable<int32> CVarMaterialEnableNewHLSLGenerator(
	TEXT("r.MaterialEnableNewHLSLGenerator"),
	0,
	TEXT("Enables the new (WIP) material HLSL generator.\n")
	TEXT("0 - Don't allow\n")
	TEXT("1 - Allow if enabled by material\n")
	TEXT("2 - Force all materials to use new generator\n"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialInterface.cpp:280

Scope (from outer to inner):

file
function     bool UMaterialInterface::IsUsingControlFlow

Source code excerpt:

bool UMaterialInterface::IsUsingControlFlow() const
{
	const int CVarValue = CVarMaterialEnableNewHLSLGenerator.GetValueOnAnyThread();
	if (CVarValue == 0)
	{
		return false;
	}

	const UMaterial* BaseMaterial = GetMaterial_Concurrent();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialInterface.cpp:292

Scope (from outer to inner):

file
function     bool UMaterialInterface::IsUsingNewHLSLGenerator

Source code excerpt:

bool UMaterialInterface::IsUsingNewHLSLGenerator() const
{
	const int CVarValue = CVarMaterialEnableNewHLSLGenerator.GetValueOnAnyThread();
	if (CVarValue == 0)
	{
		return false;
	}
	else if (CVarValue == 2)
	{