r.CompileShadersForDevelopment

r.CompileShadersForDevelopment

#Overview

name: r.CompileShadersForDevelopment

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

• type: Var
• help: Setting this to 0 allows to ship a game with more optimized shaders as some\neditor and development features are not longer compiled into the shaders.\n Note: This should be done when shipping but it\'s not done automatically yet (feature need to mature\n and shaders will compile slower as shader caching from development isn\'t shared).\nCannot be changed at runtime - can be put into BaseEngine.ini\n 0: off, shader can run a bit faster\n 1: on (Default)

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.CompileShadersForDevelopment is to control whether shaders are compiled with additional features for development and editor use. This setting is primarily used in the shader compilation and rendering systems of Unreal Engine 5.

Based on the callsites, this variable is utilized in several Unreal Engine subsystems and modules, including:

1. Core module (ConsoleManager)
2. Engine module (MaterialTranslator and ShaderCompiler)
3. RenderCore module (Shader compilation)

The value of this variable is set through a console variable (CVar) system, likely initialized in the engine configuration files (as suggested by the comment “Cannot be changed at runtime - can be put into BaseEngine.ini”).

This variable interacts with other development-related variables and flags, such as Material->GetAllowDevelopmentShaderCompile() and bAllowDevelopmentShaderCompile.

Developers should be aware that:

1. This setting affects shader compilation performance and the resulting shader code.
2. Disabling it (setting to 0) can lead to more optimized shaders for shipping builds but may remove some editor and development features from the shaders.
3. It cannot be changed at runtime, requiring a restart of the engine to take effect.

Best practices when using this variable include:

1. Keep it enabled (set to 1) during development to ensure all necessary features are available.
2. Consider disabling it (set to 0) when preparing for a shipping build to optimize shader performance.
3. Be aware that disabling this setting may impact shader caching from development builds.
4. Thoroughly test the game after changing this setting, as it may affect how shaders behave in different scenarios.

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

Scope: file

Source code excerpt:

// this cvar can be removed in shipping to not compile shaders for development (faster)
static TAutoConsoleVariable<int32> CVarCompileShadersForDevelopment(
	TEXT("r.CompileShadersForDevelopment"),
	1,
	TEXT("Setting this to 0 allows to ship a game with more optimized shaders as some\n"
		 "editor and development features are not longer compiled into the shaders.\n"
		 " Note: This should be done when shipping but it's not done automatically yet (feature need to mature\n"
		 "       and shaders will compile slower as shader caching from development isn't shared).\n"
		 "Cannot be changed at runtime - can be put into BaseEngine.ini\n"

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/HLSLMaterialTranslator.cpp:14239

Scope (from outer to inner):

file
function     bool FHLSLMaterialTranslator::IsDevelopmentFeatureEnabled

Source code excerpt:

		// The list below may not be comprehensive enough, but it definitely includes platforms which won't use selection color for sure.
		const bool bEditorMayUseTargetShaderPlatform = IsPCPlatform(Platform);
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.CompileShadersForDevelopment"));
		const bool bCompileShadersForDevelopment = (CVar && CVar->GetValueOnAnyThread() != 0);

		return
			// Does the material explicitly forbid development features?
			Material->GetAllowDevelopmentShaderCompile()
			// Can the editor run using the current shader platform?

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

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:

	if (bAllowDevelopmentShaderCompile)
	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.CompileShadersForDevelopment"));
		SET_SHADER_DEFINE(Input.Environment, COMPILE_SHADERS_FOR_DEVELOPMENT, CVar ? (CVar->GetValueOnAnyThread() != 0) : 0);
	}

	{
		SET_SHADER_DEFINE(Input.Environment, ALLOW_STATIC_LIGHTING, IsStaticLightingAllowed() ? 1 : 0);
	}

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

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.CompileShadersForDevelopment"));
		KeyString += (CVar && CVar->GetValueOnAnyThread() != 0) ? TEXT("_DEV") : TEXT("_NoDEV");
	}

	{
		const bool bValue = IsStaticLightingAllowed();
		KeyString += bValue ? TEXT("_SL") : TEXT("_NoSL");

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Public/ShaderMaterial.h:43

Scope: file

Source code excerpt:

	bool PLATFORM_ALLOW_SCENE_DATA_COMPRESSED_TRANSFORMS;

	// This is a sepcial one. The flag COMPILE_SHADERS_FOR_DEVELOPMENT is set by the cvar r.CompileShadersForDevelopment, but only
	// if bAllowDevelopmentShaderCompile is true in the call to GlobalBeginCompileShader(). So the flag COMPILE_SHADERS_FOR_DEVELOPMENT_ALLOWED
	// simply stores the result of r.CompileShadersForDevelopment. Then the logic later down the pipeline is:
	// COMPILE_SHADERS_FOR_DEVELOPMENT = COMPILE_SHADERS_FOR_DEVELOPMENT_ALLOWED && bAllowDevelopmentShaderCompile;
	bool COMPILE_SHADERS_FOR_DEVELOPMENT_ALLOWED;
	bool bSupportsDualBlending;
	int LegacyGBufferFormat;
	bool bNeedVelocityDepth;
};