r.FastVRam.DBufferMask

r.FastVRam.DBufferMask

#Overview

name: r.FastVRam.DBufferMask

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

It is referenced in 11 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.FastVRam.DBufferMask is to control the texture creation flags for the DBuffer mask texture in Unreal Engine’s rendering system. This setting is part of the Fast VRAM configuration, which allows developers to optimize memory usage and performance for specific rendering features.

The DBuffer (Decal Buffer) is a rendering technique used in Unreal Engine to efficiently render decals on surfaces. The DBufferMask is a texture that helps determine which parts of the scene need to be affected by decals.

This setting variable is primarily used in the Renderer module of Unreal Engine. It affects the creation and usage of the DBuffer mask texture in various rendering passes, particularly in deferred decal rendering.

The value of this variable is set through a console variable (CVar) system. It’s defined using the FASTVRAM_CVAR macro in the SceneRendering.cpp file.

The r.FastVRam.DBufferMask variable interacts with other DBuffer-related variables, such as r.FastVRam.DBufferB and r.FastVRam.DBufferC. These variables collectively control the creation flags for different components of the DBuffer system.

Developers should be aware that changing this variable can affect the performance and memory usage of the rendering system, particularly on platforms with limited video memory. It’s important to profile and test thoroughly when adjusting these settings.

Best practices when using this variable include:

  1. Only modify it if you have a good understanding of the DBuffer system and its impact on rendering performance.
  2. Test changes across different hardware configurations to ensure consistent performance.
  3. Use it in conjunction with other FastVRam settings for a holistic approach to memory optimization.

Regarding the associated variable DBufferMask:

The purpose of DBufferMask is to represent the actual texture resource for the DBuffer mask in the rendering pipeline. It’s used in various parts of the rendering code to store and access the DBuffer mask data.

This variable is used in the Renderer module, specifically in the deferred decal rendering system and the DBuffer texture management code.

The value of DBufferMask is set during the creation of DBuffer textures, which happens as part of the scene rendering process.

DBufferMask interacts closely with other DBuffer textures like DBufferA, DBufferB, and DBufferC. It’s often used in conjunction with these textures to determine where and how decals should be applied in the scene.

Developers should be aware that the presence and usage of DBufferMask can depend on the chosen DBuffer mask technique (EDecalDBufferMaskTechnique). The texture may not be created or used if the mask technique is set to “Disabled”.

Best practices for using DBufferMask include:

  1. Ensure proper initialization and cleanup of the texture resource.
  2. Consider the impact on memory usage, especially on platforms with limited VRAM.
  3. Optimize usage in shaders to minimize texture reads when possible.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

FASTVRAM_CVAR(DBufferB, 0);
FASTVRAM_CVAR(DBufferC, 0); 
FASTVRAM_CVAR(DBufferMask, 0);
FASTVRAM_CVAR(DOFSetup, 1);
FASTVRAM_CVAR(DOFReduce, 1);
FASTVRAM_CVAR(DOFPostfilter, 1);
FASTVRAM_CVAR(PostProcessMaterial, 1);

FASTVRAM_CVAR(CustomDepth, 0);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:221

Scope (from outer to inner):

file
function     void GetDeferredDecalPassParameters

Source code excerpt:

		AddColorTarget(DBufferTextures.DBufferC, LoadAction);

		if (DBufferTextures.DBufferMask)
		{
			AddColorTarget(DBufferTextures.DBufferMask, LoadAction);
		}

		// D-Buffer always uses the resolved depth; no MSAA.
		DepthTexture = Textures.Depth.Resolve;
		break;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:731

Scope (from outer to inner):

file
function     void AddDeferredDecalPass

Source code excerpt:

		// Combine DBuffer RTWriteMasks; will end up in one texture we can load from in the base pass PS and decide whether to do the actual work or not.
		FRDGTextureRef Textures[] = { PassTextures.DBufferTextures->DBufferA, PassTextures.DBufferTextures->DBufferB, PassTextures.DBufferTextures->DBufferC };
		FRenderTargetWriteMask::Decode(GraphBuilder, View.ShaderMap, MakeArrayView(Textures), PassTextures.DBufferTextures->DBufferMask, GFastVRamConfig.DBufferMask, TEXT("DBufferMaskCombine"));
	}
}

void ExtractNormalsForNextFrameReprojection(FRDGBuilder& GraphBuilder, const FSceneTextures& SceneTextures, const TArray<FViewInfo>& Views)
{
	// save the previous frame if early motion vectors are enabled and normal reprojection is enabled, so there should be no cost if these options are off

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

Scope (from outer to inner):

file
function     FDBufferTextures CreateDBufferTextures

Source code excerpt:

		if (DBufferMaskTechnique == EDecalDBufferMaskTechnique::PerPixel)
		{
			DBufferTextures.DBufferMask = GraphBuilder.CreateTexture(TexturesDesc.DBufferMaskDesc, TEXT("DBufferMask"));
		}
	}

	return DBufferTextures;
}

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

