ShowFlag.HeterogeneousVolumes

ShowFlag.HeterogeneousVolumes

#Overview

name: ShowFlag.HeterogeneousVolumes

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

It is referenced in 13 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.HeterogeneousVolumes is to control the visibility and rendering of heterogeneous volumes in the Unreal Engine 5 rendering system. Heterogeneous volumes are used to represent complex, non-uniform volumetric effects in 3D space, such as fog, smoke, or other atmospheric phenomena.

This setting variable is primarily used by the rendering subsystem of Unreal Engine 5, specifically within the HeterogeneousVolumes module. It is also utilized by the Scene Capture system, as indicated by the comment “for now SHOWFLAG_ALWAYS_ACCESSIBLE because it’s exposed in SceneCapture”.

The value of this variable is set using the SHOWFLAG_FIXED_IN_SHIPPING macro, which suggests that it is typically enabled (set to 1) in shipping builds but can be toggled in development builds.

The associated variable HeterogeneousVolumes interacts closely with ShowFlag.HeterogeneousVolumes. It is used in various parts of the engine, including:

  1. The UHeterogeneousVolumeComponent class, which represents a placeable actor for heterogeneous volumes.
  2. The FHeterogeneousVolumeSceneProxy class, which handles the rendering of heterogeneous volumes.
  3. The FDeferredShadingSceneRenderer class, which manages the rendering of heterogeneous volume shadows and the volumes themselves.

Developers should be aware that:

  1. This flag affects both the visibility of heterogeneous volumes and their shadows.
  2. It is exposed in the SceneCapture system, which means it can be controlled in various rendering scenarios.
  3. The rendering of heterogeneous volumes is tied to this flag, so disabling it will prevent these volumes from being rendered.

Best practices when using this variable include:

  1. Ensure that materials used with heterogeneous volumes are compatible (use GetHeterogeneousVolumeMaterial() to check).
  2. Be mindful of the performance impact of rendering heterogeneous volumes, especially in complex scenes.
  3. Use the SceneCapture system to selectively enable or disable heterogeneous volumes in different rendering contexts if needed.

The associated variable HeterogeneousVolumes is used throughout the rendering pipeline to control various aspects of heterogeneous volume rendering, including shadow generation, voxel grid creation, and integration with other rendering features like volumetric fog. Developers should familiarize themselves with the HeterogeneousVolumes namespace and its functions to fully leverage this feature in their projects.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:193

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(1, Niagara, SFG_Advanced, NSLOCTEXT("UnrealEd", "NiagaraSF", "Niagara Renderers"))
/** HeterogeneousVolumes, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_FIXED_IN_SHIPPING(1, HeterogeneousVolumes, SFG_Advanced, NSLOCTEXT("UnrealEd", "HeterogeneousVolumesSF", "Heterogeneous Volumes"))
/** if SkeletalMeshes are getting rendered, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(SkeletalMeshes, SFG_Normal, NSLOCTEXT("UnrealEd", "SkeletalMeshesSF", "Skeletal Meshes"))
/** if the builder brush (editor) is getting rendered */
SHOWFLAG_FIXED_IN_SHIPPING(0, BuilderBrush, SFG_Hidden, NSLOCTEXT("UnrealEd", "BuilderBrushSF", "Builder Brush"))
/** Render translucency, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(Translucency, SFG_Normal, NSLOCTEXT("UnrealEd", "TranslucencySF", "Translucency"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Components/HeterogeneousVolumeComponent.h:126

Scope (from outer to inner):

file
class        class UHeterogeneousVolumeComponent : public UMeshComponent

Source code excerpt:

	static UMaterialInstanceDynamic* CreateOrCastToMID(UMaterialInterface* MaterialInterface);
	void OnSparseVolumeTextureChanged(const USparseVolumeTexture* SparseVolumeTexture);
	UMaterialInterface* GetHeterogeneousVolumeMaterial() const; // Gets the UMaterialInterface* returned by GetMaterial(0), but returns nullptr if the material is incompatible with HeterogeneousVolumes.
};

/**
 * A placeable actor that represents a heterogeneous volume.
 */
