DumpUnbuiltLightInteractions

DumpUnbuiltLightInteractions

#Overview

name: DumpUnbuiltLightInteractions

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DumpUnbuiltLightInteractions is to log all lights and primitives that have unbuilt interactions in the scene. This is primarily used for debugging lighting issues in Unreal Engine.

This setting variable is primarily used by the rendering system, specifically within the scene management and lighting subsystems of Unreal Engine. Based on the callsites, it’s utilized in the following modules:

  1. UnrealEd (Editor)
  2. Engine (Core)
  3. Renderer

The value of this variable is not set directly, but rather it’s registered as a console command in the Engine’s console manager. This means it can be triggered by developers or users with appropriate access during runtime or in the editor.

DumpUnbuiltLightInteractions interacts with the World’s Scene object, particularly the NumLightingUnbuiltObjects variable, which keeps track of the number of unbuilt lighting objects in the scene.

Developers should be aware of the following when using this variable:

  1. It’s primarily a debugging tool and should not be relied upon for gameplay or production code.
  2. It’s only available in non-shipping and non-test builds of the engine.
  3. The output can be quite verbose, especially in large scenes with many unbuilt light interactions.

Best practices when using this variable include:

  1. Use it during development and testing phases, particularly when troubleshooting lighting issues.
  2. Combine its use with other lighting debugging tools and visualizations for a comprehensive understanding of the scene’s lighting state.
  3. Be prepared to handle and analyze potentially large amounts of output data, especially in complex scenes.
  4. Consider using it in conjunction with automated testing systems to catch lighting build issues early in the development process.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/StaticLightingSystem/StaticLightingSystem.cpp:448

Scope (from outer to inner):

file
function     void FStaticLightingManager::FinishLightingBuild

Source code excerpt:

	{
		// Everything should be built at this point, dump unbuilt interactions for debugging
		World->Scene->DumpUnbuiltLightInteractions(*GLog);
	}

	if (bBuildReflectionCapturesOnFinish)
	{
		GEditor->BuildReflectionCaptures(World);
	}

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/HAL/ConsoleManager.cpp:3356

Scope (from outer to inner):

file
function     void CreateConsoleVariables

Source code excerpt:

	IConsoleManager::Get().RegisterConsoleCommand(TEXT("VisRT"),	TEXT("GUI for visualizetexture"), ECVF_Cheat);
	IConsoleManager::Get().RegisterConsoleCommand(TEXT("HighResShot"),	TEXT("High resolution screenshots ResolutionX(int32)xResolutionY(int32) Or Magnification(float) [CaptureRegionX(int32) CaptureRegionY(int32) CaptureRegionWidth(int32) CaptureRegionHeight(int32) MaskEnabled(int32) DumpBufferVisualizationTargets(int32) CaptureHDR(int32)]\nExample: HighResShot 500x500 50 50 120 500 1 1 1"), ECVF_Cheat);
	IConsoleManager::Get().RegisterConsoleCommand(TEXT("DumpUnbuiltLightInteractions"),	TEXT("Logs all lights and primitives that have an unbuilt interaction."), ECVF_Cheat);
	IConsoleManager::Get().RegisterConsoleCommand(TEXT("Stat MapBuildData"),	TEXT(""), ECVF_Cheat);
	IConsoleManager::Get().RegisterConsoleCommand(TEXT("r.ResetViewState"), TEXT("Reset some state (e.g. TemporalAA index) to make rendering more deterministic (for automated screenshot verification)"), ECVF_Cheat);
	IConsoleManager::Get().RegisterConsoleCommand(TEXT("r.RHI.Name"),		TEXT("Show current RHI's name"), ECVF_Cheat);
	IConsoleManager::Get().RegisterConsoleCommand(TEXT("r.ResetRenderTargetsExtent"), TEXT("To reset internal render target extents"), ECVF_Cheat);
#endif // !(UE_BUILD_SHIPPING || UE_BUILD_TEST)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:12213

Scope (from outer to inner):

file
function     float DrawMapWarnings

Source code excerpt:

		else
		{
			// Use 'DumpUnbuiltLightInteractions' to investigate, if lighting is still unbuilt after a lighting build
			SmallTextItem.Text = FText::Format(LOCTEXT("LIGHTING_NEEDS_TO_BE_REBUILT_FMT", "LIGHTING NEEDS TO BE REBUILT ({0} unbuilt {0}|plural(one=object,other=objects))"), World->NumLightingUnbuiltObjects);
			bShouldDisplayCmdHint = true;
		}

		Canvas->DrawItem(SmallTextItem, FVector2D(MessageX, MessageY));
		MessageY += FontSizeY;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/SceneInterface.h:601

Scope (from outer to inner):

file
class        class FSceneInterface
function     virtual void DumpUnbuiltLightInteractions

Source code excerpt:

	virtual class FFXSystemInterface* GetFXSystem() = 0;

	virtual void DumpUnbuiltLightInteractions( FOutputDevice& Ar ) const { }

	/** Updates the scene's list of parameter collection id's and their uniform buffers. */
	virtual void UpdateParameterCollections(const TArray<class FMaterialParameterCollectionInstanceResource*>& InParameterCollections) {}

	/**
	 * Exports the scene.

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

Scope (from outer to inner):

file
function     static bool RendererExec

Source code excerpt:

#endif //SUPPORTS_VISUALIZE_TEXTURE
#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
	if (FParse::Command(&Cmd, TEXT("DumpUnbuiltLightInteractions")))
	{
		InWorld->Scene->DumpUnbuiltLightInteractions(Ar);
		return true;
	}
	else if (FParse::Command(&Cmd, TEXT("NaniteStats")))
	{
		NaniteStatsFilterExec(Cmd, Ar);
		return true;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:4708

Scope (from outer to inner):

file
function     void FScene::DumpUnbuiltLightInteractions

Source code excerpt:

}

void FScene::DumpUnbuiltLightInteractions( FOutputDevice& Ar ) const
{
	FlushRenderingCommands();

	TSet<FString> LightsWithUnbuiltInteractions;
	TSet<FString> PrimitivesWithUnbuiltInteractions;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScenePrivate.h:3372

Scope (from outer to inner):

file
class        class FScene : public FSceneInterface

Source code excerpt:

	virtual void UpdateSpeedTreeWind(double CurrentTime) override;
	virtual FRHIUniformBuffer* GetSpeedTreeUniformBuffer(const FVertexFactory* VertexFactory) const override;
	virtual void DumpUnbuiltLightInteractions( FOutputDevice& Ar ) const override;
	virtual void UpdateParameterCollections(const TArray<FMaterialParameterCollectionInstanceResource*>& InParameterCollections) override;

	virtual bool RequestGPUSceneUpdate(FPrimitiveSceneInfo& PrimitiveSceneInfo, EPrimitiveDirtyState PrimitiveDirtyState) override;
	virtual bool RequestUniformBufferUpdate(FPrimitiveSceneInfo& PrimitiveSceneInfo) override;

	virtual void RefreshNaniteRasterBins(FPrimitiveSceneInfo& PrimitiveSceneInfo) override;