r.SSS.Checkerboard

r.SSS.Checkerboard

#Overview

name: r.SSS.Checkerboard

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.SSS.Checkerboard is to control the checkerboard rendering for subsurface profile rendering in Unreal Engine 5. This setting variable is primarily used in the rendering system, specifically for subsurface scattering (SSS) effects.

This setting variable is relied upon by the Renderer module of Unreal Engine, particularly in the post-processing subsystem for subsurface scattering. It is referenced in the PostProcessSubsurface.cpp file, which is part of the rendering pipeline.

The value of this variable is set through a console variable (CVarSSSCheckerboard) with a default value of 2. It can be changed at runtime through console commands or programmatically.

The associated variable CVarSSSCheckerboard interacts directly with r.SSS.Checkerboard, as they share the same value. This console variable is used to retrieve the current setting value in the render thread.

Developers must be aware of the following when using this variable:

  1. It affects the quality and performance of subsurface scattering effects.
  2. The setting has three possible values (0, 1, 2) with different implications:
    • 0: Disabled (high quality)
    • 1: Enabled (low quality)
    • 2: Automatic

Best practices when using this variable include:

  1. Use the automatic setting (2) unless specific requirements dictate otherwise.
  2. Be cautious when using the disabled setting (0) with render target formats that lack an alpha channel, as it may lead to over-washed SSS effects.
  3. Consider the trade-off between quality and performance when choosing between enabled (1) and disabled (0) settings.

Regarding the associated variable CVarSSSCheckerboard: The purpose of CVarSSSCheckerboard is to provide a programmatic interface to access and modify the r.SSS.Checkerboard setting. It is used internally by the rendering system to determine the current state of checkerboard rendering for subsurface scattering.

This console variable is used in the Renderer module, specifically in the IsSubsurfaceCheckerboardFormat function, to determine whether checkerboard rendering should be applied based on the current setting.

The value of CVarSSSCheckerboard is set when the r.SSS.Checkerboard console variable is initialized, and it can be modified through console commands or programmatically.

Developers should be aware that changes to CVarSSSCheckerboard will directly affect the behavior of subsurface scattering rendering. They should use the GetValueOnRenderThread() method to safely access its value in render thread code.

Best practices for using CVarSSSCheckerboard include:

  1. Access its value using GetValueOnRenderThread() in render thread code to ensure thread safety.
  2. Consider the performance implications when modifying this value at runtime.
  3. Use it in conjunction with checks for render target format compatibility to ensure optimal subsurface scattering quality.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessSubsurface.cpp:87

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


	TAutoConsoleVariable<int32> CVarSSSCheckerboard(
		TEXT("r.SSS.Checkerboard"),
		2,
		TEXT("Enables or disables checkerboard rendering for subsurface profile rendering.\n")
		TEXT("This is necessary if SceneColor does not include a floating point alpha channel (e.g 32-bit formats)\n")
		TEXT(" 0: Disabled (high quality). If the rendertarget format does not have an alpha channel (e.g., PF_FloatR11G11B10), it leads to over-washed SSS. \n")
		TEXT(" 1: Enabled (low quality). Surface lighting will be at reduced resolution.\n")
		TEXT(" 2: Automatic. Non-checkerboard lighting will be applied if we have a suitable rendertarget format\n"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessSubsurface.cpp:86

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	);

	TAutoConsoleVariable<int32> CVarSSSCheckerboard(
		TEXT("r.SSS.Checkerboard"),
		2,
		TEXT("Enables or disables checkerboard rendering for subsurface profile rendering.\n")
		TEXT("This is necessary if SceneColor does not include a floating point alpha channel (e.g 32-bit formats)\n")
		TEXT(" 0: Disabled (high quality). If the rendertarget format does not have an alpha channel (e.g., PF_FloatR11G11B10), it leads to over-washed SSS. \n")
		TEXT(" 1: Enabled (low quality). Surface lighting will be at reduced resolution.\n")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessSubsurface.cpp:330

Scope (from outer to inner):

file
function     bool IsSubsurfaceCheckerboardFormat

Source code excerpt:

		return false;
	}
	int CVarValue = CVarSSSCheckerboard.GetValueOnRenderThread();
	if (CVarValue == 0)
	{
		return false;
	}
	else if (CVarValue == 1)
	{