Scope (from outer to inner):

file
function     FDBufferParameters GetDBufferParameters

Source code excerpt:

		Parameters.DBufferCTexture = DBufferTextures.DBufferC;

		if (DBufferTextures.DBufferMask)
		{
			Parameters.DBufferRenderMask = DBufferTextures.DBufferMask;
		}
	}

	return Parameters;
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DBufferTextures.h:13

Scope: file

Source code excerpt:

enum class EDecalDBufferMaskTechnique
{
	Disabled,	// DBufferMask is not enabled.
	PerPixel,	// DBufferMask is written explicitly by the shader during the DBuffer pass.
	WriteMask,	// DBufferMask is constructed after the DBuffer pass by compositing DBuffer write mask planes together in a compute shader.
};

EDecalDBufferMaskTechnique GetDBufferMaskTechnique(EShaderPlatform ShaderPlatform);

struct FDBufferTexturesDesc
{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DBufferTextures.h:35

Scope: file

Source code excerpt:

	FRDGTextureRef DBufferB = nullptr;
	FRDGTextureRef DBufferC = nullptr;
	FRDGTextureRef DBufferMask = nullptr;
};

FDBufferTexturesDesc GetDBufferTexturesDesc(FIntPoint Extent, EShaderPlatform ShaderPlatform);
FDBufferTextures CreateDBufferTextures(FRDGBuilder& GraphBuilder, FIntPoint Extent, EShaderPlatform ShaderPlatform);

BEGIN_SHADER_PARAMETER_STRUCT(FDBufferParameters, )

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

Scope: file

Source code excerpt:

FASTVRAM_CVAR(DBufferB, 0);
FASTVRAM_CVAR(DBufferC, 0); 
FASTVRAM_CVAR(DBufferMask, 0);
FASTVRAM_CVAR(DOFSetup, 1);
FASTVRAM_CVAR(DOFReduce, 1);
FASTVRAM_CVAR(DOFPostfilter, 1);
FASTVRAM_CVAR(PostProcessMaterial, 1);

FASTVRAM_CVAR(CustomDepth, 0);

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

Scope (from outer to inner):

file
function     void FFastVramConfig::Update

Source code excerpt:

	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_DBufferB, DBufferB);
	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_DBufferC, DBufferC);
	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_DBufferMask, DBufferMask);
	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_DOFSetup, DOFSetup);
	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_DOFReduce, DOFReduce);
	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_DOFPostfilter, DOFPostfilter);
	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_CustomDepth, CustomDepth);
	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_ShadowPointLight, ShadowPointLight);
	bDirty |= UpdateTextureFlagFromCVar(CVarFastVRam_ShadowPerObject, ShadowPerObject);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.h:2848

Scope: file

Source code excerpt:

	ETextureCreateFlags DBufferB;
	ETextureCreateFlags DBufferC;
	ETextureCreateFlags DBufferMask;
	ETextureCreateFlags DOFSetup;
	ETextureCreateFlags DOFReduce;
	ETextureCreateFlags DOFPostfilter;
	ETextureCreateFlags PostProcessMaterial;

	ETextureCreateFlags CustomDepth;

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

Scope (from outer to inner):

file
namespace    Substrate
function     void AddSubstrateMaterialClassificationPass

Source code excerpt:

				// Combine DBuffer RTWriteMasks; will end up in one texture we can load from in the base pass PS and decide whether to do the actual work or not.
				FRDGTextureRef SourceCMaskTextures[] = { SubstrateSceneData->TopLayerTexture };
				FRenderTargetWriteMask::Decode(GraphBuilder, View.ShaderMap, MakeArrayView(SourceCMaskTextures), TopLayerCmaskTexture, GFastVRamConfig.DBufferMask, TEXT("Substrate::TopLayerCmask"));
			}

			// If Dbuffer pass (i.e. apply DBuffer data after the base-pass) is enabled, run special classification for outputing tile with/without tiles
			const bool bDBufferTiles = IsDBufferPassEnabled(Platform) && CVarSubstrateDBufferPassDedicatedTiles.GetValueOnRenderThread() > 0 && DBufferTextures.IsValid() && IsConsolePlatform(View.GetShaderPlatform());

			FSubstrateMaterialTileClassificationPassCS::FPermutationDomain PermutationVector;