r.HairStrands.Lighting.AllowOneTransmittancePass

r.HairStrands.Lighting.AllowOneTransmittancePass

#Overview

name: r.HairStrands.Lighting.AllowOneTransmittancePass

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

• type: Var
• help: Allows one transmittance pass for hair strands lighting to have better performance (experimental).\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HairStrands.Lighting.AllowOneTransmittancePass is to optimize the performance of hair strands lighting by allowing a single transmittance pass. This setting is part of the rendering system, specifically for hair rendering and lighting.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, as evidenced by its location in the LightRendering.cpp file. It’s part of the hair strands rendering subsystem, which is responsible for realistic hair rendering in the engine.

The value of this variable is set through a console variable (CVarHairStrandsAllowOneTransmittancePass) with a default value of 1 (enabled). It can be changed at runtime through console commands or project settings.

The associated variable CVarHairStrandsAllowOneTransmittancePass directly interacts with r.HairStrands.Lighting.AllowOneTransmittancePass. They share the same value and purpose.

Developers should be aware that this feature is marked as experimental in the comments. This means it might not be fully stable or optimized for all scenarios. It’s important to test thoroughly when enabling this feature, especially in performance-critical situations.

Best practices when using this variable include:

1. Benchmark your application with and without this feature enabled to ensure it provides a performance benefit in your specific use case.
2. Monitor the visual quality of hair rendering when this feature is enabled, as performance optimizations might sometimes come at the cost of visual fidelity.
3. Consider exposing this setting in your game’s graphics options to allow users to toggle it based on their hardware capabilities.

Regarding the associated variable CVarHairStrandsAllowOneTransmittancePass:

The purpose of CVarHairStrandsAllowOneTransmittancePass is to provide a runtime-configurable way to enable or disable the single transmittance pass optimization for hair strands lighting.

This console variable is used in the Renderer module, specifically in the light rendering system. It’s checked in the RenderLights function of the FDeferredShadingSceneRenderer class.

The value of this variable is set when the engine initializes, but it can be changed at runtime through console commands.

This variable directly controls the behavior of the r.HairStrands.Lighting.AllowOneTransmittancePass setting. When its value is greater than 0, it enables the single transmittance pass optimization.

Developers should be aware that this variable affects the elision of subpixel screen shadow masks for hair strands. This could potentially impact the visual quality of shadows on hair.

Best practices for using this variable include:

1. Use it in conjunction with profiling tools to measure its impact on rendering performance.
2. Test it with various hair rendering scenarios to ensure it doesn’t introduce visual artifacts.
3. Consider creating a user-facing graphics option that toggles this setting for performance tuning.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:177

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarHairStrandsAllowOneTransmittancePass(
	TEXT("r.HairStrands.Lighting.AllowOneTransmittancePass"),
	1,
	TEXT("Allows one transmittance pass for hair strands lighting to have better performance (experimental).\n"),
	ECVF_RenderThreadSafe);

#if ENABLE_DEBUG_DISCARD_PROP
static float GDebugLightDiscardProp = 0.0f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:176

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarHairStrandsAllowOneTransmittancePass(
	TEXT("r.HairStrands.Lighting.AllowOneTransmittancePass"),
	1,
	TEXT("Allows one transmittance pass for hair strands lighting to have better performance (experimental).\n"),
	ECVF_RenderThreadSafe);

#if ENABLE_DEBUG_DISCARD_PROP

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:1581

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderLights

Source code excerpt:

						VisibleLightInfo.VirtualShadowMapId != INDEX_NONE &&	// Not a directional light, so no per-view clipmaps
						VisibleLightInfo.ContainsOnlyVirtualShadowMaps();
					bElideScreenShadowMaskSubPixel = bElideScreenShadowMask && CVarHairStrandsAllowOneTransmittancePass.GetValueOnRenderThread() > 0;

					if (!SharedScreenShadowMaskTexture || !SharedScreenShadowMaskSubPixelTexture)
					{
						const FRDGTextureDesc SharedScreenShadowMaskTextureDesc(FRDGTextureDesc::Create2D(SceneTextures.Config.Extent, PF_B8G8R8A8, FClearValueBinding::White, TexCreate_RenderTargetable | TexCreate_ShaderResource | GFastVRamConfig.ScreenSpaceShadowMask));
						
						if (!SharedScreenShadowMaskTexture && !bElideScreenShadowMask)