r.Decal.StencilSizeThreshold

r.Decal.StencilSizeThreshold

#Overview

name: r.Decal.StencilSizeThreshold

The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.

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.Decal.StencilSizeThreshold is to control an optimization for rendering large decals in screen space. This setting variable is part of Unreal Engine’s rendering system, specifically the deferred decal rendering process.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the deferred decal rendering component. This can be seen from the file location where the variable is defined and used: “CompositionLighting/PostProcessDeferredDecals.cpp”.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 0.1f, but can be changed at runtime through console commands or configuration files.

This variable interacts closely with its associated variable CVarStencilSizeThreshold. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable controls a performance optimization for large decals. The optimization adds a per-decal stencil pass, which can make rendering large decals faster but adds overhead for each decal. The variable’s value determines when this optimization is applied:

Best practices when using this variable include:

  1. Leave it at the default value (0.1) unless you’re experiencing performance issues with decals.
  2. If you have many large decals in your scene and are facing performance problems, try adjusting this value to find the optimal balance between performance and visual quality.
  3. Monitor the performance impact when changing this value, as the optimization might not always be beneficial depending on your specific use case.

Regarding the associated variable CVarStencilSizeThreshold:

The purpose of CVarStencilSizeThreshold is to provide a console-variable interface for the r.Decal.StencilSizeThreshold setting. It allows for runtime modification of the threshold value.

This variable is used in the Renderer module, specifically in the deferred decal rendering process. Its value is typically retrieved using the GetValueOnRenderThread() method, ensuring thread-safe access in the rendering code.

The value of CVarStencilSizeThreshold is set when the r.Decal.StencilSizeThreshold console variable is modified, either through console commands or configuration files.

Developers should be aware that changes to CVarStencilSizeThreshold will directly affect the behavior of the decal rendering optimization. It’s used to determine whether a decal is large enough on screen to warrant the stencil pass optimization.

Best practices for using CVarStencilSizeThreshold include:

  1. Use it for debugging or performance tuning in development builds.
  2. Be cautious about modifying it in shipping builds, as it could affect performance and visual quality.
  3. When adjusting the value, consider the typical sizes of decals in your scenes to find an optimal threshold.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:299, section: [IOS DeviceProfile]

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:547, section: [iPadPro DeviceProfile]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:19

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarStencilSizeThreshold(
	TEXT("r.Decal.StencilSizeThreshold"),
	0.1f,
	TEXT("Control a per decal stencil pass that allows to large (screen space) decals faster. It adds more overhead per decals so this\n")
	TEXT("  <0: optimization is disabled\n")
	TEXT("   0: optimization is enabled no matter how small (screen space) the decal is\n")
	TEXT("0..1: optimization is enabled, value defines the minimum size (screen space) to trigger the optimization (default 0.1)")
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:18

Scope: file

Source code excerpt:

#include "PSOPrecacheValidation.h"

static TAutoConsoleVariable<float> CVarStencilSizeThreshold(
	TEXT("r.Decal.StencilSizeThreshold"),
	0.1f,
	TEXT("Control a per decal stencil pass that allows to large (screen space) decals faster. It adds more overhead per decals so this\n")
	TEXT("  <0: optimization is disabled\n")
	TEXT("   0: optimization is enabled no matter how small (screen space) the decal is\n")
	TEXT("0..1: optimization is enabled, value defines the minimum size (screen space) to trigger the optimization (default 0.1)")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:314

Scope (from outer to inner):

file
function     static bool RenderPreStencil

Source code excerpt:

		float EstimatedDecalSize = Radius / Distance;

		float StencilSizeThreshold = CVarStencilSizeThreshold.GetValueOnRenderThread();

		// Check if it's large enough on screen
		if (EstimatedDecalSize < StencilSizeThreshold)
		{
			return false;
		}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:603

Scope (from outer to inner):

file
function     void AddDeferredDecalPass

Source code excerpt:

	const bool bVisibleDecalsInView = MeshDecalCount > 0 || SortedDecalCount > 0;
	const bool bShaderComplexity = View.Family->EngineShowFlags.ShaderComplexity;
	const bool bStencilSizeThreshold = CVarStencilSizeThreshold.GetValueOnRenderThread() >= 0;

	// Attempt to clear the D-Buffer if it's appropriate for this view.
	const EDecalDBufferMaskTechnique DBufferMaskTechnique = GetDBufferMaskTechnique(ShaderPlatform);

	const auto RenderDecals = [&](uint32 DecalIndexBegin, uint32 DecalIndexEnd, EDecalRenderTargetMode RenderTargetMode)
	{