r.ShowMaterialDrawEvents

r.ShowMaterialDrawEvents

#Overview

name: r.ShowMaterialDrawEvents

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShowMaterialDrawEvents is to enable or disable the emission of draw events around every mesh draw call, providing information about the assets used. This setting is primarily used for debugging purposes in the rendering system of Unreal Engine 5.

This setting variable is mainly relied upon by the Engine and RHI (Rendering Hardware Interface) modules of Unreal Engine. It’s referenced in core engine files like UnrealEngine.cpp, SceneManagement.h, and DynamicRHI.cpp, as well as in the Vulkan RHI implementation.

The value of this variable is set through a console variable, which can be modified at runtime. It’s defined using FAutoConsoleVariableRef in UnrealEngine.cpp, allowing it to be changed via console commands or through code.

This variable interacts closely with other debugging and profiling variables, such as those related to ProfileGPU functionality. It’s often used in conjunction with other render-related console variables to fine-tune debugging output.

Developers must be aware that enabling this variable introduces severe CPU and GPU overhead. It should only be used for debugging purposes and not in production builds. The variable is typically compiled out for TEST and SHIPPING builds unless specifically allowed through additional compile-time definitions.

Best practices when using this variable include:

  1. Only enable it when necessary for debugging material-related issues.
  2. Disable it immediately after use to avoid performance impacts.
  3. Be cautious when using it in conjunction with other performance-heavy debugging tools.
  4. Remember that it may not be available in all build configurations, particularly in shipping builds.
  5. Use it in combination with profiling tools like RenderDoc or Unreal Insights for more comprehensive debugging.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

*/
static FAutoConsoleVariableRef CVARShowMaterialDrawEvents(
	TEXT("r.ShowMaterialDrawEvents"),
	GShowMaterialDrawEvents,
	TEXT("Whether to emit a draw event around every mesh draw call with information about the assets used.  Introduces severe CPU and GPU overhead when enabled, but useful for debugging."),
	ECVF_Default
);
#endif

#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/Misc/Build.h:375

Scope: file

Source code excerpt:

#endif

// 0 (default), set this to 1 to get draw events with "TOGGLEDRAWEVENTS" "r.ShowMaterialDrawEvents" and the "ProfileGPU" command working in test
#ifndef ALLOW_PROFILEGPU_IN_TEST
	#define ALLOW_PROFILEGPU_IN_TEST 0
#endif

#ifndef ALLOW_PROFILEGPU_IN_SHIPPING
	#define ALLOW_PROFILEGPU_IN_SHIPPING 0
#endif

// draw events with "TOGGLEDRAWEVENTS" "r.ShowMaterialDrawEvents" (for ProfileGPU, Pix, Razor, RenderDoc, ...) and the "ProfileGPU" command are normally compiled out for TEST and SHIPPING
#define WITH_PROFILEGPU (!(UE_BUILD_SHIPPING || UE_BUILD_TEST) || (UE_BUILD_TEST && ALLOW_PROFILEGPU_IN_TEST) || (UE_BUILD_SHIPPING && ALLOW_PROFILEGPU_IN_SHIPPING))

#ifndef ALLOW_DUMPGPU_IN_TEST
	#define ALLOW_DUMPGPU_IN_TEST 1
#endif

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

Scope (from outer to inner):

file
function     void FEngineModule::StartupModule

Source code excerpt:

	CacheWPOPrimitivesVar->SetOnChangedCallback(FConsoleVariableDelegate::CreateStatic(&OnChangeEngineCVarRequiringRecreateRenderState));

	static auto CVARShowMaterialDrawEvents = IConsoleManager::Get().FindConsoleVariable(TEXT("r.ShowMaterialDrawEvents"));
	if (CVARShowMaterialDrawEvents)
	{
		CVARShowMaterialDrawEvents->SetOnChangedCallback(FConsoleVariableDelegate::CreateStatic(&OnChangeEngineCVarRequiringRecreateRenderState));
	}

	SuspendTextureStreamingRenderTasks = &SuspendRenderAssetStreaming;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/SceneManagement.h:2760

Scope: file

Source code excerpt:

	/**
	 * true if we debug material names with SCOPED_DRAW_EVENT.
	 * Toggle with "r.ShowMaterialDrawEvents" cvar.
	 */
	extern ENGINE_API void BeginMeshDrawEvent_Inner(FRHICommandList& RHICmdList, const class FPrimitiveSceneProxy* PrimitiveSceneProxy, const struct FMeshBatch& Mesh, struct FDrawEvent& DrawEvent);
#endif

FORCEINLINE void BeginMeshDrawEvent(FRHICommandList& RHICmdList, const class FPrimitiveSceneProxy* PrimitiveSceneProxy, const struct FMeshBatch& Mesh, struct FDrawEvent& DrawEvent, bool ShowMaterialDrawEvent)
{
#if WANTS_DRAW_MESH_EVENTS
	if (ShowMaterialDrawEvent)
	{

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/DynamicRHI.cpp:492

Scope (from outer to inner):

file
function     void FDynamicRHI::EnableIdealGPUCaptureOptions

Source code excerpt:

{
	static IConsoleVariable* RHICmdBypassVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.rhicmdbypass"));
	static IConsoleVariable* ShowMaterialDrawEventVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.ShowMaterialDrawEvents"));	
	static IConsoleObject* RHIThreadEnableObj = IConsoleManager::Get().FindConsoleObject(TEXT("r.RHIThread.Enable"));
	static IConsoleCommand* RHIThreadEnableCommand = RHIThreadEnableObj ? RHIThreadEnableObj->AsCommand() : nullptr;

	const bool bShouldEnableDrawEvents = bEnabled;
	const bool bShouldEnableMaterialDrawEvents = bEnabled;
	const bool bShouldEnableRHIThread = !bEnabled;

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanDevice.cpp:92

Scope (from outer to inner):

file
function     static void EnableDrawMarkers

Source code excerpt:

static void EnableDrawMarkers()
{
	static IConsoleVariable* ShowMaterialDrawEventVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.ShowMaterialDrawEvents"));

	const bool bDrawEvents = GetEmitDrawEvents() != 0;
	const bool bMaterialDrawEvents = ShowMaterialDrawEventVar ? ShowMaterialDrawEventVar->GetInt() != 0 : false;

	UE_LOG(LogRHI, Display, TEXT("Setting GPU Capture Options: 1"));
	if (!bDrawEvents)