D3D12.LockTexture2DRHIFlush

D3D12.LockTexture2DRHIFlush

#Overview

name: D3D12.LockTexture2DRHIFlush

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of D3D12.LockTexture2DRHIFlush is to control whether a render thread flush occurs when locking a 2D texture in the Direct3D 12 rendering hardware interface (RHI) of Unreal Engine 5.

This setting variable is primarily used in the D3D12RHI module, which is responsible for interfacing with the Direct3D 12 graphics API. Specifically, it affects the texture locking and unlocking operations in the rendering system.

The value of this variable is set through a console variable (CVarD3D12Texture2DRHIFlush) defined in the D3D12Texture.cpp file. It’s initialized with a default value of 0 (off) and can be changed at runtime.

This variable interacts closely with its associated variable CVarD3D12Texture2DRHIFlush. They share the same value and are used interchangeably in the code.

Developers must be aware that enabling this variable (setting it to 1) will cause a render thread flush when locking or unlocking 2D textures. This can have performance implications, as flushing the render thread can be a costly operation.

Best practices when using this variable include:

  1. Keeping it disabled (0) by default, as the comments suggest it’s likely not required on any platform.
  2. Only enabling it for testing purposes or when investigating specific rendering issues related to texture locking.
  3. Monitoring performance when enabled, as it may introduce additional overhead.

Regarding the associated variable CVarD3D12Texture2DRHIFlush:

The purpose of CVarD3D12Texture2DRHIFlush is identical to D3D12.LockTexture2DRHIFlush. It’s the actual console variable implementation that controls the behavior described above.

This variable is used in the D3D12RHI module, specifically in the texture locking and unlocking functions of the FD3D12DynamicRHI class.

Its value is set through the console variable system and can be changed at runtime.

It directly interacts with the logic in LockTexture2D_RenderThread and UnlockTexture2D_RenderThread functions, determining whether a render thread flush should occur.

Developers should be aware that this variable is marked as ECVF_RenderThreadSafe, meaning it can be safely accessed from the render thread.

Best practices for using CVarD3D12Texture2DRHIFlush align with those of D3D12.LockTexture2DRHIFlush, as they are effectively the same variable.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Texture.cpp:24

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarD3D12Texture2DRHIFlush(
	TEXT("D3D12.LockTexture2DRHIFlush"),
	0,
	TEXT("If enabled, we do RHIThread flush on LockTexture2D. Likely not required on any platform, but keeping just for testing for now")
	TEXT(" 0: off (default)\n")
	TEXT(" 1: on"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Texture.cpp:23

Scope: file

Source code excerpt:

	);

static TAutoConsoleVariable<int32> CVarD3D12Texture2DRHIFlush(
	TEXT("D3D12.LockTexture2DRHIFlush"),
	0,
	TEXT("If enabled, we do RHIThread flush on LockTexture2D. Likely not required on any platform, but keeping just for testing for now")
	TEXT(" 0: off (default)\n")
	TEXT(" 1: on"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Texture.cpp:2155

Scope (from outer to inner):

file
function     void* FD3D12DynamicRHI::LockTexture2D_RenderThread

Source code excerpt:

void* FD3D12DynamicRHI::LockTexture2D_RenderThread(class FRHICommandListImmediate& RHICmdList, FRHITexture2D* TextureRHI, uint32 MipIndex, EResourceLockMode LockMode, uint32& DestStride, bool bLockWithinMiptail, bool bNeedsDefaultRHIFlush, uint64* OutLockedByteCount)
{
	if (CVarD3D12Texture2DRHIFlush.GetValueOnRenderThread() && bNeedsDefaultRHIFlush)
	{
		QUICK_SCOPE_CYCLE_COUNTER(STAT_RHIMETHOD_LockTexture2D_Flush);
		RHICmdList.ImmediateFlush(EImmediateFlushType::FlushRHIThread);
		return RHILockTexture2D(TextureRHI, MipIndex, LockMode, DestStride, bLockWithinMiptail, OutLockedByteCount);
	}

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Texture.cpp:2176

Scope (from outer to inner):

file
function     void FD3D12DynamicRHI::UnlockTexture2D_RenderThread

Source code excerpt:

void FD3D12DynamicRHI::UnlockTexture2D_RenderThread(class FRHICommandListImmediate& RHICmdList, FRHITexture2D* TextureRHI, uint32 MipIndex, bool bLockWithinMiptail, bool bNeedsDefaultRHIFlush)
{
	if (CVarD3D12Texture2DRHIFlush.GetValueOnRenderThread() && bNeedsDefaultRHIFlush)
	{
		QUICK_SCOPE_CYCLE_COUNTER(STAT_RHIMETHOD_UnlockTexture2D_Flush);
		RHICmdList.ImmediateFlush(EImmediateFlushType::FlushRHIThread);
		RHIUnlockTexture2D(TextureRHI, MipIndex, bLockWithinMiptail);
		return;
	}