r.OIT.SortedTriangles.Pool

r.OIT.SortedTriangles.Pool

#Overview

name: r.OIT.SortedTriangles.Pool

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

• type: Var
• help: Enable index buffer pool allocation which reduce creation/deletion time by re-use buffers.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.OIT.SortedTriangles.Pool is to enable index buffer pool allocation for Order-Independent Transparency (OIT) in Unreal Engine’s rendering system. This setting is designed to reduce creation and deletion time of index buffers by reusing them.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the OIT (Order-Independent Transparency) subsystem. It affects the allocation and management of sorted triangle index buffers used in rendering transparent objects.

The value of this variable is set through the console variable system in Unreal Engine. It can be modified at runtime using console commands or through configuration files.

The associated variable CVarOIT_SortedTriangles_Pool interacts directly with r.OIT.SortedTriangles.Pool. They share the same value and are used interchangeably in the code.

Developers should be aware that enabling this feature (by setting the value to greater than 0) will change the behavior of index buffer allocation for OIT. Instead of creating and deleting index buffers for each use, the system will maintain a pool of reusable buffers. This can potentially improve performance by reducing memory allocation overhead, but it may also increase memory usage if many buffers are kept in the pool.

Best practices when using this variable include:

1. Monitor performance and memory usage when enabling this feature to ensure it provides benefits for your specific use case.
2. Consider adjusting the related r.OIT.SortedTriangles.Pool.ReleaseFrameThreshold variable to control how long unused buffers are kept in the pool.
3. Be cautious when modifying this setting in shipping builds, as it may affect rendering performance and memory usage.

Regarding the associated variable CVarOIT_SortedTriangles_Pool:

The purpose of CVarOIT_SortedTriangles_Pool is identical to r.OIT.SortedTriangles.Pool. It’s an internal representation of the console variable used within the C++ code.

This variable is used directly in the OIT rendering code to check if the pool allocation feature is enabled. It’s accessed in various functions related to allocating, deallocating, and managing sorted index buffers for OIT.

The value of CVarOIT_SortedTriangles_Pool is set automatically when r.OIT.SortedTriangles.Pool is modified through the console variable system.

CVarOIT_SortedTriangles_Pool interacts closely with CVarOIT_SortedTriangles_PoolReleaseThreshold, which controls the threshold for releasing unused buffers from the pool.

Developers should be aware that this variable is accessed on both the render thread and potentially other threads, so thread safety considerations are important when modifying or reading its value.

Best practices for using CVarOIT_SortedTriangles_Pool include:

1. Use the GetValueOnRenderThread() method when accessing the value on the render thread for consistency and thread safety.
2. Be cautious about changing the value during runtime, as it may affect ongoing rendering operations.
3. Consider the performance implications of enabling or disabling this feature, especially in performance-critical sections of the rendering pipeline.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/OIT/OIT.cpp:33

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarOIT_SortedTriangles_Pool(
	TEXT("r.OIT.SortedTriangles.Pool"), 
	0, 
	TEXT("Enable index buffer pool allocation which reduce creation/deletion time by re-use buffers."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOIT_SortedTriangles_PoolReleaseThreshold(
	TEXT("r.OIT.SortedTriangles.Pool.ReleaseFrameThreshold"), 

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/OIT/OIT.cpp:32

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOIT_SortedTriangles_Pool(
	TEXT("r.OIT.SortedTriangles.Pool"), 
	0, 
	TEXT("Enable index buffer pool allocation which reduce creation/deletion time by re-use buffers."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOIT_SortedTriangles_PoolReleaseThreshold(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/OIT/OIT.cpp:342

Scope (from outer to inner):

file
function     void FOITSceneData::Allocate

Source code excerpt:

	const uint32 NumIndices = InMeshElement.NumPrimitives * 3; // Sorted index always has triangle list topology
	FSortedIndexBuffer* OITIndexBuffer = nullptr;
	if (CVarOIT_SortedTriangles_Pool.GetValueOnRenderThread() > 0)
	{
		for (uint32 FreeIt=0,FreeCount=FreeBuffers.Num(); FreeIt<FreeCount; ++FreeIt)
		{		
			FSortedIndexBuffer* FreeBuffer = FreeBuffers[FreeIt];
			// TODO: check for format as well + more robust comparison
			if (FreeBuffer != nullptr && FreeBuffer->NumIndices >= NumIndices && FreeBuffer->Id == FSortedIndexBuffer::InvalidId) 

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/OIT/OIT.cpp:394

Scope (from outer to inner):

file
function     void FOITSceneData::Deallocate

Source code excerpt:

		if (Slot < uint32(Allocations.Num()))
		{
			if (CVarOIT_SortedTriangles_Pool.GetValueOnAnyThread() > 0)
			{
				OITIndexBuffer->Id = FSortedIndexBuffer::InvalidId;
				OITIndexBuffer->LastUsedFrameId = FrameIndex;
				FreeBuffers.Add(OITIndexBuffer);
				Allocations[Slot] = FSortedTriangleData();
			}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/OIT/OIT.cpp:907

Scope (from outer to inner):

file
class        class FOITSortTriangleIndex_WriteOutCS : public FGlobalShader

Source code excerpt:

		// Trim unused buffers
		OITSceneData.FrameIndex = View.Family->FrameNumber;
		if (CVarOIT_SortedTriangles_Pool.GetValueOnRenderThread() > 0 && CVarOIT_SortedTriangles_PoolReleaseThreshold.GetValueOnRenderThread() > 0)
		{
			TrimSortedIndexBuffers(OITSceneData.FreeBuffers, OITSceneData.PendingDeletes, OITSceneData.FrameIndex);
		}
	}

	FOITData CreateOITData(FRDGBuilder& GraphBuilder, const FViewInfo& View, EOITPassType PassType)