CacheSizeKB

CacheSizeKB

#Overview

name: CacheSizeKB

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 12 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of CacheSizeKB is to determine the maximum amount of memory that should be used for audio stream caching at any given time. It is primarily used for the audio system in Unreal Engine 5.

This setting variable is relied upon by the audio subsystem, particularly the audio streaming and caching modules. It’s used across multiple platform-specific settings classes, including WindowsTargetSettings, AndroidRuntimeSettings, and IOSRuntimeSettings, indicating its importance in cross-platform audio management.

The value of this variable is typically set in the constructor of the respective platform settings classes. For example, in WindowsTargetSettings, AndroidRuntimeSettings, and IOSRuntimeSettings, it’s initialized to 65536 KB (64 MB) by default.

CacheSizeKB interacts with other variables such as MaxChunkSizeOverrideKB and indirectly affects the calculation of the number of cache elements and chunk sizes in the audio streaming system.

Developers should be aware that setting this value too low (≤ 8 MB) will lower the size of individual chunks of audio during cooking, which can affect streaming performance. Additionally, the actual cache size used may be adjusted based on other factors like the minimum number of chunks required.

Best practices when using this variable include:

  1. Consider the target platform’s memory constraints when setting this value.
  2. Balance it with other audio quality settings to optimize performance and audio fidelity.
  3. Test thoroughly with different values to ensure smooth audio streaming on your target platforms.
  4. Be mindful of how changes to this value might affect the size of audio chunks and overall memory usage in your game.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:312, section: [/Script/WindowsTargetPlatform.WindowsTargetSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/Windows/WindowsTargetPlatform/Classes/WindowsTargetSettings.h:108

Scope (from outer to inner):

file
class        class UWindowsTargetSettings : public UObject

Source code excerpt:

	/** This determines the max amount of memory that should be used for the cache at any given time. If set low (<= 8 MB), it lowers the size of individual chunks of audio during cook. */
	UPROPERTY(GlobalConfig, EditAnywhere, Category = "Audio|CookOverrides|Stream Caching", meta = (DisplayName = "Max Cache Size (KB)"))
	int32 CacheSizeKB;

	/** This overrides the default max chunk size used when chunking audio for stream caching (ignored if < 0) */
	UPROPERTY(GlobalConfig, EditAnywhere, Category = "Audio|CookOverrides|Stream Caching", meta = (DisplayName = "Max Chunk Size Override (KB)"))
	int32 MaxChunkSizeOverrideKB;

	UPROPERTY(GlobalConfig, EditAnywhere, Category = "Audio|CookOverrides")

#Loc: <Workspace>/Engine/Source/Developer/Windows/WindowsTargetPlatform/Private/WindowsTargetPlatformClasses.cpp:7

Scope (from outer to inner):

file
function     UWindowsTargetSettings::UWindowsTargetSettings

Source code excerpt:

UWindowsTargetSettings::UWindowsTargetSettings( const FObjectInitializer& ObjectInitializer )
	: Super(ObjectInitializer)
	, CacheSizeKB(65536)
	, MaxSampleRate(48000)
	, HighSampleRate(32000)
	, MedSampleRate(24000)
	, LowSampleRate(12000)
	, MinSampleRate(8000)
	, CompressionQualityModifier(1)

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Classes/AndroidRuntimeSettings.h:604

Scope (from outer to inner):

file
class        class UAndroidRuntimeSettings : public UObject

Source code excerpt:

	/** This determines the max amount of memory that should be used for the cache at any given time. If set low (<= 8 MB), it lowers the size of individual chunks of audio during cook. */
	UPROPERTY(GlobalConfig, EditAnywhere, Category = "Audio|CookOverrides|Stream Caching", meta = (DisplayName = "Max Cache Size (KB)"))
	int32 CacheSizeKB;

	/** This overrides the default max chunk size used when chunking audio for stream caching (ignored if < 0) */
	UPROPERTY(GlobalConfig, EditAnywhere, Category = "Audio|CookOverrides|Stream Caching", meta = (DisplayName = "Max Chunk Size Override (KB)"))
	int32 MaxChunkSizeOverrideKB;

	UPROPERTY(config, EditAnywhere, Category = "Audio|CookOverrides")

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

Scope (from outer to inner):

file
function     UAndroidRuntimeSettings::UAndroidRuntimeSettings

Source code excerpt:

	, AudioCallbackBufferFrameSize(1024)
	, AudioNumBuffersToEnqueue(4)
	, CacheSizeKB(65536)
	, MaxSampleRate(48000)
	, HighSampleRate(32000)
    , MedSampleRate(24000)
    , LowSampleRate(12000)
	, MinSampleRate(8000)
	, CompressionQualityModifier(1)

#Loc: <Workspace>/Engine/Source/Runtime/AudioPlatformConfiguration/Private/AudioCompressionSettings.cpp:60

Scope (from outer to inner):

file
function     void FPlatformAudioCookOverrides::GetHashSuffix

Source code excerpt:

	
	// FAudioStreamCachingSettings
	FPCU::AppendHash(OutSuffix, TEXT("CSZE"), InOverrides->StreamCachingSettings.CacheSizeKB);
	FPCU::AppendHash(OutSuffix, TEXT("LCF"), InOverrides->StreamCachingSettings.bForceLegacyStreamChunking);
	FPCU::AppendHash(OutSuffix, TEXT("ZCS"), InOverrides->StreamCachingSettings.ZerothChunkSizeForLegacyStreamChunkingKB);
	FPCU::AppendHash(OutSuffix, TEXT("MCSO"), InOverrides->StreamCachingSettings.MaxChunkSizeOverrideKB);
	
	OutSuffix += TEXT("END");
}

