r.HeterogeneousVolumes.Shadows

r.HeterogeneousVolumes.Shadows

#Overview

name: r.HeterogeneousVolumes.Shadows

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.HeterogeneousVolumes.Shadows is to enable or disable heterogeneous volume-casting shadows in the rendering system of Unreal Engine 5. This setting variable is primarily used in the rendering subsystem, specifically for handling heterogeneous volumes and their shadow casting capabilities.

Based on the Callsites section, this variable is utilized in the Renderer module and the RenderCore module. It’s referenced in the HeterogeneousVolumes.cpp and Shader.cpp files, indicating its importance in the rendering pipeline.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0, which means heterogeneous volume-casting shadows are disabled by default. The value can be changed at runtime through console commands.

This variable interacts with the shader compilation process, as seen in the ShaderMapAppendKeyString function. When enabled, it adds a “_HVSHADOW” suffix to the shader key string, likely triggering the compilation of specific shader variants for heterogeneous volume shadows.

Developers must be aware that this is a render thread safe and read-only variable, as indicated by the ECVF_RenderThreadSafe | ECVF_ReadOnly flags. This means it’s safe to read from multiple threads, but it should not be modified during gameplay.

Best practices when using this variable include:

  1. Only enable it when heterogeneous volume shadows are necessary for the project, as it may have performance implications.
  2. Consider the impact on shader compilation times and shader permutations when enabling this feature.
  3. Test thoroughly on target platforms to ensure compatibility and performance.

Regarding the associated variable CVarHeterogeneousVolumesShadows:

This is the actual CVar object that controls the r.HeterogeneousVolumes.Shadows setting. It’s defined in the HeterogeneousVolumes.cpp file and is used to query the current state of the setting.

The purpose of CVarHeterogeneousVolumesShadows is to provide a programmatic interface to check whether heterogeneous volume-casting shadows are enabled.

This variable is used in the ShouldHeterogeneousVolumesCastShadows() function, which likely serves as a central point for other parts of the engine to check if this feature is enabled.

Developers should use the ShouldHeterogeneousVolumesCastShadows() function rather than directly accessing the CVar when checking if the feature is enabled in C++ code. This provides a layer of abstraction and makes it easier to modify the behavior in the future if needed.

Best practices for using CVarHeterogeneousVolumesShadows include:

  1. Use the GetValueOnAnyThread() method when querying its value, as shown in the provided code.
  2. Remember that changes to this variable will affect the entire rendering pipeline, so use it judiciously.
  3. Consider performance implications when enabling this feature, especially on lower-end hardware.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesShadows(
	TEXT("r.HeterogeneousVolumes.Shadows"),
	0,
	TEXT("Enables heterogeneous volume-casting shadows (default = 0)"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);

static TAutoConsoleVariable<int32> CVarTranslucencyHeterogeneousVolumes(

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

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

	if (DoesPlatformSupportHeterogeneousVolumes(Platform))
	{
		static const auto ShadowCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HeterogeneousVolumes.Shadows"));
		if (ShadowCVar && ShadowCVar->GetValueOnAnyThread() != 0)
		{
			KeyString += TEXT("_HVSHADOW");
		}

		static const auto CompTranslucencyCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Translucency.HeterogeneousVolumes"));

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesShadows(
	TEXT("r.HeterogeneousVolumes.Shadows"),
	0,
	TEXT("Enables heterogeneous volume-casting shadows (default = 0)"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.cpp:272

Scope (from outer to inner):

file
function     bool ShouldHeterogeneousVolumesCastShadows

Source code excerpt:

bool ShouldHeterogeneousVolumesCastShadows()
{
	return CVarHeterogeneousVolumesShadows.GetValueOnAnyThread() != 0;
}

bool ShouldCompositeHeterogeneousVolumesWithTranslucency()
{
	return CVarTranslucencyHeterogeneousVolumes.GetValueOnAnyThread() != 0;
}