r.HeterogeneousVolumes.CompositeWithTranslucency.Refraction.UseAVSM

r.HeterogeneousVolumes.CompositeWithTranslucency.Refraction.UseAVSM

#Overview

name: r.HeterogeneousVolumes.CompositeWithTranslucency.Refraction.UseAVSM

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.CompositeWithTranslucency.Refraction.UseAVSM is to enable or disable the Adaptive Volumetric Shadow Map (AVSM) lookup for refraction in heterogeneous volumes when compositing with translucency.

This setting variable is primarily used in the rendering system, specifically in the distortion rendering module of Unreal Engine 5. It is part of the heterogeneous volumes feature set, which is an advanced rendering technique for complex volumetric effects.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by its location in the DistortionRendering.cpp file within the Runtime/Renderer/Private directory.

The value of this variable is set through a console variable (CVarRefractionUseAVSM) with a default value of 1 (enabled). Developers can modify this value at runtime using console commands or through project settings.

This variable interacts with other rendering parameters, particularly those related to heterogeneous volumes and translucency compositing. It is used in conjunction with the TransmittanceThreshold variable (CVarRefractionTransmittanceThreshold) to control the refraction behavior in complex volumetric scenarios.

Developers must be aware that:

  1. This feature requires the “Composite with Translucency” setting to be enabled in the Heterogeneous Volumes Project Settings.
  2. Enabling or disabling this feature may have performance implications, as AVSM lookups can be computationally expensive.
  3. The effect of this setting is render thread safe, meaning it can be changed dynamically without causing thread synchronization issues.

Best practices when using this variable include:

  1. Only enable it when working with complex volumetric effects that require high-quality refractions.
  2. Test the performance impact in your specific use case, as it may vary depending on scene complexity.
  3. Consider exposing this setting to end-users as a graphics quality option, allowing them to balance visual quality and performance.

Regarding the associated variable CVarRefractionUseAVSM:

This is the actual console variable that controls the r.HeterogeneousVolumes.CompositeWithTranslucency.Refraction.UseAVSM setting. It is defined as a TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime.

The purpose of CVarRefractionUseAVSM is to provide a programmatic way to access and modify the AVSM lookup setting for refractions in heterogeneous volumes.

It is used in the CreateDistortionPassUniformBuffer function to set the UseAVSM parameter in the distortion pass uniform buffer. This directly affects how the rendering system handles refractions in the presence of heterogeneous volumes.

Developers should be aware that:

  1. The value is accessed on the render thread (GetValueOnRenderThread()), ensuring thread-safe operations.
  2. A non-zero value enables the AVSM lookup, while zero disables it.

Best practices for using CVarRefractionUseAVSM include:

  1. Use it in render thread safe contexts to avoid potential race conditions.
  2. Consider caching the value if it’s accessed frequently to reduce overhead from repeated calls to GetValueOnRenderThread().
  3. When modifying this value programmatically, ensure it’s done in a way that respects the engine’s threading model and doesn’t cause visual artifacts or performance issues during transitions.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistortionRendering.cpp:59

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarRefractionUseAVSM(
	TEXT("r.HeterogeneousVolumes.CompositeWithTranslucency.Refraction.UseAVSM"),
	1,
	TEXT("Enables AVSM lookup (Default = 1)\n")
	TEXT("Requires enabling Heterogeneous Volumes Project Setting: 'Composite with Translucency'"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarRefractionTransmittanceThreshold(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistortionRendering.cpp:58

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRefractionUseAVSM(
	TEXT("r.HeterogeneousVolumes.CompositeWithTranslucency.Refraction.UseAVSM"),
	1,
	TEXT("Enables AVSM lookup (Default = 1)\n")
	TEXT("Requires enabling Heterogeneous Volumes Project Setting: 'Composite with Translucency'"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistortionRendering.cpp:129

Scope (from outer to inner):

file
function     TRDGUniformBufferRef<FDistortionPassUniformParameters> CreateDistortionPassUniformBuffer

Source code excerpt:

	Substrate::BindSubstrateForwardPasslUniformParameters(GraphBuilder, View, Parameters->Substrate);
	Parameters->AVSM = HeterogeneousVolumes::GetAdaptiveVolumetricCameraMapParameters(GraphBuilder, View.ViewState);
	Parameters->UseAVSM = CVarRefractionUseAVSM.GetValueOnRenderThread() != 0;
	Parameters->TransmittanceThreshold = FMath::Clamp(CVarRefractionTransmittanceThreshold.GetValueOnRenderThread(), 0.0, 1.0);

	return GraphBuilder.CreateUniformBuffer(Parameters);
}

static bool GetUseRoughRefraction()