r.Shaders.FlowControlMode

r.Shaders.FlowControlMode

#Overview

name: r.Shaders.FlowControlMode

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shaders.FlowControlMode is to control how the shader compiler handles flow control statements in shader code. It’s primarily used for debugging and can override per-shader or per-material settings.

This setting variable is used in the shader compilation system of Unreal Engine. Based on the callsites, it’s utilized in the ShaderCompiler module and affects the RenderCore subsystem.

The value of this variable is set through a console variable (CVar) system, which allows it to be changed at runtime. It’s defined with a default value of 0, but can be modified through the console or configuration files.

The variable interacts with shader compilation flags, specifically the CFLAG_AvoidFlowControl flag. It also affects the shader map key string generation, which is used for shader caching and compilation.

Developers should be aware that:

  1. This is primarily a debugging aid and should be left at its default value (0) for normal operation.
  2. Changing this value will override per-shader and per-material settings.
  3. It has three possible values:
    • 0: Off (Default) - Flow control handling is left to the platform compiler or specific shader/material settings.
    • 1: Prefer - Attempts to preserve flow control in shaders.
    • 2: Avoid - Attempts to unroll and flatten flow control in shaders.

Best practices when using this variable:

  1. Leave it at the default value (0) unless debugging specific shader issues.
  2. Use it temporarily for debugging and revert to the default value after.
  3. Be aware that changing this value can affect shader performance and compilation times.

Regarding the associated variable CVarShaderFlowControl:

The purpose of CVarShaderFlowControl is to serve as the actual console variable that stores and provides access to the r.Shaders.FlowControlMode setting.

This variable is part of the shader compilation system in Unreal Engine. It’s defined in the ShaderCompiler module and used to control shader compilation behavior.

The value of CVarShaderFlowControl is set when the console variable is defined, but can be changed at runtime through the console system.

It directly interacts with the shader compilation process, affecting how flow control is handled in shaders.

Developers should be aware that:

  1. This is the actual variable that stores the flow control mode setting.
  2. It can be accessed from C++ code to read or modify the current flow control mode.

Best practices when using CVarShaderFlowControl:

  1. Use GetValueOnAnyThread() to safely read its value from any thread.
  2. Avoid directly modifying this variable; instead, use the console command system to change r.Shaders.FlowControlMode.
  3. Consider the performance implications when changing this value, especially in shipping builds.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarShaderFlowControl(
	TEXT("r.Shaders.FlowControlMode"),
	0,
	TEXT("Specifies whether the shader compiler should preserve or unroll flow-control in shader code.\n")
	TEXT("This is primarily a debugging aid and will override any per-shader or per-material settings if not left at the default value (0).\n")
	TEXT("\t0: Off (Default) - Entirely at the discretion of the platform compiler or the specific shader/material.\n")
	TEXT("\t1: Prefer - Attempt to preserve flow-control.\n")
	TEXT("\t2: Avoid - Attempt to unroll and flatten flow-control.\n"),

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

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

	
	{
		static const auto CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shaders.FlowControlMode"));
		if (CVar)
		{
			switch(CVar->GetInt())
			{
				case 2:
					KeyString += TEXT("_AvoidFlow");

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarShaderFlowControl(
	TEXT("r.Shaders.FlowControlMode"),
	0,
	TEXT("Specifies whether the shader compiler should preserve or unroll flow-control in shader code.\n")
	TEXT("This is primarily a debugging aid and will override any per-shader or per-material settings if not left at the default value (0).\n")
	TEXT("\t0: Off (Default) - Entirely at the discretion of the platform compiler or the specific shader/material.\n")
	TEXT("\t1: Prefer - Attempt to preserve flow-control.\n")

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

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:

	
	{
		int32 FlowControl = CVarShaderFlowControl.GetValueOnAnyThread();
		switch (FlowControl)
		{
			case 2:
				Input.Environment.CompilerFlags.Add(CFLAG_AvoidFlowControl);
				break;
			case 1: