ShowFlag.AmbientCubemap

ShowFlag.AmbientCubemap

#Overview

name: ShowFlag.AmbientCubemap

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

It is referenced in 25 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.AmbientCubemap is to control the visibility of the ambient cubemap in the rendering pipeline. It is used as a show flag to toggle the rendering of the ambient cubemap, which is a lighting feature that provides global illumination to the scene.

This setting variable is primarily used in the rendering system of Unreal Engine, specifically in the post-processing and lighting subsystems. Based on the callsites, it is utilized in various modules and plugins, including:

  1. The core Engine module
  2. The Renderer module
  3. The UnrealEd module (for editor-specific functionality)
  4. The Niagara plugin (for particle system visualization)
  5. The HairStrands plugin (for hair rendering)

The value of this variable is typically set through the engine’s show flags system, which allows toggling various rendering features on and off. It can be controlled programmatically or through the editor interface.

The AmbientCubemap variable interacts closely with this show flag. It represents the actual cubemap texture used for ambient lighting. The show flag controls whether this cubemap is applied in the rendering process.

Developers should be aware that:

  1. Disabling this flag will prevent the ambient cubemap from contributing to the scene lighting.
  2. It affects both runtime and editor visualization of the ambient cubemap.
  3. The flag is accessible in SceneCapture, which means it can affect captured scenes as well.

Best practices when using this variable include:

  1. Ensure the AmbientCubemap texture is set correctly when the flag is enabled.
  2. Be mindful of performance implications when enabling this feature, especially on lower-end hardware.
  3. Use it in conjunction with other lighting features for a balanced and realistic lighting setup.

Regarding the associated variable AmbientCubemap:

The purpose of AmbientCubemap is to store the actual cubemap texture used for ambient lighting in the scene. It provides a way to add global illumination to the scene by sampling from this environment map.

This variable is used across multiple Unreal Engine subsystems, including the core rendering pipeline, editor tools, and various plugins like Niagara and HairStrands.

The value of AmbientCubemap is typically set in the UThumbnailManager class, which suggests it’s used for both runtime rendering and editor previews. It can also be overridden in post-process settings.

It interacts closely with other variables such as AmbientCubemapTint and AmbientCubemapIntensity, which allow for fine-tuning of the cubemap’s contribution to the scene lighting.

Developers should be aware that:

  1. The cubemap should be in a suitable format and resolution for optimal rendering performance.
  2. Changes to this variable will affect the overall look and feel of the scene lighting.

Best practices include:

  1. Ensure the cubemap is of appropriate quality and represents the desired lighting environment.
  2. Use in conjunction with other lighting features for a more realistic result.
  3. Consider performance implications, especially when using high-resolution cubemaps.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_ALWAYS_ACCESSIBLE(TemporalAA, SFG_Advanced, NSLOCTEXT("UnrealEd", "TemporalAASF", "Temporal AA (instead FXAA)"))
/** e.g. Ambient cube map, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(AmbientCubemap, SFG_LightingFeatures, NSLOCTEXT("UnrealEd", "AmbientCubemapSF", "Ambient Cubemap"))
/** Human like eye simulation to adapt to the brightness of the view, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(EyeAdaptation, SFG_PostProcess, NSLOCTEXT("UnrealEd", "EyeAdaptationSF", "Eye Adaptation"))
/** Display a histogram of the scene HDR color */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeHDR, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeHDRSF", "HDR (Eye Adaptation)"))
/** Display the illuminance debug view for the skylight */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeSkyLightIlluminance, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeSkyLightIlluminance", "Visualize SkyLight Illuminance"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/FX/Niagara/Source/NiagaraEditor/Private/Customizations/SimCache/NiagaraRenderTargetVolumeSimCacheVisualizer.cpp:231

Scope (from outer to inner):

file
function     FSceneView* FNiagaraVolumeTextureViewportClient::CalcSceneView

Source code excerpt:

	FSceneView* SceneView = FEditorViewportClient::CalcSceneView(ViewFamily);
	FFinalPostProcessSettings::FCubemapEntry& CubemapEntry = *new(SceneView->FinalPostProcessSettings.ContributingCubemaps) FFinalPostProcessSettings::FCubemapEntry;
	CubemapEntry.AmbientCubemap = GUnrealEd->GetThumbnailManager()->AmbientCubemap;
	CubemapEntry.AmbientCubemapTintMulScaleValue = FLinearColor::White;
	return SceneView;
}

void FNiagaraVolumeTextureViewportClient::SetIsSimulateInEditorViewport(bool bInIsSimulateInEditorViewport)
{

#Loc: <Workspace>/Engine/Plugins/FX/Niagara/Source/NiagaraEditor/Private/Widgets/SNiagaraSystemViewport.cpp:621

Scope (from outer to inner):

file
function     FSceneView* FNiagaraSystemViewportClient::CalcSceneView

Source code excerpt:

	FSceneView* SceneView = FEditorViewportClient::CalcSceneView(ViewFamily);
	FFinalPostProcessSettings::FCubemapEntry& CubemapEntry = *new(SceneView->FinalPostProcessSettings.ContributingCubemaps) FFinalPostProcessSettings::FCubemapEntry;
	CubemapEntry.AmbientCubemap = GUnrealEd->GetThumbnailManager()->AmbientCubemap;
	CubemapEntry.AmbientCubemapTintMulScaleValue = FLinearColor::White;
	return SceneView;
}

void FNiagaraSystemViewportClient::SetIsSimulateInEditorViewport(bool bInIsSimulateInEditorViewport)
{

#Loc: <Workspace>/Engine/Plugins/FX/Niagara/Source/NiagaraEditor/Private/Widgets/SNiagaraSystemViewport.cpp:1326

Scope (from outer to inner):

file
function     FSceneView* FNiagaraBaselineViewportClient::CalcSceneView

Source code excerpt:

	FSceneView* SceneView = FEditorViewportClient::CalcSceneView(ViewFamily);
	FFinalPostProcessSettings::FCubemapEntry& CubemapEntry = *new(SceneView->FinalPostProcessSettings.ContributingCubemaps) FFinalPostProcessSettings::FCubemapEntry;
	CubemapEntry.AmbientCubemap = GUnrealEd->GetThumbnailManager()->AmbientCubemap;
	CubemapEntry.AmbientCubemapTintMulScaleValue = FLinearColor::White;
	return SceneView;
}

void FNiagaraBaselineViewportClient::SetIsSimulateInEditorViewport(bool bInIsSimulateInEditorViewport)
{

#Loc: <Workspace>/Engine/Plugins/Runtime/HairStrands/Source/HairStrandsEditor/Private/Widgets/SGroomEditorViewport.cpp:103

Scope (from outer to inner):

file
function     FSceneView* FGroomEditorViewportClient::CalcSceneView

Source code excerpt:

	FSceneView* SceneView = FEditorViewportClient::CalcSceneView(ViewFamily);
	FFinalPostProcessSettings::FCubemapEntry& CubemapEntry = *new(SceneView->FinalPostProcessSettings.ContributingCubemaps) FFinalPostProcessSettings::FCubemapEntry;
	CubemapEntry.AmbientCubemap = GUnrealEd->GetThumbnailManager()->AmbientCubemap;
	CubemapEntry.AmbientCubemapTintMulScaleValue = FLinearColor::White;
	return SceneView;
}

void FGroomEditorViewportClient::SetShowGrid(bool bShowGrid)
{

#Loc: <Workspace>/Engine/Source/Editor/Kismet/Private/SCSEditorViewportClient.cpp:204

Scope (from outer to inner):

file
function     FSCSEditorViewportClient::FSCSEditorViewportClient

Source code excerpt:

	PreviewScene->GetWorld()->SetBegunPlay(false);

	PreviewScene->SetSkyCubemap(GUnrealEd->GetThumbnailManager()->AmbientCubemap);
}

