r.Nanite.ShowMeshDrawEvents

r.Nanite.ShowMeshDrawEvents

#Overview

name: r.Nanite.ShowMeshDrawEvents

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

• type: Var
• help: Emit draw events for Nanite rasterization and materials.

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Nanite.ShowMeshDrawEvents is to control the emission of draw events for Nanite rasterization and materials in Unreal Engine 5. This setting variable is primarily used for debugging and profiling purposes within the Nanite rendering system.

This setting variable is primarily used in the Nanite rendering subsystem, which is part of Unreal Engine 5’s advanced geometry system. It’s specifically referenced in the renderer module, as evidenced by its usage in the NaniteCullRaster.cpp and NaniteShading.cpp files.

The value of this variable is set through a console variable (CVarNaniteShowDrawEvents) with an initial value of 0. It can be changed at runtime through console commands or programmatically.

The associated variable CVarNaniteShowDrawEvents directly interacts with r.Nanite.ShowMeshDrawEvents. They share the same value and purpose.

Developers must be aware that enabling this variable (setting it to a non-zero value) will cause the engine to emit additional draw events, which can impact performance. Therefore, it should primarily be used for debugging and profiling purposes, not in production builds.

Best practices for using this variable include:

1. Only enable it when necessary for debugging or profiling Nanite rendering.
2. Disable it in production builds to avoid unnecessary performance overhead.
3. Use it in conjunction with Unreal Engine’s built-in profiling tools to get a comprehensive view of Nanite rendering performance.

Regarding the associated variable CVarNaniteShowDrawEvents:

The purpose of CVarNaniteShowDrawEvents is identical to r.Nanite.ShowMeshDrawEvents. It’s an internal representation of the console variable used to control the emission of Nanite draw events.

This variable is used directly in the Nanite rendering code to determine whether to emit draw events. It’s checked in both hardware (DispatchHW) and software (DispatchSW) rendering paths, as well as in the shading code.

The value of CVarNaniteShowDrawEvents is set when the console variable r.Nanite.ShowMeshDrawEvents is initialized or changed.

Developers should treat CVarNaniteShowDrawEvents as an internal implementation detail. They should interact with the r.Nanite.ShowMeshDrawEvents console variable instead of trying to modify CVarNaniteShowDrawEvents directly.

Best practices for CVarNaniteShowDrawEvents are the same as for r.Nanite.ShowMeshDrawEvents, as they are effectively the same variable. The main difference is that CVarNaniteShowDrawEvents is used internally in the C++ code, while r.Nanite.ShowMeshDrawEvents is the exposed console variable name.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:42

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarNaniteShowDrawEvents(
	TEXT("r.Nanite.ShowMeshDrawEvents"),
	0,
	TEXT("Emit draw events for Nanite rasterization and materials."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarNaniteEnableAsyncRasterization(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:41

Scope: file

Source code excerpt:

static_assert(NANITE_MAX_INSTANCES <= MAX_INSTANCE_ID, "Nanite must be able to represent the full scene instance ID range");

TAutoConsoleVariable<int32> CVarNaniteShowDrawEvents(
	TEXT("r.Nanite.ShowMeshDrawEvents"),
	0,
	TEXT("Emit draw events for Nanite rasterization and materials."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:2534

Scope (from outer to inner):

file
namespace    Nanite
class        class FRenderer : public FSceneRenderingAllocatorObject< FRenderer >, public IRenderer
function     void DispatchHW

Source code excerpt:

				Parameters.IndirectArgs->MarkResourceAsUsed();

				const bool bShowDrawEvents = CVarNaniteShowDrawEvents.GetValueOnRenderThread() != 0;
				for (const int32 Indirection : DispatchList.Indirections)
				{
					const FRasterizerPass& RasterizerPass = RasterizerPasses[Indirection];

				#if WANTS_DRAW_MESH_EVENTS
					SCOPED_CONDITIONAL_DRAW_EVENTF(RHICmdList, HWRaster, bShowDrawEvents != 0, TEXT("%s"), GetRasterMaterialName(RasterizerPass.RasterPipeline.RasterMaterial, FixedMaterialProxy));

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:2650

Scope (from outer to inner):

file
namespace    Nanite
class        class FRenderer : public FSceneRenderingAllocatorObject< FRenderer >, public IRenderer
function     void DispatchSW

Source code excerpt:

				Parameters.IndirectArgs->MarkResourceAsUsed();

				const bool bShowDrawEvents = CVarNaniteShowDrawEvents.GetValueOnRenderThread() != 0;
				for (const int32 Indirection : DispatchList.Indirections)
				{
					const FRasterizerPass& RasterizerPass = RasterizerPasses[Indirection];

				#if WANTS_DRAW_MESH_EVENTS
					SCOPED_CONDITIONAL_DRAW_EVENTF(RHICmdList, SWRaster, bShowDrawEvents, TEXT("%s"), GetRasterMaterialName(RasterizerPass.RasterPipeline.RasterMaterial, FixedMaterialProxy));

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteShading.cpp:22

Scope: file

Source code excerpt:

DEFINE_STAT(STAT_CLP_NaniteBasePass);

extern TAutoConsoleVariable<int32> CVarNaniteShowDrawEvents;

extern int32 GSkipDrawOnPSOPrecaching;
extern int32 GNaniteShowStats;

#if WANTS_DRAW_MESH_EVENTS
static FORCEINLINE const TCHAR* GetShadingMaterialName(const FMaterialRenderProxy* InShadingMaterial)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteShading.cpp:671

Scope (from outer to inner):

file
function     inline void RecordShadingCommand

Source code excerpt:

{
#if WANTS_DRAW_MESH_EVENTS
	SCOPED_CONDITIONAL_DRAW_EVENTF(RHICmdList, SWShading, CVarNaniteShowDrawEvents.GetValueOnRenderThread() != 0, TEXT("%s"), GetShadingMaterialName(ShadingCommand.Pipeline->MaterialProxy));
#endif

	const uint32 IndirectOffset = (ShadingCommand.ShadingBin * IndirectArgStride);

	FRHIComputeShader* ComputeShaderRHI = ShadingCommand.Pipeline->ComputeShader;
	SetComputePipelineState(RHICmdList, ComputeShaderRHI);