D3D12.UseUpdateTexture3DComputeShader

D3D12.UseUpdateTexture3DComputeShader

#Overview

name: D3D12.UseUpdateTexture3DComputeShader

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

• type: Var
• help: If enabled, use a compute shader for UpdateTexture3D. Avoids alignment restrictions 0: off (default)\n 1: on

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of D3D12.UseUpdateTexture3DComputeShader is to control whether a compute shader is used for updating 3D textures in the DirectX 12 rendering pipeline. This setting is specifically for the D3D12 Rendering Hardware Interface (RHI) subsystem of Unreal Engine.

The D3D12RHI module relies on this setting variable. It is used within the texture handling code of the DirectX 12 implementation.

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

This variable interacts directly with its associated variable CVarUseUpdateTexture3DComputeShader. They share the same value and purpose.

Developers must be aware that enabling this option (setting it to 1) will use a compute shader for UpdateTexture3D operations. This approach avoids alignment restrictions but may have different performance characteristics compared to the default method.

Best practices when using this variable include:

1. Only enable it if you’re experiencing issues with texture alignment in 3D textures.
2. Test performance with and without this option enabled, as it may impact rendering speed differently depending on the specific use case.
3. Be cautious when enabling this for compressed texture formats, as the code specifically checks for uncompressed formats (BlockSizeX == 1 && BlockSizeY == 1).
4. Consider the impact on different hardware configurations, as compute shader performance can vary across GPUs.

Regarding the associated variable CVarUseUpdateTexture3DComputeShader:

This is a console variable of type TAutoConsoleVariable that directly controls the D3D12.UseUpdateTexture3DComputeShader setting. It is defined in the same file (D3D12Texture.cpp) and is used to get the current value of the setting at runtime.

The purpose and usage considerations for CVarUseUpdateTexture3DComputeShader are identical to those of D3D12.UseUpdateTexture3DComputeShader. It’s used in the BeginUpdateTexture3D_Internal function to determine whether to attempt a compute shader update for 3D textures.

When working with this variable, developers should use CVarUseUpdateTexture3DComputeShader.GetValueOnRenderThread() to retrieve its current value, ensuring thread-safe access in the render thread context.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarUseUpdateTexture3DComputeShader(
	TEXT("D3D12.UseUpdateTexture3DComputeShader"),
	0,
	TEXT("If enabled, use a compute shader for UpdateTexture3D. Avoids alignment restrictions")
	TEXT(" 0: off (default)\n")
	TEXT(" 1: on"),
	ECVF_RenderThreadSafe );

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarUseUpdateTexture3DComputeShader(
	TEXT("D3D12.UseUpdateTexture3DComputeShader"),
	0,
	TEXT("If enabled, use a compute shader for UpdateTexture3D. Avoids alignment restrictions")
	TEXT(" 0: off (default)\n")
	TEXT(" 1: on"),
	ECVF_RenderThreadSafe );

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

Scope (from outer to inner):

file
function     FUpdateTexture3DData FD3D12DynamicRHI::BeginUpdateTexture3D_Internal

Source code excerpt:

	bool bDoComputeShaderCopy = false; // Compute shader can not cast compressed formats into uint
	if (CVarUseUpdateTexture3DComputeShader.GetValueOnRenderThread() != 0 && FormatInfo.BlockSizeX == 1 && FormatInfo.BlockSizeY == 1 && Texture->ResourceLocation.GetGPUVirtualAddress() && !EnumHasAnyFlags(Texture->GetFlags(), TexCreate_OfflineProcessed))
	{
		// Try a compute shader update. This does a memory allocation internally
		bDoComputeShaderCopy = BeginUpdateTexture3D_ComputeShader(UpdateData, UpdateDataD3D12);
	}

	if (!bDoComputeShaderCopy)