UCLASS(showcategories = (Movement, Rendering, Transformation, DataLayers, "Input|MouseInput", "Input|TouchInput"), ClassGroup = Fog, hidecategories = (Info, Object, Input), MinimalAPI)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/HeterogeneousVolumeComponent.cpp:163

Scope (from outer to inner):

file
function     FPrimitiveViewRelevance FHeterogeneousVolumeSceneProxy::GetViewRelevance

Source code excerpt:


	MaterialRelevance.SetPrimitiveViewRelevance(Result);
	Result.bDrawRelevance = IsShown(View) && View->Family->EngineShowFlags.HeterogeneousVolumes;
	Result.bOpaque = false;
	Result.bStaticRelevance = false;
	Result.bDynamicRelevance = true;
	Result.bShadowRelevance = IsShadowCast(View);
	Result.bRenderInMainPass = ShouldRenderInMainPass();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/HeterogeneousVolumeComponent.cpp:184

Scope (from outer to inner):

file
function     void FHeterogeneousVolumeSceneProxy::GetDynamicMeshElements

Source code excerpt:

	}

	if (ViewFamily.EngineShowFlags.HeterogeneousVolumes)
	{
		for (int32 ViewIndex = 0; ViewIndex < Views.Num(); ViewIndex++)
		{
			if (VisibilityMap & (1 << ViewIndex))
			{
				if (MaterialInterface)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:192

Scope: file

Source code excerpt:

/** Niagara, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_FIXED_IN_SHIPPING(1, Niagara, SFG_Advanced, NSLOCTEXT("UnrealEd", "NiagaraSF", "Niagara Renderers"))
/** HeterogeneousVolumes, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_FIXED_IN_SHIPPING(1, HeterogeneousVolumes, SFG_Advanced, NSLOCTEXT("UnrealEd", "HeterogeneousVolumesSF", "Heterogeneous Volumes"))
/** if SkeletalMeshes are getting rendered, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(SkeletalMeshes, SFG_Normal, NSLOCTEXT("UnrealEd", "SkeletalMeshesSF", "Skeletal Meshes"))
/** if the builder brush (editor) is getting rendered */
SHOWFLAG_FIXED_IN_SHIPPING(0, BuilderBrush, SFG_Hidden, NSLOCTEXT("UnrealEd", "BuilderBrushSF", "Builder Brush"))
/** Render translucency, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(Translucency, SFG_Normal, NSLOCTEXT("UnrealEd", "TranslucencySF", "Translucency"))

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderHeterogeneousVolumeShadows

Source code excerpt:

	RDG_EVENT_SCOPE(GraphBuilder, "HeterogeneousVolumeShadows");
	RDG_GPU_STAT_SCOPE(GraphBuilder, HeterogeneousVolumeShadowsStat);
	SCOPED_NAMED_EVENT(HeterogeneousVolumes, FColor::Emerald);

	TRDGUniformBufferRef<FOrthoVoxelGridUniformBufferParameters> OrthoGridUniformBuffer = nullptr;
	TRDGUniformBufferRef<FFrustumVoxelGridUniformBufferParameters> FrustumGridUniformBuffer = nullptr;
	if (HeterogeneousVolumes::GetShadowMode() == HeterogeneousVolumes::EShadowMode::VoxelGrid)
	{
		FVoxelGridBuildOptions BuildOptions;

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderHeterogeneousVolumes

Source code excerpt:

	RDG_EVENT_SCOPE(GraphBuilder, "HeterogeneousVolumes");
	RDG_GPU_STAT_SCOPE(GraphBuilder, HeterogeneousVolumesStat);
	SCOPED_NAMED_EVENT(HeterogeneousVolumes, FColor::Emerald);

	TRDGUniformBufferRef<FOrthoVoxelGridUniformBufferParameters> OrthoGridUniformBuffer = HeterogeneousVolumes::GetOrthoVoxelGridUniformBuffer(GraphBuilder, Views[0].ViewState);
	TRDGUniformBufferRef<FFrustumVoxelGridUniformBufferParameters> FrustumGridUniformBuffer = HeterogeneousVolumes::GetFrustumVoxelGridUniformBuffer(GraphBuilder, Views[0].ViewState);

	FRDGTextureRef HeterogeneousVolumeRadiance = nullptr;
	if (ShouldRenderHeterogeneousVolumesForAnyView(Views))

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderHeterogeneousVolumes

Source code excerpt:

		Desc.Format = PF_FloatRGBA;
		Desc.Flags &= ~(TexCreate_FastVRAM);
		HeterogeneousVolumeRadiance = GraphBuilder.CreateTexture(Desc, TEXT("HeterogeneousVolumes"));
		AddClearUAVPass(GraphBuilder, GraphBuilder.CreateUAV(HeterogeneousVolumeRadiance), FLinearColor::Transparent);
	}

	for (int32 ViewIndex = 0; ViewIndex < Views.Num(); ViewIndex++)
	{
		FViewInfo& View = Views[ViewIndex];

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.h:461

Scope: file

Source code excerpt:

	void PostRender(FScene& Scene, TArray<FViewInfo>& Views);

} // namespace HeterogeneousVolumes

void RenderWithLiveShading(
	FRDGBuilder& GraphBuilder,
	const FSceneTextures& SceneTextures,
	const FScene* Scene,
	const FViewInfo& View,

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

Scope (from outer to inner):

file
function     void RenderLightingCacheWithPreshadingCompute

Source code excerpt:


		// Ray data
		//PassParameters->StepSize = HeterogeneousVolumes::GetStepSize();
		PassParameters->MaxStepCount = HeterogeneousVolumes::GetMaxStepCount();
		PassParameters->bJitter = HeterogeneousVolumes::ShouldJitter();
		PassParameters->MipLevel = HeterogeneousVolumes::GetMipLevel();

		// Shadow data
		PassParameters->ForwardLightData = View.ForwardLightingResources.ForwardLightUniformBuffer;

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

Scope: file

Source code excerpt:

	}

} // namespace HeterogeneousVolumes

void CompressVolumetricShadowMap(
	FRDGBuilder& GraphBuilder,
	FViewInfo& View,
	FIntVector GroupCount,
	// Input

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

Scope (from outer to inner):

file
function     void RenderVolumetricShadowMapForCameraWithVoxelGrid

Source code excerpt:

	ShadowMapResolution.X = FMath::Max(ShadowMapResolution.X / DownsampleFactor, 1);
	ShadowMapResolution.Y = FMath::Max(ShadowMapResolution.Y / DownsampleFactor, 1);
	//ShadowMapResolution = HeterogeneousVolumes::GetShadowMapResolution();

	GroupCount = FIntVector(1);
	GroupCount.X = FMath::DivideAndRoundUp(ShadowMapResolution.X, FRenderVolumetricShadowMapForLightWithVoxelGridCS::GetThreadGroupSize2D());
	GroupCount.Y = FMath::DivideAndRoundUp(ShadowMapResolution.Y, FRenderVolumetricShadowMapForLightWithVoxelGridCS::GetThreadGroupSize2D());

	// TODO: Allocate debug data

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenTranslucencyVolumeLighting.h:39

Scope: file

Source code excerpt:

END_SHADER_PARAMETER_STRUCT()

// Used by VolumetricFog and HeterogeneousVolumes
BEGIN_GLOBAL_SHADER_PARAMETER_STRUCT(FLumenTranslucencyLightingUniforms, )
	SHADER_PARAMETER_STRUCT_INCLUDE(FLumenTranslucencyLightingParameters, Parameters)
END_GLOBAL_SHADER_PARAMETER_STRUCT()

extern FLumenTranslucencyLightingParameters GetLumenTranslucencyLightingParameters(
	FRDGBuilder& GraphBuilder,