All modules of the Wwise sound engine access memory through the AK::MemoryMgr interface. The client of the sound engine is responsible for initializing and terminating this interface.

A default implementation is provided with the SDK as a static library (AkMemoryMgr.lib). To use this library, the client needs to include the AkModule.h header, and call the AK::MemoryMgr::Init initialization function.

Refer to Build Configuration for more information regarding the usage of AkMemoryMgr.lib and other libraries.

Initialization

In the default implementation, default initialization settings can be obtained using AK::MemoryMgr::GetDefaultSettings.

Use the following setting to limit the total amount of virtual and device memory allocated by the Memory Manager:

• AkMemSettings::uMemAllocationSizeLimit

Use the following setting to enable additional runtime debugging functionality:

• AkMemSettings::uMemoryDebugLevel

This is an opaque value to allow custom implementations to define as many memory debugging features as they like. The default implementation provides two levels.

• Level 1 enables basic runtime memory debugging including; capturing FILE and LINE for each allocation, tracking callstacks ( where possible ) for each allocation, reporting leaks in a detailed manner upon shutdown and some very light integrity checks. This is light enough that you may run this during development by default.
• Level 2 enables the use of a stomp allocator which uses discrete pages of virtual memory for every allocation and seeks to trap any writes that occur out of bounds. This is a very slow and resource hungry mode and as such we do not recommend you enable it by default during development but instead when you are trying to track the cause of a memory stomp only.

Use the following to dump all allocations to a file (note that this requires AkMemSettings::uMemoryDebugLevel to be 1 and a non Release configuration):

• AK::MemoryMgr::DumpToFile

Remark: The sound engine opens a stream for writing using AK::IAkStreamMgr::CreateStd(). If you are using the default implementation of the Stream Manager, file opening is executed in your implementation of the Low-Level IO interface AK::StreamMgr::IAkLowLevelIOHook::BatchOpen().

Use the following settings to perform tracking of allocations for debugging purposes (these will not be called in the Release configuration):

• AkMemSettings::pfDebugMalloc
• AkMemSettings::pfDebugMalign
• AkMemSettings::pfDebugRealloc
• AkMemSettings::pfDebugFree
• AkMemSettings::pfDebugCheckForOverwrite

The debug functions above do not replace the actual allocation functions below; they are notification callbacks for the various memory allocation events.

Use the following settings to override the default implementation's use of rpmalloc with a custom allocator:

• AkMemSettings::pfInitForThread
• AkMemSettings::pfTermForThread
• AkMemSettings::pfTrimForThread
• AkMemSettings::pfMalloc
• AkMemSettings::pfMalign
• AkMemSettings::pfRealloc
• AkMemSettings::pfFree
• AkMemSettings::pfTotalReservedMemorySize
• AkMemSettings::pfSizeOfMemory

It is important for the allocation functions above to honor the AkMemType_Device bit by returning device memory when the bit is set. Device memory allocation is used on certain platforms only, and must conform to specific parameters: refer to the platform-specific section for details.

On PS5, it is critical to return device memory pages protected with additional flags. Refer to Memory Mapping Requirements for details on how to properly implement device memory allocation functions on PS5.

On Xbox One, it is critical to return memory pages allocated with APU functions. Refer to APU Memory for details on how to properly implement device memory allocation functions on Xbox One.

On Xbox Series X, it is critical to return memory pages allocated with APU functions. Refer to APU Memory for details on how to properly implement device memory allocation functions on Xbox Series X.

Use the following settings to override or control the page allocation mechanism underlying rpmalloc:

• AkMemSettings::pfAllocVM
• AkMemSettings::pfFreeVM
• AkMemSettings::pfAllocDevice
• AkMemSettings::pfFreeDevice
• AkMemSettings::uVMPageSize
• AkMemSettings::uDevicePageSize
• AkMemSettings::uMaxThreadLocalHeapAllocSize

The functions above will not be called if a custom allocator is configured to override rpmalloc. Device memory allocation is used on certain platforms only, and must conform to specific parameters: refer to the platform-specific section for details. If the alignment of the returned memory does not correspond to the natural alignment of the platform (for example, 64KB on Windows), this custom alignment must be specified in uVMPageSize and uDevicePageSize.

On threads that have called AK::MemoryMgr::InitForThread(), any allocation smaller than uMaxThreadLocalHeapAllocSize goes to a thread-local heap. Any allocation larger than that value go to a global heap, which is shared by all threads. The default value of uMaxThreadLocalHeapAllocSize is 0, so by default, all allocations go to the global heap. During periods of heavy multi-threaded CPU activity, there might be significant levels of contention for access to the global heap. If this occurs, consider setting uMaxThreadLocalHeapAllocSize to a value such as 384 or 512 or higher in order to mitigate the CPU contention, at the cost of greater memory use.

Refer to Samples for sample code and more information regarding the initialization of the Memory Manager in your game.

Refer to Loading Banks for more information regarding SoundBank memory usage.

Refer to Optimizing Memory Allocation for information about optimizing memory allocation.

Overriding the memory manager

It is possible for a client to provide a custom implementation of the AK::MemoryMgr interface. All functions defined in AkMemoryMgr.h should be implemented. The functions from the AK::MemoryMgr namespace defined in AkModule.h do not need to be implemented as they are specific to the default implementation of the memory manager.

As when overriding the various allocation functions of AkMemSettings, when writing a new AK::MemoryMgr implementation care must be taken to honor the AkMemType_Device bit by returning device memory when the bit is set. Device memory allocation is used on certain platforms only, and must conform to specific parameters: refer to the platform-specific section for details.