au.compression.AsyncCompression

au.compression.AsyncCompression

#Overview

name: au.compression.AsyncCompression

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.compression.AsyncCompression is to control whether asynchronous compression of USoundWave is allowed when supported by the audio codec in Unreal Engine 5.

This setting variable is primarily used in the audio system of Unreal Engine, specifically in the audio compression and derived data generation subsystem. It is referenced in the Engine module, particularly in the AudioDerivedData.cpp file.

The value of this variable is set through a console variable (CVar) system. It is initialized to 1 (enabled) by default, but can be changed at runtime or through configuration files.

The au.compression.AsyncCompression variable interacts directly with the AllowAsyncCompression variable. They share the same value, with AllowAsyncCompression being the actual int32 variable used in the code, while au.compression.AsyncCompression is the console variable name used for external access and configuration.

Developers must be aware that this variable affects the behavior of audio compression, particularly for USoundWave objects. When enabled (set to 1), it allows asynchronous compression of audio data when the codec supports it. When disabled (set to 0), it forces synchronous compression.

Best practices when using this variable include:

  1. Keep it enabled (1) for better performance in most cases, especially on multi-core systems.
  2. Consider disabling it (0) if you encounter issues with audio compression or need deterministic behavior in audio processing.
  3. Be aware that changing this setting might affect build times and runtime performance of audio-related tasks.

Regarding the associated variable AllowAsyncCompression:

The purpose of AllowAsyncCompression is to serve as the actual int32 variable that controls the async compression behavior within the C++ code.

It is used directly in the Engine module, specifically in the audio derivation and compression systems. The IsBuildThreadsafe() function of FDerivedAudioDataCompressor uses this variable to determine if parallel building of audio data is allowed.

The value of AllowAsyncCompression is set through the au.compression.AsyncCompression console variable.

AllowAsyncCompression interacts with the CookInputs->Compressor object, checking if parallel build is supported by the compressor when async compression is enabled.

Developers should be aware that this variable directly affects the thread safety of audio data building processes. It’s crucial for determining whether audio compression can be performed asynchronously.

Best practices for AllowAsyncCompression include:

  1. Avoid modifying it directly in code; instead, use the au.compression.AsyncCompression console variable.
  2. When implementing custom audio compressors, ensure they properly support or handle the async compression setting.
  3. Consider the implications on thread safety and performance when this variable is enabled or disabled.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDerivedData.cpp:34

Scope: file

Source code excerpt:

static int32 AllowAsyncCompression = 1;
FAutoConsoleVariableRef CVarAllowAsyncCompression(
	TEXT("au.compression.AsyncCompression"),
	AllowAsyncCompression,
	TEXT("1: Allow async compression of USoundWave when supported by the codec.\n")
	TEXT("0: Disable async compression."),
	ECVF_Default);

#define FORCE_RESAMPLE 0

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

DEFINE_LOG_CATEGORY_STATIC(LogAudioDerivedData, Log, All);

static int32 AllowAsyncCompression = 1;
FAutoConsoleVariableRef CVarAllowAsyncCompression(
	TEXT("au.compression.AsyncCompression"),
	AllowAsyncCompression,
	TEXT("1: Allow async compression of USoundWave when supported by the codec.\n")
	TEXT("0: Disable async compression."),
	ECVF_Default);

#define FORCE_RESAMPLE 0

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDerivedData.cpp:2096

Scope (from outer to inner):

file
function     bool FDerivedAudioDataCompressor::IsBuildThreadsafe

Source code excerpt:

bool FDerivedAudioDataCompressor::IsBuildThreadsafe() const
{
	return AllowAsyncCompression && CookInputs->Compressor ? CookInputs->Compressor->AllowParallelBuild() : false;
}

bool FDerivedAudioDataCompressor::Build(TArray<uint8>& OutData)
{
	TRACE_CPUPROFILER_EVENT_SCOPE(FDerivedAudioDataCompressor::Build);