Tex.AsyncDXTBlocksPerBatch

Tex.AsyncDXTBlocksPerBatch

#Overview

name: Tex.AsyncDXTBlocksPerBatch

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 Tex.AsyncDXTBlocksPerBatch is to control the number of blocks to compress in parallel for DXT texture compression. This setting variable is primarily used in the texture compression system of Unreal Engine 5.

Based on the Callsites section, this setting variable is used in the TextureFormatDXT module, which is part of Unreal Engine’s texture compression subsystem. Specifically, it’s used in the CompressionSettings namespace within the TextureFormatDXT.cpp file.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be adjusted at runtime through the console or configuration files. The default value is set to 2048 blocks per batch.

This variable interacts closely with the associated variable BlocksPerBatch. They share the same value, and BlocksPerBatch is used directly in the texture compression logic.

Developers should be aware that this variable affects the parallelism of DXT compression. A higher value may improve compression speed but could also increase memory usage during compression.

Best practices when using this variable include:

  1. Adjusting it based on the target hardware’s capabilities.
  2. Monitoring performance and memory usage when changing this value.
  3. Considering the typical texture sizes in your project when setting this value.

Regarding the associated variable BlocksPerBatch:

The purpose of BlocksPerBatch is to determine the number of texture blocks processed in a single batch during DXT compression.

It’s used in the CompressImageUsingNVTT function to calculate the number of batches and rows per batch for the compression process.

The value of BlocksPerBatch is set by the Tex.AsyncDXTBlocksPerBatch console variable.

BlocksPerBatch interacts with other variables in the compression process, such as ImageBlocksX and ImageBlocksY, to determine the batching strategy.

Developers should be aware that the actual number of blocks per batch may be adjusted based on the image dimensions. The code ensures that BlocksPerBatch is at least as large as ImageBlocksX and is rounded up to a power of two.

Best practices for BlocksPerBatch include:

  1. Ensuring it’s set to a value that balances compression speed and memory usage.
  2. Considering adjusting it based on the typical texture sizes in your project.
  3. Monitoring its impact on compression performance, especially for large textures.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/TextureFormatDXT/Private/TextureFormatDXT.cpp:285

Scope (from outer to inner):

file
namespace    CompressionSettings

Source code excerpt:

	int32 BlocksPerBatch = 2048;
	FAutoConsoleVariableRef BlocksPerBatch_CVar(
		TEXT("Tex.AsyncDXTBlocksPerBatch"),
		BlocksPerBatch,
		TEXT("The number of blocks to compress in parallel for DXT compression.")
		);
}

/**

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/TextureFormatDXT/Private/TextureFormatDXT.cpp:283

Scope (from outer to inner):

file
namespace    CompressionSettings

Source code excerpt:

namespace CompressionSettings
{
	int32 BlocksPerBatch = 2048;
	FAutoConsoleVariableRef BlocksPerBatch_CVar(
		TEXT("Tex.AsyncDXTBlocksPerBatch"),
		BlocksPerBatch,
		TEXT("The number of blocks to compress in parallel for DXT compression.")
		);
}

/**
 * Compresses an image using NVTT.

#Loc: <Workspace>/Engine/Source/Developer/TextureFormatDXT/Private/TextureFormatDXT.cpp:320

Scope (from outer to inner):

file
function     static bool CompressImageUsingNVTT

Source code excerpt:

	const int32 ImageBlocksX = FMath::Max( FMath::DivideAndRoundUp( SizeX , BlockSizeX), 1);
	const int32 ImageBlocksY = FMath::Max( FMath::DivideAndRoundUp( SizeY , BlockSizeY), 1);
	const int32 BlocksPerBatch = FMath::Max<int32>(ImageBlocksX, FMath::RoundUpToPowerOfTwo(CompressionSettings::BlocksPerBatch));
	const int32 RowsPerBatch = BlocksPerBatch / ImageBlocksX;
	const int32 NumBatches = ImageBlocksY / RowsPerBatch;
	// these round down, then if (RowsPerBatch * NumBatches) != ImageBlocksY , will encode without batches

	// nvtt doesn't support 64-bit output sizes.
	int64 OutDataSize = (int64)ImageBlocksX * ImageBlocksY * BlockBytes;
	if (OutDataSize > MAX_uint32)

#Loc: <Workspace>/Engine/Source/Developer/TextureFormatDXT/Private/TextureFormatDXT.cpp:336

Scope (from outer to inner):

file
function     static bool CompressImageUsingNVTT

Source code excerpt:

	OutCompressedData.AddUninitialized(OutDataSize);

	if (ImageBlocksX * ImageBlocksY <= BlocksPerBatch ||
		BlocksPerBatch % ImageBlocksX != 0 ||
		RowsPerBatch * NumBatches != ImageBlocksY)
	{
		FNVTTCompressor* Compressor = NULL;
		{
			Compressor = new FNVTTCompressor(
				SourceData,