r.ExrReaderGPU.UseUploadHeap

r.ExrReaderGPU.UseUploadHeap

#Overview

name: r.ExrReaderGPU.UseUploadHeap

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 r.ExrReaderGPU.UseUploadHeap is to control the use of an upload heap for copying raw EXR (OpenEXR) buffer data asynchronously in the GPU-based EXR image reader. This setting is part of the image media handling system in Unreal Engine 5, specifically for processing EXR image files.

This setting variable is primarily used in the ImgMedia plugin, which is responsible for handling various image formats in Unreal Engine. The main subsystem relying on this variable is the EXR image reading and processing system within the ImgMedia module.

The value of this variable is set through a console variable (CVarExrReaderUseUploadHeap) in the ExrImgMediaReaderGpu.cpp file. It is initialized to true by default, meaning the upload heap is used by default.

The associated variable CVarExrReaderUseUploadHeap interacts directly with r.ExrReaderGPU.UseUploadHeap, as they share the same value. This console variable is used throughout the code to check the current setting and adjust behavior accordingly.

Developers must be aware of several important aspects when using this variable:

  1. Changing this setting requires a restart of the engine to take effect.
  2. When enabled, it utilizes an upload heap and copies the raw EXR buffer asynchronously, which can potentially improve performance.
  3. The setting affects how GPU buffers are allocated and used in the EXR reading process.

Best practices when using this variable include:

  1. Consider the performance implications of enabling or disabling this feature based on your specific use case and hardware capabilities.
  2. Remember to restart the engine after changing this setting to ensure it takes effect.
  3. Monitor performance metrics when working with EXR images to determine if using the upload heap is beneficial for your project.

Regarding the associated variable CVarExrReaderUseUploadHeap:

The purpose of CVarExrReaderUseUploadHeap is to provide a runtime-configurable way to control the r.ExrReaderGPU.UseUploadHeap setting. It is implemented as a console variable, allowing developers to change the setting during development or debugging.

This variable is used in the same ImgMedia plugin and EXR reading system as r.ExrReaderGPU.UseUploadHeap. It directly influences how GPU buffers are allocated and used when reading EXR images.

The value of CVarExrReaderUseUploadHeap is set when the console variable is defined, but can be changed at runtime through console commands.

CVarExrReaderUseUploadHeap interacts closely with the static bool bUseUploadHeap, which is used to force users to restart the engine after changing the setting.

Developers should be aware that while CVarExrReaderUseUploadHeap can be changed at runtime, the changes won’t take effect until the engine is restarted due to the static bUseUploadHeap variable.

Best practices for using CVarExrReaderUseUploadHeap include:

  1. Use it for debugging and performance testing during development.
  2. Document any changes made to this setting in your project, as it can affect EXR image processing performance.
  3. Be cautious when changing this setting in a shipping build, as it may have unexpected effects on performance or stability.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Media/ImgMedia/Source/ImgMedia/Private/Readers/ExrImgMediaReaderGpu.cpp:35

Scope: file

Source code excerpt:


static TAutoConsoleVariable<bool> CVarExrReaderUseUploadHeap(
	TEXT("r.ExrReaderGPU.UseUploadHeap"),
	true,
	TEXT("Utilizes upload heap and copies raw exr buffer asynchronously.\n\
			Requires a restart of the engine."));

/** This is to force user to restart after they've changed this setting. */
static bool bUseUploadHeap = CVarExrReaderUseUploadHeap.GetValueOnAnyThread();

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Media/ImgMedia/Source/ImgMedia/Private/Readers/ExrImgMediaReaderGpu.cpp:34

Scope: file

Source code excerpt:



static TAutoConsoleVariable<bool> CVarExrReaderUseUploadHeap(
	TEXT("r.ExrReaderGPU.UseUploadHeap"),
	true,
	TEXT("Utilizes upload heap and copies raw exr buffer asynchronously.\n\
			Requires a restart of the engine."));

/** This is to force user to restart after they've changed this setting. */
static bool bUseUploadHeap = CVarExrReaderUseUploadHeap.GetValueOnAnyThread();

namespace {

	/** This function is similar to DrawScreenPass in OpenColorIODisplayExtension.cpp except it is catered for Viewless texture rendering. */
	template<typename TSetupFunction>
	void DrawScreenPass(

#Loc: <Workspace>/Engine/Plugins/Media/ImgMedia/Source/ImgMedia/Private/Readers/ExrImgMediaReaderGpu.cpp:661

Scope (from outer to inner):

file
function     FStructuredBufferPoolItemSharedPtr FExrImgMediaReaderGpu::AllocateGpuBufferFromPool
lambda-function

Source code excerpt:

				AllocatedBuffer->UploadBufferMapped = RHICmdList.LockBuffer(AllocatedBuffer->UploadBufferRef, 0, AllocSize, RLM_WriteOnly);

				if (CVarExrReaderUseUploadHeap.GetValueOnAnyThread())
				{
					CreateInfo.DebugName = TEXT("ExrReaderGpu.DestBuffer");
					AllocatedBuffer->ShaderAccessBufferRef = RHICmdList.CreateStructuredBuffer(sizeof(uint16) * 2., AllocSize, BUF_ShaderResource | BUF_FastVRAM, CreateInfo);
					AllocatedBuffer->ShaderResourceView = RHICmdList.CreateShaderResourceView(AllocatedBuffer->ShaderAccessBufferRef);
				}
				else

#Loc: <Workspace>/Engine/Plugins/Media/ImgMedia/Source/ImgMedia/Private/Readers/ExrImgMediaReaderGpu.h:17

Scope: file

Source code excerpt:

	/**
	* This is the actual buffer reference that we need to keep after it is locked and until it is unlocked.
	* The buffer is used as an upload heap and will not be accessed by shader if CVarExrReaderUseUploadHeap is set.
	*/
	FBufferRHIRef UploadBufferRef;

	/** 
	* A pointer to mapped GPU memory.
	*/
	void* UploadBufferMapped;

	/**
	* This buffer is used by the swizzling shader if CVarExrReaderUseUploadHeap is set and UploadBufferRef contents are copied into it.
	*/
	FBufferRHIRef ShaderAccessBufferRef;

	/** 
	* Resource View used by swizzling shader.
	*/
	FShaderResourceViewRHIRef ShaderResourceView;