#Loc: <Workspace>/Engine/Source/Runtime/AudioPlatformConfiguration/Public/AudioCompressionSettings.h:33

Scope: file

Source code excerpt:

	// In the future settings for the cache can be more complex, but for now
	// we set the max chunk size to 256 kilobytes, then set the number of elements in our cache as
	// CacheSizeKB / 256.
	int32 CacheSizeKB;

	// Bool flag for keeping sounds flagged for streaming chunked in the style of the legacy streaming manager.
	bool bForceLegacyStreamChunking;

	int32 ZerothChunkSizeForLegacyStreamChunkingKB;

#Loc: <Workspace>/Engine/Source/Runtime/AudioPlatformConfiguration/Public/AudioCompressionSettings.h:45

Scope (from outer to inner):

file
function     FAudioStreamCachingSettings

Source code excerpt:


	FAudioStreamCachingSettings()
		: CacheSizeKB(DefaultCacheSize)
		, bForceLegacyStreamChunking(false)
		, ZerothChunkSizeForLegacyStreamChunkingKB(256)
		, MaxChunkSizeOverrideKB(INDEX_NONE)
	{
	}
};

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioCompressionSettingsUtils.cpp:131

Scope (from outer to inner):

file
function     void CacheAudioCookOverrides

Source code excerpt:

	}

	OutOverrides.StreamCachingSettings.CacheSizeKB = RetrievedCacheSize;

	int32 RetrievedChunkSizeOverride = INDEX_NONE;
	if (PlatformFile->GetInt(*CategoryName, TEXT("MaxChunkSizeOverrideKB"), RetrievedChunkSizeOverride))
	{
		OutOverrides.StreamCachingSettings.MaxChunkSizeOverrideKB = RetrievedChunkSizeOverride;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioCompressionSettingsUtils.cpp:351

Scope (from outer to inner):

file
function     FCachedAudioStreamingManagerParams FPlatformCompressionUtilities::BuildCachedStreamingManagerParams

Source code excerpt:

	int32 MinChunkSize = (1.0f - MinimumCacheUsage) * MaxChunkSize;
	
	uint64 TempNumElements = ((CacheSettings.CacheSizeKB * 1024) / MinChunkSize) * FMath::Max(ChunkSlotNumScalarCvar, 1.0f);
	int32 NumElements = FMath::Min(TempNumElements, static_cast<uint64>(TNumericLimits< int32 >::Max()));

	FCachedAudioStreamingManagerParams Params;
	FCachedAudioStreamingManagerParams::FCacheDimensions CacheDimensions;

	// Primary cache defined here:
	CacheDimensions.MaxChunkSize = 256 * 1024; // max possible chunk size (hard coded for legacy streaming path)
	CacheDimensions.MaxMemoryInBytes = CacheSettings.CacheSizeKB > 0 ? CacheSettings.CacheSizeKB * 1024 : FAudioStreamCachingSettings::DefaultCacheSize * 1024;
	CacheDimensions.NumElements = FMath::Max(NumElements, 1); // force at least a single cache element to avoid crashes
	Params.Caches.Add(CacheDimensions);

	// TODO: When settings are added to support multiple sub-caches, add it here.

	return Params;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioCompressionSettingsUtils.cpp:376

Scope (from outer to inner):

file
function     uint32 FPlatformCompressionUtilities::GetMaxChunkSizeForCookOverrides

Source code excerpt:

	// In that case we log a warning on application launch.
	const int32 MinimumNumChunks = 32;
	int32 CacheSizeKB = InCompressionOverrides->StreamCachingSettings.CacheSizeKB;

	const int32 DefaultMaxChunkSizeKB = 256;
	const int32 MaxChunkSizeOverrideKB = InCompressionOverrides->StreamCachingSettings.MaxChunkSizeOverrideKB;
	int32 ChunkSizeBasedOnUtilization = 0;

	if (CacheSizeKB / DefaultMaxChunkSizeKB < MinimumNumChunks)
	{
		ChunkSizeBasedOnUtilization = (CacheSizeKB / MinimumNumChunks);
	}

	return FMath::Max(FMath::Max(DefaultMaxChunkSizeKB, MaxChunkSizeOverrideKB), ChunkSizeBasedOnUtilization) * 1024;
}

float FPlatformCompressionUtilities::GetCompressionDurationForCurrentPlatform()

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Classes/IOSRuntimeSettings.h:551

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

	/** This determines the max amount of memory that should be used for the cache at any given time. If set low (<= 8 MB), it lowers the size of individual chunks of audio during cook. */
	UPROPERTY(GlobalConfig, EditAnywhere, Category = "Audio|CookOverrides|Stream Caching", meta = (DisplayName = "Max Cache Size (KB)"))
	int32 CacheSizeKB;

	/** This overrides the default max chunk size used when chunking audio for stream caching (ignored if < 0) */
	UPROPERTY(GlobalConfig, EditAnywhere, Category = "Audio|CookOverrides|Stream Caching", meta = (DisplayName = "Max Chunk Size Override (KB)"))
	int32 MaxChunkSizeOverrideKB;

	UPROPERTY(config, EditAnywhere, Category = "Audio|CookOverrides")

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Private/IOSRuntimeSettings.cpp:17

Scope (from outer to inner):

file
function     UIOSRuntimeSettings::UIOSRuntimeSettings

Source code excerpt:

UIOSRuntimeSettings::UIOSRuntimeSettings(const FObjectInitializer& ObjectInitializer)
	: Super(ObjectInitializer)
	, CacheSizeKB(65536)
	, MaxSampleRate(48000)
	, HighSampleRate(32000)
	, MedSampleRate(24000)
	, LowSampleRate(12000)
	, MinSampleRate(8000)
	, CompressionQualityModifier(1)