r.Substrate.OpaqueMaterialRoughRefraction

r.Substrate.OpaqueMaterialRoughRefraction

#Overview

name: r.Substrate.OpaqueMaterialRoughRefraction

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.Substrate.OpaqueMaterialRoughRefraction is to enable or disable the Substrate opaque material rough refractions effect from top layers over layers below in Unreal Engine’s rendering system.

This setting variable is primarily used in the rendering subsystem of Unreal Engine, specifically within the Substrate rendering module. Based on the callsites, it’s referenced in the RenderCore and Engine modules.

The value of this variable is set through a console variable (CVar) named CVarSubstrateOpaqueMaterialRoughRefraction. It’s initialized with a default value of 0, meaning the feature is disabled by default.

The associated variable CVarSubstrateOpaqueMaterialRoughRefraction directly interacts with r.Substrate.OpaqueMaterialRoughRefraction. They share the same value and purpose.

Developers should be aware that this variable is marked as read-only and render thread safe (ECVF_ReadOnly | ECVF_RenderThreadSafe). This means it cannot be changed during runtime and is designed to be safely accessed from the render thread.

Best practices when using this variable include:

  1. Only enable it when needed, as it may have performance implications.
  2. Be aware that it’s a global setting affecting all opaque materials using the Substrate system.
  3. Use it in conjunction with other Substrate-related settings for optimal results.
  4. Test thoroughly when enabled to ensure it doesn’t negatively impact performance or visual quality in your specific use case.

Regarding the associated variable CVarSubstrateOpaqueMaterialRoughRefraction:

The purpose of CVarSubstrateOpaqueMaterialRoughRefraction is to provide programmatic access to the r.Substrate.OpaqueMaterialRoughRefraction setting within the C++ code.

This variable is used in the RenderCore module of Unreal Engine, specifically within the Substrate namespace.

The value of this variable is set when the engine initializes its console variables. It can be accessed using the GetValueOnAnyThread() method.

It interacts directly with the IsOpaqueRoughRefractionEnabled() function in the Substrate namespace, which checks if both Substrate is enabled and this variable is set to a value greater than 0.

Developers should be aware that this is a TAutoConsoleVariable, meaning it’s an integer value that can be changed via console commands.

Best practices include:

  1. Use the IsOpaqueRoughRefractionEnabled() function to check if the feature is enabled, rather than accessing the CVar directly.
  2. Be cautious when changing this value, as it affects the entire rendering pipeline for Substrate materials.
  3. Consider performance implications when enabling this feature, especially on lower-end hardware.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1758

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSubstrateOpaqueMaterialRoughRefraction(
	TEXT("r.Substrate.OpaqueMaterialRoughRefraction"),
	0,
	TEXT("Enable Substrate opaque material rough refractions effect from top layers over layers below."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateSheenQuality(
	TEXT("r.Substrate.SheenQuality"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SubstrateVisualizationData.cpp:126

Scope (from outer to inner):

file
function     void FSubstrateVisualizationData::Initialize

Source code excerpt:

			true,
			Substrate::IsOpaqueRoughRefractionEnabled(),
			LOCTEXT("IsSubstrateRoughRefractionEnabled", "Substrate rough refraction r.Substrate.OpaqueMaterialRoughRefraction is disabled"));

		AddVisualizationMode(
			AllModeMap,
			TEXT("SubstrateInfo"),
			LOCTEXT("SubstrateInfo", "Substrate Info"),
			LOCTEXT("SubstrateInfoDesc", "Visualizes Substrate info"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1757

Scope: file

Source code excerpt:

	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateOpaqueMaterialRoughRefraction(
	TEXT("r.Substrate.OpaqueMaterialRoughRefraction"),
	0,
	TEXT("Enable Substrate opaque material rough refractions effect from top layers over layers below."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateSheenQuality(

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1999

Scope (from outer to inner):

file
namespace    Substrate
function     bool IsOpaqueRoughRefractionEnabled

Source code excerpt:

	bool IsOpaqueRoughRefractionEnabled()
	{
		return IsSubstrateEnabled() && CVarSubstrateOpaqueMaterialRoughRefraction.GetValueOnAnyThread() > 0;
	}

	bool IsAdvancedVisualizationEnabled()
	{
		return CVarSubstrateDebugAdvancedVisualizationShaders.GetValueOnAnyThread() > 0;
	}