r.Nanite.AllowMaskedMaterials

r.Nanite.AllowMaskedMaterials

#Overview

name: r.Nanite.AllowMaskedMaterials

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

• type: Var
• help: Whether to allow meshes using masked materials to render using Nanite.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Nanite.AllowMaskedMaterials is to control whether meshes using masked materials are allowed to render using Nanite, Unreal Engine’s virtualized geometry system.

This setting variable is primarily used in the rendering system, specifically within the Nanite subsystem of Unreal Engine 5. It’s referenced in the Engine module, particularly in the NaniteResources.cpp file, which is part of the core rendering implementation.

The value of this variable is set through the console variable system. It’s initialized with a default value of 1 (true), allowing masked materials to be rendered with Nanite by default.

The associated C++ variable GNaniteAllowMaskedMaterials directly interacts with r.Nanite.AllowMaskedMaterials. They share the same value, with the console variable controlling the C++ variable’s value.

Developers must be aware that changing this variable will trigger a recreation of render states for all components in the scene. This is evident from the FGlobalComponentRecreateRenderStateContext used in the console variable’s delegate.

Best practices when using this variable include:

1. Be cautious when changing its value at runtime, as it can impact performance due to the render state recreation.
2. Consider the visual impact on masked materials in your scene when disabling this feature.
3. Use it in conjunction with other Nanite settings for optimal rendering performance and quality.

Regarding the associated variable GNaniteAllowMaskedMaterials:

The purpose of GNaniteAllowMaskedMaterials is to provide a C++ accessible flag for the Nanite system to determine if masked materials should be rendered using Nanite.

This variable is used within the Nanite namespace, specifically in the IsMaskingAllowed function. This function likely determines whether a specific mesh or material should use Nanite rendering based on its masked status and this global setting.

The value of GNaniteAllowMaskedMaterials is set by the r.Nanite.AllowMaskedMaterials console variable, ensuring they always have the same value.

No other variables directly interact with GNaniteAllowMaskedMaterials, but it’s used in conjunction with other conditions to determine the final masking allowance.

Developers should be aware that this variable is checked as a non-zero value, so any positive integer will enable the feature. It’s also used in a thread-safe manner, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using GNaniteAllowMaskedMaterials include:

1. Avoid directly modifying this variable in C++ code; instead, use the console variable to ensure consistency.
2. Consider the performance implications of allowing or disallowing masked materials in Nanite, especially for scenes with many masked objects.
3. Use this in combination with other Nanite-related variables and world settings for fine-tuned control over Nanite rendering.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/NaniteResources.cpp:95

Scope: file

Source code excerpt:

int32 GNaniteAllowMaskedMaterials = 1;
FAutoConsoleVariableRef CVarNaniteAllowMaskedMaterials(
	TEXT("r.Nanite.AllowMaskedMaterials"),
	GNaniteAllowMaskedMaterials,
	TEXT("Whether to allow meshes using masked materials to render using Nanite."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/NaniteResources.cpp:93

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_ReadOnly);

int32 GNaniteAllowMaskedMaterials = 1;
FAutoConsoleVariableRef CVarNaniteAllowMaskedMaterials(
	TEXT("r.Nanite.AllowMaskedMaterials"),
	GNaniteAllowMaskedMaterials,
	TEXT("Whether to allow meshes using masked materials to render using Nanite."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/NaniteResources.cpp:2359

Scope (from outer to inner):

file
namespace    Nanite
function     bool IsMaskingAllowed

Source code excerpt:

	}
	
	return (GNaniteAllowMaskedMaterials != 0) && (bAllowedByWorld || bForceNaniteForMasked);
}

void FVertexFactoryResource::InitRHI(FRHICommandListBase& RHICmdList)
{
	if (DoesPlatformSupportNanite(GMaxRHIShaderPlatform))
	{