au.Quartz.bAlwaysTakeVoiceSlot

au.Quartz.bAlwaysTakeVoiceSlot

#Overview

name: au.Quartz.bAlwaysTakeVoiceSlot

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.Quartz.bAlwaysTakeVoiceSlot is to control the behavior of voice slot allocation in the Unreal Engine’s audio system, specifically for the Quartz subsystem. This setting determines whether audio play requests should be immediately forwarded to the audio engine or if they should be cached on the component until closer to the playback deadline.

This setting variable is primarily used by the audio system within Unreal Engine, specifically the Quartz subsystem which handles timing and synchronization for audio playback. It is referenced in the AudioComponent module, which is part of the Engine’s core audio functionality.

The value of this variable is set using a console variable (CVar) system. It is initialized with a default value of 1 (true) and can be changed at runtime through console commands or configuration files.

The associated variable bAlwaysTakeVoiceSlotCVar directly interacts with au.Quartz.bAlwaysTakeVoiceSlot. They share the same value, with bAlwaysTakeVoiceSlotCVar being the actual integer storage for the setting.

Developers must be aware that this variable affects the timing of when audio requests are sent to the audio engine. When set to 1 (default), it will always forward requests immediately, which may result in rendering silent voices before the actual playback time. When set to 0, it will attempt to cache play requests on the component until closer to the deadline, potentially optimizing performance but introducing a slight delay in audio responsiveness.

Best practices when using this variable include:

  1. Keep it at the default value (1) unless you’re experiencing performance issues related to audio processing.
  2. If you decide to change it to 0, thoroughly test your game’s audio behavior to ensure that the slight delay in audio responsiveness doesn’t negatively impact the user experience.
  3. Consider the trade-off between immediate audio responsiveness and potential performance optimization when deciding whether to modify this setting.

Regarding the associated variable bAlwaysTakeVoiceSlotCVar:

The purpose of bAlwaysTakeVoiceSlotCVar is to serve as the actual storage for the au.Quartz.bAlwaysTakeVoiceSlot setting. It is an integer variable that directly controls the behavior described above.

This variable is used within the AudioComponent module of the Unreal Engine. It’s referenced in the PlayQuantized function of the UAudioComponent class, influencing how audio requests are processed.

The value of bAlwaysTakeVoiceSlotCVar is set through the CVar system, mirroring the value of au.Quartz.bAlwaysTakeVoiceSlot.

bAlwaysTakeVoiceSlotCVar interacts directly with the logic in the PlayQuantized function, determining whether to immediately take a voice slot or potentially cache the request.

Developers should be aware that modifying bAlwaysTakeVoiceSlotCVar directly is not recommended. Instead, they should use the au.Quartz.bAlwaysTakeVoiceSlot console variable to change this setting.

Best practices for bAlwaysTakeVoiceSlotCVar include:

  1. Treat it as a read-only variable in your code.
  2. Use the au.Quartz.bAlwaysTakeVoiceSlot console variable to modify its value if needed.
  3. Be cautious about changing its value in performance-critical sections of code, as it could impact audio behavior and performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/AudioComponent.cpp:48

Scope: file

Source code excerpt:

static int32 bAlwaysTakeVoiceSlotCVar = 1;
FAutoConsoleVariableRef bCVarAlwaysTakeVoiceSlot(
	TEXT("au.Quartz.bAlwaysTakeVoiceSlot"),
	bAlwaysTakeVoiceSlotCVar,
	TEXT("Always take voice slot immediately without trying to cache the request on the component\n")
	TEXT("default = 1: always forward the request to the audio engine immediately. - 0: attempt to cache play requests on the component until closer to the deadline."),
	ECVF_Default);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/AudioComponent.cpp:46

Scope: file

Source code excerpt:


//CVar to disable the gamethread-side caching of play requests to minimize time spent rendering a silent voice before the Quartz Deadline
static int32 bAlwaysTakeVoiceSlotCVar = 1;
FAutoConsoleVariableRef bCVarAlwaysTakeVoiceSlot(
	TEXT("au.Quartz.bAlwaysTakeVoiceSlot"),
	bAlwaysTakeVoiceSlotCVar,
	TEXT("Always take voice slot immediately without trying to cache the request on the component\n")
	TEXT("default = 1: always forward the request to the audio engine immediately. - 0: attempt to cache play requests on the component until closer to the deadline."),
	ECVF_Default);


static int32 WorldlessGetAudioTimeBehaviorCVar = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/AudioComponent.cpp:525

Scope (from outer to inner):

file
function     void UAudioComponent::PlayQuantized

Source code excerpt:


	// If the desired quantization time is less than our min time, just execute immediately
	const bool bStealVoiceSlot = bAlwaysTakeVoiceSlotCVar || (NumFramesForDesiredTime <= NumFramesBeforeMinTime);
	const bool bClockIsNotRunning = !InClockHandle->IsClockRunning(WorldContextObject);
	const bool bCommandResetsClock = InQuantizationBoundary.bResetClockOnQueued;
	if (bStealVoiceSlot || bClockIsNotRunning || bCommandResetsClock)
	{
		AudioComponentQuartzCommandData.AnticapatoryBoundary = NewComponentCommandInfo.AnticapatoryBoundary = InQuantizationBoundary; // use the desired target boundary