r.SSProfiles.Transmission.UseLegacy

r.SSProfiles.Transmission.UseLegacy

#Overview

name: r.SSProfiles.Transmission.UseLegacy

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.SSProfiles.Transmission.UseLegacy is to control the transmission profile used in subsurface scattering (SSS) calculations within the rendering system of Unreal Engine 5. This setting variable allows developers to switch between a more physically correct transmission profile and a legacy transmission profile.

This setting variable is primarily used in the rendering subsystem of Unreal Engine, specifically in the subsurface scattering implementation. It is defined and used in the BurleyNormalizedSSS.cpp file, which is part of the Engine module.

The value of this variable is set through the console variable system in Unreal Engine. It is initialized with a default value of 1, which means the legacy transmission profile is used by default.

The associated variable CVarSSProfilesTransmissionUseLegacy directly interacts with r.SSProfiles.Transmission.UseLegacy. They share the same value and purpose.

Developers must be aware that:

  1. This variable affects the visual quality and performance of subsurface scattering rendering.
  2. Changing this setting may impact the appearance of materials that use subsurface scattering, potentially requiring adjustments to material parameters.
  3. The physically correct transmission profile (value 0) may produce different results compared to the legacy profile (value 1), which could affect existing content.

Best practices when using this variable include:

  1. Testing the visual impact of both settings (0 and 1) on your specific content to determine which provides the best results for your project.
  2. Documenting the chosen setting in your project’s technical specifications to ensure consistency across the development team.
  3. Consider the performance implications of each setting, especially for projects targeting lower-end hardware.
  4. If switching from the legacy to the physically correct profile, review and potentially adjust existing materials that use subsurface scattering.

Regarding the associated variable CVarSSProfilesTransmissionUseLegacy: The purpose of CVarSSProfilesTransmissionUseLegacy is to provide programmatic access to the r.SSProfiles.Transmission.UseLegacy setting within the C++ code. It allows the engine to query the current state of this setting and adjust the subsurface scattering calculations accordingly.

This variable is used in the ComputeTransmissionProfileBurley function to determine whether to apply an additional scaling factor to the inverse unit scale when calculating the transmission profile. When the legacy mode is active (value 1), an additional scaling of 0.1 is applied for backward compatibility.

Developers should be aware that changing the value of CVarSSProfilesTransmissionUseLegacy at runtime will immediately affect the subsurface scattering calculations on the render thread, as it uses the ECVF_RenderThreadSafe flag.

Best practices for using CVarSSProfilesTransmissionUseLegacy include:

  1. Accessing its value using the GetValueOnAnyThread() method when needed in rendering code.
  2. Considering the implications of changing this value at runtime, especially in terms of visual consistency and potential performance impacts.
  3. Using this variable in conjunction with other subsurface scattering parameters to fine-tune the overall appearance of materials in your game or application.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/BurleyNormalizedSSS.cpp:10

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSSProfilesTransmissionUseLegacy(
	TEXT("r.SSProfiles.Transmission.UseLegacy"),
	1,
	TEXT("0. Use more physically correct transmission profile.\n")
	TEXT("1. Use legacy transmission profile (default)."),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/BurleyNormalizedSSS.cpp:9

Scope: file

Source code excerpt:

#include "HAL/IConsoleManager.h"

static TAutoConsoleVariable<int32> CVarSSProfilesTransmissionUseLegacy(
	TEXT("r.SSProfiles.Transmission.UseLegacy"),
	1,
	TEXT("0. Use more physically correct transmission profile.\n")
	TEXT("1. Use legacy transmission profile (default)."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/BurleyNormalizedSSS.cpp:266

Scope (from outer to inner):

file
function     void ComputeTransmissionProfileBurley

Source code excerpt:

	float InvUnitScale = 1.0 / UnitScale; // Scaling the unit is equivalent to inverse scaling of the profile.

	if (CVarSSProfilesTransmissionUseLegacy.GetValueOnAnyThread() == 1)
	{
		InvUnitScale *= 0.1f; // Backward compatibility
	}

	static float MaxTransmissionProfileDistance = 5.0f; // See SSSS_MAX_TRANSMISSION_PROFILE_DISTANCE in TransmissionCommon.ush
	static float CmToMm = 10.0f;