r.VolumetricCloud.ShadowMap.RaySampleMaxCount

r.VolumetricCloud.ShadowMap.RaySampleMaxCount

#Overview

name: r.VolumetricCloud.ShadowMap.RaySampleMaxCount

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.VolumetricCloud.ShadowMap.RaySampleMaxCount is to control the maximum number of samples taken during ray marching for evaluating the cloud shadow map in Unreal Engine 5’s volumetric cloud rendering system.

This setting variable is primarily used by the rendering system, specifically in the volumetric cloud rendering module. The Unreal Engine subsystem that relies on this variable is the Renderer, as evidenced by its usage in the VolumetricCloudRendering.cpp file.

The value of this variable is set as a console variable (CVar) with an initial value of 128.0f. It can be modified at runtime through the console or through engine configuration files.

This variable interacts with other variables in the volumetric cloud rendering system:

  1. It’s used in conjunction with CloudShadowRaySampleCountScale, which is a property of the UDirectionalLightComponent class.
  2. It’s also used alongside CVarVolumetricCloudShadowMapRaySampleHorizonMultiplier in calculations for cloud shadow ray sampling.

Developers should be aware that:

  1. This variable directly impacts the quality and performance of cloud shadow rendering.
  2. It’s marked as render thread safe and scalable, meaning it can be adjusted based on performance requirements.
  3. The actual number of samples used is clamped by this maximum value, even if other factors would suggest using more samples.

Best practices when using this variable include:

  1. Balancing between visual quality and performance. Higher values will provide better shadow quality but at a higher performance cost.
  2. Considering the target hardware when setting this value, as lower-end devices may benefit from a lower maximum to ensure consistent performance.
  3. Using it in conjunction with CloudShadowRaySampleCountScale for fine-tuning shadow quality on a per-light basis.

Regarding the associated variable CVarVolumetricCloudShadowMapRaySampleMaxCount:

This is the actual console variable that stores and provides access to the r.VolumetricCloud.ShadowMap.RaySampleMaxCount value. It’s used in the same way as described above, but it’s the internal representation that the engine uses to manage this setting. When accessing this value in C++ code, developers should use CVarVolumetricCloudShadowMapRaySampleMaxCount.GetValueOnAnyThread() to retrieve the current setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VolumetricCloudRendering.cpp:148

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarVolumetricCloudShadowMapRaySampleMaxCount(
	TEXT("r.VolumetricCloud.ShadowMap.RaySampleMaxCount"), 128.0f,
	TEXT("The maximum number of samples taken while ray marching shadow rays to evaluate the cloud shadow map."),
	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<float> CVarVolumetricCloudShadowMapRaySampleHorizonMultiplier(
	TEXT("r.VolumetricCloud.ShadowMap.RaySampleHorizonMultiplier"), 2.0f,
	TEXT("The multipler on the sample count applied when the atmospheric light reach the horizon. Less pixels in the shadow map need to be traced, but rays need to travel a lot longer."),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Components/DirectionalLightComponent.h:228

Scope (from outer to inner):

file
class        class UDirectionalLightComponent : public ULightComponent

Source code excerpt:

	/**
	 * Scale the shadow map tracing sample count.
	 * The sample count resolution is still clamped according to scalability setting to 'r.VolumetricCloud.ShadowMap.RaySampleMaxCount'.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = AtmosphereAndCloud, AdvancedDisplay, meta = (UIMin = "0.25", UIMax = "8", ClampMin = "0.25", SliderExponent = 1.0))
	float CloudShadowRaySampleCountScale;

	/**
	 * Scales the lights contribution when scattered in cloud participating media. This can help counter balance the fact that our multiple scattering solution is only an approximation.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, interp, Category = AtmosphereAndCloud, meta = (HideAlphaChannel))
	FLinearColor CloudScatteredLuminanceScale;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VolumetricCloudRendering.cpp:147

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<float> CVarVolumetricCloudShadowMapRaySampleMaxCount(
	TEXT("r.VolumetricCloud.ShadowMap.RaySampleMaxCount"), 128.0f,
	TEXT("The maximum number of samples taken while ray marching shadow rays to evaluate the cloud shadow map."),
	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<float> CVarVolumetricCloudShadowMapRaySampleHorizonMultiplier(
	TEXT("r.VolumetricCloud.ShadowMap.RaySampleHorizonMultiplier"), 2.0f,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VolumetricCloudRendering.cpp:1701

Scope (from outer to inner):

file
function     void FSceneRenderer::InitVolumetricCloudsForViews
lambda-function

Source code excerpt:

					const float CloudShadowRaySampleCountScale = GetVolumetricCloudShadowRaySampleCountScale(AtmosphericLight);
					const float CloudShadowRaySampleBaseCount = 16.0f;
					const float CloudShadowRayMapSampleCount = FMath::Max(4.0f, FMath::Min(CloudShadowRaySampleBaseCount * CloudShadowRaySampleCountScale, CVarVolumetricCloudShadowMapRaySampleMaxCount.GetValueOnAnyThread()));
					const float RaySampleHorizonFactor = FMath::Max(0.0f, CVarVolumetricCloudShadowMapRaySampleHorizonMultiplier.GetValueOnAnyThread()-1.0f);
					const float HorizonFactor = FMath::Clamp(0.2f / FMath::Abs(FVector3f::DotProduct(PlanetToCameraNormUp, -AtmopshericLightDirection)), 0.0f, 1.0f);
					CloudGlobalShaderParams.CloudShadowmapSampleCount[LightIndex] = FVector4f(CloudShadowRayMapSampleCount + RaySampleHorizonFactor * CloudShadowRayMapSampleCount * HorizonFactor, 0.0f, 0.0f, 0.0f);
				}
				else
				{