FSCSEditorViewportClient::~FSCSEditorViewportClient()
{
	// Ensure that an in-progress transaction is ended
	EndTransaction();

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Classes/ThumbnailRendering/ThumbnailManager.h:114

Scope (from outer to inner):

file
class        class UThumbnailManager : public UObject

Source code excerpt:


	UPROPERTY(Transient)
	TObjectPtr<class UTextureCube> AmbientCubemap;

	UPROPERTY(Transient)
	TObjectPtr<class UTexture2D> CheckerboardTexture;

public:
	//~ Begin UObject Interface

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/ThumbnailHelpers.cpp:61

Scope (from outer to inner):

file
function     FThumbnailPreviewScene::FThumbnailPreviewScene

Source code excerpt:

	AddComponent(DirectionalLight3, FTransform( FRotator(299.235,144.993, 0) ));

	SetSkyCubemap(GUnrealEd->GetThumbnailManager()->AmbientCubemap);

	// Add an infinite plane
	const float FloorPlaneScale = 10000.f;
	const FTransform FloorPlaneTransform(FRotator(-90.f,0,0), FVector::ZeroVector, FVector(FloorPlaneScale));
	UStaticMeshComponent* FloorPlaneComponent = NewObject<UStaticMeshComponent>();
	FloorPlaneComponent->SetStaticMesh( GUnrealEd->GetThumbnailManager()->EditorPlane );

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/ThumbnailManager.cpp:62

Scope (from outer to inner):

file
function     UThumbnailManager::UThumbnailManager

Source code excerpt:

		EditorSkySphere = ConstructorStatics.EditorSkySphereMesh.Object;
		FloorPlaneMaterial = ConstructorStatics.FloorPlaneMaterial.Object;
		AmbientCubemap = ConstructorStatics.DaylightAmbientCubemap.Object;

		SetupCheckerboardTexture();
	}
}

void UThumbnailManager::Initialize(void)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/Scene.h:1711

Scope: file

Source code excerpt:

	float ScreenSpaceReflectionMaxRoughness;

	/** AmbientCubemap tint color */
	UPROPERTY(interp, BlueprintReadWrite, Category="Rendering Features|Ambient Cubemap", meta=(editcondition = "bOverride_AmbientCubemapTint", DisplayName = "Tint", HideAlphaChannel))
	FLinearColor AmbientCubemapTint;

	/**
	 * To scale the Ambient cubemap brightness
	 * >=0: off, 1(default), >1 brighter

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/Scene.h:1724

Scope: file

Source code excerpt:

	/** The Ambient cubemap (Affects diffuse and specular shading), blends additively which if different from all other settings here */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Rendering Features|Ambient Cubemap", meta=(DisplayName = "Cubemap Texture"))
	TObjectPtr<class UTextureCube> AmbientCubemap;

	/** The camera shutter in seconds.*/
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Lens|Camera", meta=(ClampMin = "1.0", ClampMax = "2000.0", editcondition = "bOverride_CameraShutterSpeed", DisplayName = "Shutter Speed (1/s)"))
    float CameraShutterSpeed;

	/** The camera sensor sensitivity in ISO.*/

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:1790

Scope (from outer to inner):

file
function     void FSceneView::OverridePostProcessSettings

