r.MaterialEditor.PreshaderDumpToHLSL

r.MaterialEditor.PreshaderDumpToHLSL

#Overview

name: r.MaterialEditor.PreshaderDumpToHLSL

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.MaterialEditor.PreshaderDumpToHLSL is to control whether preshader expressions and parameter reference counts are appended to the HLSL source window as comments at the end of the code in the Material Editor.

This setting variable is primarily used in the rendering system, specifically in the material compilation and editing process within Unreal Engine.

Based on the callsites, this variable is used in the Engine module, particularly in the Materials subsystem.

The value of this variable is set using a TAutoConsoleVariable, which means it can be changed at runtime through the console or configuration files. By default, it is set to true.

The associated variable CVarMaterialEdPreshaderDumpToHLSL interacts directly with r.MaterialEditor.PreshaderDumpToHLSL. They share the same value and purpose.

Developers must be aware that this variable only has an effect when the editor is present (#if WITH_EDITOR), and it’s specifically designed for use in the Material Editor. It affects the output of the HLSL source window, which can be useful for debugging and understanding the compiled material code.

Best practices when using this variable include:

  1. Use it for debugging complex materials, as it provides additional information about preshader expressions and parameter usage.
  2. Be aware that enabling this option may slightly increase the time it takes to display the HLSL source in the Material Editor, especially for complex materials.
  3. Consider disabling it in performance-critical scenarios or when not actively debugging material issues.

Regarding the associated variable CVarMaterialEdPreshaderDumpToHLSL:

The purpose of CVarMaterialEdPreshaderDumpToHLSL is identical to r.MaterialEditor.PreshaderDumpToHLSL. It’s the actual console variable that controls the behavior described earlier.

This variable is used in the Engine module, specifically in the material compilation process.

The value is set when the TAutoConsoleVariable is initialized, and it can be changed at runtime through console commands.

CVarMaterialEdPreshaderDumpToHLSL directly controls the behavior of appending preshader information to the HLSL source. It’s checked in the FMaterial::GetMaterialExpressionSource function to determine whether to append the additional information.

Developers should be aware that this variable is only accessible within the Engine module and is marked as ECVF_RenderThreadSafe, meaning it’s safe to access from the render thread.

Best practices for using CVarMaterialEdPreshaderDumpToHLSL include:

  1. Use console commands to toggle this feature on and off as needed during development.
  2. Be mindful of its impact on performance and material compilation time when enabled.
  3. Consider exposing this option in your project’s development settings for easier access by the development team.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialShared.cpp:79

Scope: file

Source code excerpt:

#if WITH_EDITOR
static TAutoConsoleVariable<bool> CVarMaterialEdPreshaderDumpToHLSL(
	TEXT("r.MaterialEditor.PreshaderDumpToHLSL"),
	true,
	TEXT("Controls whether to append preshader expressions and parameter reference counts to the HLSL source window (as comments at the end of the code)."),
	ECVF_RenderThreadSafe);
#endif

IMPLEMENT_TYPE_LAYOUT(FHashedMaterialParameterInfo);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialShared.cpp:78

Scope: file

Source code excerpt:


#if WITH_EDITOR
static TAutoConsoleVariable<bool> CVarMaterialEdPreshaderDumpToHLSL(
	TEXT("r.MaterialEditor.PreshaderDumpToHLSL"),
	true,
	TEXT("Controls whether to append preshader expressions and parameter reference counts to the HLSL source window (as comments at the end of the code)."),
	ECVF_RenderThreadSafe);
#endif

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialShared.cpp:4364

Scope (from outer to inner):

file
function     bool FMaterial::GetMaterialExpressionSource

Source code excerpt:

			OutSource = MoveTemp(*Source);

			if (CVarMaterialEdPreshaderDumpToHLSL.GetValueOnGameThread())
			{
				OutSource.AppendChar('\n');

				TMap<FString, uint32> ParameterReferences;
				FMaterialRenderContext MaterialContext(nullptr, *this, nullptr);
				UE::Shader::FPreshaderDataContext PreshaderContextBase(NewCompilationOutput.UniformExpressionSet.UniformPreshaderData);