r.GBufferDiffuseSampleOcclusion

r.GBufferDiffuseSampleOcclusion

#Overview

name: r.GBufferDiffuseSampleOcclusion

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

• type: Var
• help: Whether the gbuffer contain occlusion information for individual diffuse samples.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GBufferDiffuseSampleOcclusion is to control whether the G-buffer contains occlusion information for individual diffuse samples in the rendering system. This setting variable is primarily used in the rendering pipeline of Unreal Engine 5.

Based on the callsites, this variable is utilized in the RenderCore and Engine modules of Unreal Engine. Specifically, it affects shader compilation and G-buffer composition.

The value of this variable is set through a console variable (CVar) system, which allows for runtime configuration. It is defined as an integer with a default value of 0, indicating that the feature is disabled by default.

This variable interacts with shader compilation processes, particularly in setting shader defines. It influences the GBUFFER_HAS_DIFFUSE_SAMPLE_OCCLUSION define, which is used to conditionally compile shader code.

Developers must be aware that changing this variable can impact rendering performance and visual quality. Enabling this feature (setting to non-zero) will increase G-buffer memory usage and potentially affect rendering performance, but it may improve visual quality in certain scenarios.

Best practices when using this variable include:

1. Only enable it when necessary for specific visual effects or rendering techniques that require per-sample occlusion information.
2. Consider the performance implications, especially on lower-end hardware.
3. Test thoroughly with different values to ensure the desired visual outcome is achieved without significant performance degradation.
4. Be cautious when changing this value at runtime, as it may require shader recompilation, which can cause hitches.
5. Document any project-specific usage of this variable to ensure consistency across the development team.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarGBufferDiffuseSampleOcclusion(
	TEXT("r.GBufferDiffuseSampleOcclusion"), 0,
	TEXT("Whether the gbuffer contain occlusion information for individual diffuse samples."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
	); 

static TAutoConsoleVariable<int32> CVarDistanceFields(
	TEXT("r.DistanceFields"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:8346

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:

	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.GBufferDiffuseSampleOcclusion"));
		SET_SHADER_DEFINE(Input.Environment, GBUFFER_HAS_DIFFUSE_SAMPLE_OCCLUSION, CVar ? (CVar->GetValueOnAnyThread() != 0) : 1);
	}

	{
		SET_SHADER_DEFINE(Input.Environment, SELECTIVE_BASEPASS_OUTPUTS, IsUsingSelectiveBasePassOutputs((EShaderPlatform)Target.Platform) ? 1 : 0);
	}

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:2171

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.GBufferDiffuseSampleOcclusion"));
		if (CVar && CVar->GetValueOnAnyThread() != 0)
		{
			KeyString += TEXT("_GDSO");
		}
	}