Source code excerpt:


		// cubemaps are getting blended additively - in contrast to other properties, maybe we should make that consistent
		if (Src.AmbientCubemap && Src.bOverride_AmbientCubemapIntensity)
		{
			FFinalPostProcessSettings::FCubemapEntry Entry;

			Entry.AmbientCubemapTintMulScaleValue = FLinearColor(1, 1, 1, 1) * Src.AmbientCubemapIntensity;

			if (Src.bOverride_AmbientCubemapTint)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:1801

Scope (from outer to inner):

file
function     void FSceneView::OverridePostProcessSettings

Source code excerpt:

			}

			Entry.AmbientCubemap = Src.AmbientCubemap;
			Dest.UpdateEntry(Entry, Weight);
		}

		IF_PP(ColorGradingLUT)
		{
			float ColorGradingIntensity = FMath::Clamp(Src.ColorGradingIntensity, 0.0f, 1.0f);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:2128

Scope (from outer to inner):

file
function     void FSceneView::EndFinalPostprocessSettings

Source code excerpt:

	}

	if(!Family->EngineShowFlags.AmbientCubemap)
	{
		FinalPostProcessSettings.ContributingCubemaps.Reset();
	}

	if(!Family->EngineShowFlags.LensFlares)
	{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShowFlags.cpp:647

Scope (from outer to inner):

file
function     void EngineShowFlagOverride

Source code excerpt:

			 DISABLE_ENGINE_SHOWFLAG(Refraction)
			 DISABLE_ENGINE_SHOWFLAG(ReflectionEnvironment)
			 DISABLE_ENGINE_SHOWFLAG(AmbientCubemap)
			 DISABLE_ENGINE_SHOWFLAG(MotionBlur)
			 DISABLE_ENGINE_SHOWFLAG(DirectLighting)
			 DISABLE_ENGINE_SHOWFLAG(Lighting)
			 DISABLE_ENGINE_SHOWFLAG(Translucency)
			 DISABLE_ENGINE_SHOWFLAG(TextRender)
			 DISABLE_ENGINE_SHOWFLAG(Particles)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/FinalPostProcessSettings.h:40

Scope (from outer to inner):

file
class        class FFinalPostProcessSettings : public FPostProcessSettings

Source code excerpt:

		FLinearColor AmbientCubemapTintMulScaleValue;
		// can be 0
		class UTexture* AmbientCubemap;

		FCubemapEntry() :
			AmbientCubemapTintMulScaleValue(FLinearColor(0, 0, 0, 0)),
			AmbientCubemap(NULL)
		{}
	};

	struct FLUTBlenderEntry
	{
		// 0..1

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/FinalPostProcessSettings.h:66

Scope (from outer to inner):

file
class        class FFinalPostProcessSettings : public FPostProcessSettings
function     void UpdateEntry

Source code excerpt:

			FCubemapEntry& Local = ContributingCubemaps[i];
			
			if(Local.AmbientCubemap == Entry.AmbientCubemap)
			{
				Local.AmbientCubemapTintMulScaleValue = FMath::Lerp(Local.AmbientCubemapTintMulScaleValue, Entry.AmbientCubemapTintMulScaleValue, Weight);
				Existing = true;
			}
			else
			{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlags.h:291

Scope: file

Source code excerpt:

	/**
	 * not optimized for speed, good for serialization and debugging
	 * @return e.g. TEXT("PostProcessingTonemapper=0,AmbientCubemap=1")
	 */
	ENGINE_API FString ToString() const;

	/**
	 * More powerful than SetSingleFlag() as it allows to set/clear multiple flags
	 * not optimized but doesn't have to be
	 * Tolerates whitespace and user error, as user might manipulate the data
	 * @param In e.g. TEXT("PostProcessing,PostProcessingTonemapper=0,AmbientCubemap=1")
	 * @return true:success, false:parse error detected
	 */
	ENGINE_API bool SetFromString(const TCHAR* In);
	
	/**
	 * @param Name e.g. TEXT("EyeAdaptation")
	 * @param CommaSeparatedNames leave 0 for normal purpose, is used internally for the grouping feature
	 * @return -1 if not found
	 */
	ENGINE_API static int32 FindIndexByName(const TCHAR* Name, const TCHAR *CommaSeparatedNames = 0);
	
	/**

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

Scope: file

Source code excerpt:

SHOWFLAG_ALWAYS_ACCESSIBLE(TemporalAA, SFG_Advanced, NSLOCTEXT("UnrealEd", "TemporalAASF", "Temporal AA (instead FXAA)"))
/** e.g. Ambient cube map, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(AmbientCubemap, SFG_LightingFeatures, NSLOCTEXT("UnrealEd", "AmbientCubemapSF", "Ambient Cubemap"))
/** Human like eye simulation to adapt to the brightness of the view, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(EyeAdaptation, SFG_PostProcess, NSLOCTEXT("UnrealEd", "EyeAdaptationSF", "Eye Adaptation"))
/** Display a histogram of the scene HDR color */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeHDR, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeHDRSF", "HDR (Eye Adaptation)"))
/** Display the illuminance debug view for the skylight */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeSkyLightIlluminance, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeSkyLightIlluminance", "Visualize SkyLight Illuminance"))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/AmbientCubemapParameters.h:14

Scope: file

Source code excerpt:

	SHADER_PARAMETER(FLinearColor, AmbientCubemapColor)
	SHADER_PARAMETER(FVector4f, AmbientCubemapMipAdjust)
	SHADER_PARAMETER_TEXTURE(TextureCube, AmbientCubemap)
	SHADER_PARAMETER_SAMPLER(SamplerState, AmbientCubemapSampler)
END_SHADER_PARAMETER_STRUCT()

void SetupAmbientCubemapParameters(const FFinalPostProcessSettings::FCubemapEntry& Entry, FAmbientCubemapParameters* OutParameters);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessAmbient.cpp:11

Scope (from outer to inner):

file
function     void SetupAmbientCubemapParameters

Source code excerpt:

		float MipCount = 0;

		if(Entry.AmbientCubemap)
		{
			int32 CubemapWidth = Entry.AmbientCubemap->GetSurfaceWidth();
			MipCount = FMath::Log2(static_cast<float>(CubemapWidth)) + 1.0f;
		}

		OutParameters->AmbientCubemapColor = Entry.AmbientCubemapTintMulScaleValue;

		OutParameters->AmbientCubemapMipAdjust.X =  1.0f - GDiffuseConvolveMipLevel / MipCount;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessAmbient.cpp:27

Scope (from outer to inner):

file
function     void SetupAmbientCubemapParameters

Source code excerpt:

	// cubemap texture
	{
		FTexture* AmbientCubemapTexture = Entry.AmbientCubemap ? Entry.AmbientCubemap->GetResource() : (FTexture*)GBlackTextureCube;
		OutParameters->AmbientCubemap = AmbientCubemapTexture->TextureRHI;
		OutParameters->AmbientCubemapSampler = AmbientCubemapTexture->SamplerStateRHI;
	}
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IndirectLightRendering.cpp:1634

Scope (from outer to inner):

file
lambda-function
lambda-function

Source code excerpt:

					{
						FAmbientCubemapCompositePS::FParameters ShaderParameters = *PassParameters;
						SetupAmbientCubemapParameters(CubemapEntry, &ShaderParameters.AmbientCubemap);
						SetShaderParameters(RHICmdList, PixelShader, PixelShader.GetPixelShader(), ShaderParameters);
					
						if (bSubstrateEnabled)
						{
							SetShaderParameters(RHICmdList, TileVertexShader, TileVertexShader.GetVertexShader(), PassParameters->SubstrateTile);
							RHICmdList.DrawPrimitiveIndirect(PassParameters->SubstrateTile.TileIndirectBuffer->GetIndirectRHICallBuffer(), Substrate::TileTypeDrawIndirectArgOffset(TileType));

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:3834

Scope (from outer to inner):

file
function     void FSceneRenderer::OnRenderFinish

Source code excerpt:

				{
					// platform configuration can't be loaded from the rendering thread, therefore the warning wont be displayed for TMGS_FromTextureGroup settings
					if (ContributingCubemap.AmbientCubemap &&
						ContributingCubemap.AmbientCubemap->MipGenSettings != TMGS_FromTextureGroup &&
						ContributingCubemap.AmbientCubemap->MipGenSettings != TMGS_Angular)
					{
						bShowAmbientCubemapMipGenSettingsWarning = true;
						break;
					}
				}
#endif

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentLighting.cpp:951

Scope (from outer to inner):

file
function     void InjectTranslucencyLightingVolumeAmbientCubemap

Source code excerpt:

			{
				auto* PassParameters = GraphBuilder.AllocParameters<FInjectAmbientCubemapPS::FParameters>();
				SetupAmbientCubemapParameters(CubemapEntry, &PassParameters->AmbientCubemap);
				PassParameters->RenderTargets[0] = FRenderTargetBinding(VolumeAmbientTexture, ERenderTargetLoadAction::ELoad);
				PassParameters->View = View.ViewUniformBuffer;

				GraphBuilder.AddPass(
					RDG_EVENT_NAME("Cascade %d", VolumeCascadeIndex),
					PassParameters,