r.HeterogeneousVolumes.Shadows.CameraDownsampleFactor

r.HeterogeneousVolumes.Shadows.CameraDownsampleFactor

#Overview

name: r.HeterogeneousVolumes.Shadows.CameraDownsampleFactor

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.HeterogeneousVolumes.Shadows.CameraDownsampleFactor is to control the downsample factor for the camera volumetric shadow map in the heterogeneous volumes rendering system. This setting is part of Unreal Engine 5’s advanced rendering features, specifically for handling volumetric shadows in heterogeneous volumes.

This setting variable is primarily used by the Renderer module, particularly in the heterogeneous volumes rendering pipeline. It’s part of the volumetric shadow mapping system, which is crucial for rendering realistic shadows in complex volumetric environments.

The value of this variable is set through the console variable system. It’s initialized with a default value of 2, but can be changed at runtime using console commands or through project settings.

This variable interacts closely with other heterogeneous volumes rendering settings, particularly those related to shadow rendering. It’s associated with the C++ variable CVarHeterogeneousVolumesShadowCameraDownsampleFactor, which is used to access its value in the code.

Developers should be aware that this setting directly impacts the resolution and quality of volumetric shadows. A higher value will result in lower resolution shadows, which can improve performance but may reduce visual quality. Conversely, a lower value will increase shadow quality at the cost of performance.

Best practices when using this variable include:

  1. Balancing between performance and visual quality based on the project’s requirements.
  2. Testing different values to find the optimal setting for specific scenes or use cases.
  3. Considering the target hardware capabilities when adjusting this setting.
  4. Using it in conjunction with other shadow-related settings for best results.

Regarding the associated variable CVarHeterogeneousVolumesShadowCameraDownsampleFactor:

This is the actual C++ variable that stores and provides access to the r.HeterogeneousVolumes.Shadows.CameraDownsampleFactor setting. It’s implemented as a TAutoConsoleVariable, which allows it to be changed at runtime through console commands.

The purpose of this variable is to provide a programmatic interface to the downsample factor setting. It’s used in the rendering code to retrieve the current value of the setting and apply it to the shadow rendering process.

This variable is primarily used within the Renderer module, specifically in the heterogeneous volumes rendering pipeline. It’s accessed using the GetValueOnRenderThread() method to ensure thread-safe access in the render thread.

The value of this variable is set indirectly through the console variable system when the r.HeterogeneousVolumes.Shadows.CameraDownsampleFactor setting is changed.

Developers should be aware that this variable should only be accessed from the render thread to ensure thread safety. The GetCameraDownsampleFactor() function provides a safe way to access this value, including a safeguard to ensure the value is never less than 1.

Best practices for using this variable include:

  1. Always accessing it through the provided GetCameraDownsampleFactor() function or similar thread-safe methods.
  2. Avoiding direct modification of this variable in code; instead, use the console variable system to change its value.
  3. Consider caching the value if it’s needed frequently in performance-critical code sections to avoid repeated calls to GetValueOnRenderThread().

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesShadowCameraDownsampleFactor(
	TEXT("r.HeterogeneousVolumes.Shadows.CameraDownsampleFactor"),
	2,
	TEXT("Controls downsample factor for camera volumetric shadow map (default = 2)"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesShadowResolution(
	TEXT("r.HeterogeneousVolumes.Shadows.Resolution"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesShadowCameraDownsampleFactor(
	TEXT("r.HeterogeneousVolumes.Shadows.CameraDownsampleFactor"),
	2,
	TEXT("Controls downsample factor for camera volumetric shadow map (default = 2)"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesShadowResolution(

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

Scope (from outer to inner):

file
namespace    HeterogeneousVolumes
function     float GetCameraDownsampleFactor

Source code excerpt:

	float GetCameraDownsampleFactor()
	{
		return FMath::Max(CVarHeterogeneousVolumesShadowCameraDownsampleFactor.GetValueOnRenderThread(), 1);
	}

	float GetShadingRateForShadows()
	{
		return FMath::Max(CVarHeterogeneousVolumesShadowShadingRate.GetValueOnRenderThread(), 0.1);
	}