r.Shaders.Optimize

r.Shaders.Optimize

#Overview

name: r.Shaders.Optimize

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

• type: Var
• help: Whether to optimize shaders. When using graphical debuggers like Nsight it can be useful to disable this on startup.\nThis setting can be overriden in any Engine.ini under the [ShaderCompiler] section.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shaders.Optimize is to control whether shaders should be optimized during compilation. This setting is primarily used in the shader compilation and rendering systems of Unreal Engine 5.

Based on the callsites, this setting variable is relied upon by the following Unreal Engine subsystems and modules:

1. The shader compiler subsystem (ShaderCompiler.cpp)
2. The Metal RHI (Rendering Hardware Interface) module for Apple platforms (MetalCommandQueue.cpp)
3. The RenderCore module (ShaderCore.cpp)

The value of this variable is set as a console variable (CVar) with a default value of 1 (enabled). It can be overridden in the Engine.ini file under the [ShaderCompiler] section.

This variable interacts with other shader-related settings and systems, particularly those involved in shader compilation and optimization. In the Metal RHI, it also interacts with the EMetalFeaturesGPUTrace feature flag.

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

1. Disabling shader optimization (setting to 0) can be useful when using graphical debuggers like Nsight.
2. The setting is marked as ECVF_ReadOnly, meaning it should typically be set at startup and not changed during runtime.
3. On Apple platforms with Metal, disabling this option or using the “metalshaderdebug” command line parameter enables GPU tracing features.

Best practices when using this variable include:

1. Leave it enabled (default value of 1) for release builds to ensure optimal shader performance.
2. Consider disabling it temporarily when debugging shaders or using graphical debugging tools.
3. If overriding the value, do so in the Engine.ini file for consistency across the project.
4. Be aware that disabling optimization may impact performance but can aid in debugging and development.

#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:2208

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarOptimizeShaders(
	TEXT("r.Shaders.Optimize"),
	1,
	TEXT("Whether to optimize shaders.  When using graphical debuggers like Nsight it can be useful to disable this on startup.\n")
	TEXT("This setting can be overriden in any Engine.ini under the [ShaderCompiler] section."),
	ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarShaderFastMath(

#Loc: <Workspace>/Engine/Source/Runtime/Apple/MetalRHI/Private/MetalCommandQueue.cpp:264

Scope: file

Source code excerpt:

#endif

	static const auto CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shaders.Optimize"));
	if (CVar->GetInt() == 0 || FParse::Param(FCommandLine::Get(),TEXT("metalshaderdebug")))
	{
		Features |= EMetalFeaturesGPUTrace;
	}

	PermittedOptions = 0;

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderCore.cpp:673

Scope (from outer to inner):

file
function     bool ShouldOptimizeShaders

Source code excerpt:

bool ShouldOptimizeShaders(FName ShaderFormat)
{
	static const FShaderSymbolSettingHelper Optimize(TEXT("r.Shaders.Optimize"));
	return Optimize.IsEnabled(ShaderFormat);
}

#ifndef UE_ALLOW_SHADER_COMPILING
// is shader compiling allowed at all? (set to 0 in a cooked editor .Target.cs if the target has no shaders available)
#define UE_ALLOW_SHADER_COMPILING 1