Version
menu_open
Wwise SDK 2019.2.15
AkMemoryMgr.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Version: <VERSION> Build: <BUILDNUMBER>
25  Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
26 *******************************************************************************/
27 
28 /// \file
29 /// Memory Manager namespace.
30 
31 #ifndef _AKMEMORYMGR_H_
32 #define _AKMEMORYMGR_H_
33 
34 #include <AK/SoundEngine/Common/AkTypes.h>
35 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
36 
37 //#define AK_MEMDEBUG
38 
39 struct AkMemSettings;
40 
41 /// Memory category IDs.
42 enum AkMemID
43 {
44  AkMemID_Object, ///< Generic placeholder for allocations tied to the Wwise project.
45  AkMemID_Event, ///< Events from the Wwise project.
46  AkMemID_Structure, ///< Structures from the Wwise project.
47  AkMemID_Media, ///< Media from the Wwise project.
48  AkMemID_GameObject, ///< Game Objects and related.
49  AkMemID_Processing, ///< Anything tied to instancing and processing of the DSP graph.
50  AkMemID_ProcessingPlugin, ///< Plug-in allocations related to the DSP graph.
51  AkMemID_Streaming, ///< Streaming Manager objects.
52  AkMemID_StreamingIO, ///< Streaming Manager I/O memory.
53  AkMemID_SpatialAudio, ///< Spatial audio.
54  AkMemID_SpatialAudioGeometry, ///< Spatial audio geometry data.
55  AkMemID_SpatialAudioPaths, ///< Spatial audio paths data.
56  AkMemID_GameSim, ///< Game Simulator allocations.
57  AkMemID_MonitorQueue, ///< Monitor Queue.
58  AkMemID_Profiler, ///< Profiler.
59  AkMemID_FilePackage, ///< File packager.
60  AkMemID_SoundEngine, ///< Base sound engine allocations (managers, etc).
61 
62  AkMemID_NUM, ///< Category count.
63  AkMemID_MASK = 0x1FFFFFFF, ///< Mask for category IDs.
64 
65  AkMemType_Media = 0x20000000, ///< Media memory type bit.
66  AkMemType_Device = 0x80000000 ///< Device memory type bit.
67 };
68 
69 namespace AK
70 {
71  /// Memory Manager namespace.
72  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
73  /// \sa
74  /// - \ref memorymanager
75  namespace MemoryMgr
76  {
77  /// Memory category statistics.
78  /// \remarks These statistics are not collected in the Release configuration of
79  /// the default memory manager implementation.
80  /// \sa
81  /// - AK::MemoryMgr::GetCategoryStats()
82  /// - \ref memorymanager
83  struct CategoryStats
84  {
85  // Current state
86  AkUInt64 uUsed; ///< Used memory (in bytes)
87 
88  // Statistics
89  AkUInt64 uPeakUsed; ///< Peak used memory (in bytes)
90  AkUInt32 uAllocs; ///< Number of allocation calls since initialization
91  AkUInt32 uFrees; ///< Number of free calls since initialization
92  };
93 
94  struct GlobalStats
95  {
96  AkUInt64 uUsed;
97  AkUInt64 uDeviceUsed;
98  AkUInt64 uReserved;
99  AkUInt64 uMax;
100  };
101 
102  ////////////////////////////////////////////////////////////////////////
103  /// @name Initialization
104  //@{
105 
106  /// Query whether the Memory Manager has been sucessfully initialized.
107  /// \warning This function is not thread-safe. It should not be called at the same time as MemoryMgr::Init or MemoryMgr::Term.
108  /// \return True if the Memory Manager is initialized, False otherwise
109  /// \sa
110  /// - AK::MemoryMgr::Init()
111  /// - \ref memorymanager
112  AK_EXTERNAPIFUNC( bool, IsInitialized )();
113 
114  /// Terminate the Memory Manager.
115  /// \warning This function is not thread-safe. It is not valid to allocate memory or otherwise interact with the memory manager during or after this call.
116  /// \sa
117  /// - \ref memorymanager
118  AK_EXTERNAPIFUNC( void, Term )();
119 
120  /// Performs whatever steps are required to initialize a thread for use with the memory manager.
121  /// For example initializing thread local storage that the allocator requires to work.
122  /// The default implementation of the memory manager performs thread initialization automatically and therefore this call is optional.
123  /// For implementations where the cost of automatically initializing a thread for use with an allocator would be prohibitively expensive
124  /// this call allows you to perform the initialization once during, for example, thread creation.
125  /// \sa
126  /// - AkMemInitForThread
127  AK_EXTERNAPIFUNC( void, InitForThread )();
128 
129  /// Allows you to manually terminate a thread for use with the memory manager.
130  /// The default implementation of the memory manager requires that all threads that interact with the memory manager call this function prior
131  /// to either their termination or the termination of the memory manager. Threads not created by the sound engine itself will not have this
132  /// function called for them automatically.
133  /// Take care to call this function for any thread, not owned by wwise, that may have interacted with the memory manager. For example job system workers.
134  /// \sa
135  /// - AkMemTermForThread
136  AK_EXTERNAPIFUNC( void, TermForThread )();
137 
138  //@}
139 
140  ////////////////////////////////////////////////////////////////////////
141  /// @name Memory Allocation
142  //@{
143 
144 #if defined (AK_MEMDEBUG)
145  /// Allocate memory: debug version.
146  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
147  /// \sa
148  /// - \ref memorymanager
149  AK_EXTERNAPIFUNC( void *, dMalloc )(
150  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
151  size_t in_uSize, ///< Number of bytes to allocate
152  const char *in_pszFile, ///< Debug file name
153  AkUInt32 in_uLine ///< Debug line number
154  );
155 #endif
156  /// Allocate memory.
157  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
158  /// \sa
159  /// - \ref memorymanager
160  AK_EXTERNAPIFUNC( void *, Malloc )(
161  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
162  size_t in_uSize ///< Number of bytes to allocate
163  );
164 
165 #if defined (AK_MEMDEBUG)
166  /// Reallocate memory: debug version.
167  /// \return A pointer to the start of the reallocated memory (NULL if the allocation could not be completed)
168  /// \sa
169  /// - \ref memorymanager
170  AK_EXTERNAPIFUNC( void*, dRealloc )(
171  AkMemPoolId in_poolId,
172  void *in_pAlloc,
173  size_t in_uSize,
174  const char *in_pszFile,
175  AkUInt32 in_uLine
176  );
177 #endif
178 
179  /// Reallocate memory.
180  /// \return A pointer to the start of the reallocated memory (NULL if the allocation could not be completed)
181  /// \sa
182  /// - \ref memorymanager
183  AK_EXTERNAPIFUNC( void *, Realloc )(
184  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
185  void * in_pAlloc, ///< Pointer to the start of the allocated memory
186  size_t in_uSize ///< Number of bytes to allocate
187  );
188 
189  /// Free memory allocated with either AK::MemoryMgr::Malloc or AKMemoryMgr::Realloc.
190  /// \sa
191  /// - \ref memorymanager
192  AK_EXTERNAPIFUNC( void, Free )(
193  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
194  void * in_pMemAddress ///< Pointer to the start of memory allocated with Malloc or Realloc
195  );
196 
197 #if defined (AK_MEMDEBUG)
198  /// Allocate memory with a specific alignment. Needs to be used
199  /// in conjunction with AK::MemoryMgr::Falign. debug version.
200  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
201  /// \sa
202  /// - \ref memorymanager
203  AK_EXTERNAPIFUNC( void *, dMalign )(
204  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
205  size_t in_uSize, ///< Number of bytes to allocate
206  AkUInt32 in_uAlignment, ///< Alignment (in bytes)
207  const char* in_pszFile, ///< Debug file name
208  AkUInt32 in_uLine ///< Debug line number
209  );
210 #endif
211 
212  /// Allocate memory with a specific alignment. Needs to be used
213  /// in conjunction with AK::MemoryMgr::Falign.
214  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
215  /// \sa
216  /// - \ref memorymanager
217  AK_EXTERNAPIFUNC( void *, Malign )(
218  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
219  size_t in_uSize, ///< Number of bytes to allocate
220  AkUInt32 in_uAlignment ///< Alignment (in bytes)
221  );
222 
223  /// Free memory allocated with AK::MemoryMgr::Malign.
224  /// \sa
225  /// - \ref memorymanager
226  AK_EXTERNAPIFUNC( void, Falign )(
227  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
228  void * in_pMemAddress ///< Pointer to the start of memory allocated with Malign
229  );
230 
231  //@}
232 
233  ////////////////////////////////////////////////////////////////////////
234  /// @name Memory Profiling
235  //@{
236 
237  /// Get statistics for a given memory category.
238  /// \note Be aware of the potentially incoherent nature of reporting such information during concurrent modification by multiple threads.
239  AK_EXTERNAPIFUNC( void, GetCategoryStats )(
240  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
241  CategoryStats& out_poolStats ///< Returned statistics.
242  );
243 
244  /// Get statistics for overall memory manager usage.
245  /// \note Be aware of the potentially incoherent nature of reporting such information during concurrent modification by multiple threads.
246  AK_EXTERNAPIFUNC( void, GetGlobalStats )(
247  GlobalStats& out_stats ///< Returned statistics.
248  );
249 
250  /// Called to start profiling memory usage for one thread (the calling thread).
251  /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage.
252  AK_EXTERNAPIFUNC( void, StartProfileThreadUsage )(
253  );
254 
255  /// Called to stop profiling memory usage for the current thread.
256  /// \return The amount of memory allocated by this thread since StartProfileThreadUsage was called.
257  /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage.
258  AK_EXTERNAPIFUNC( AkUInt64, StopProfileThreadUsage )(
259  );
260 
261  //@}
262  }
263 }
264 
265 #endif // _AKMEMORYMGR_H_
AkMemID_Processing
@ AkMemID_Processing
Anything tied to instancing and processing of the DSP graph.
Definition: AkMemoryMgr.h:49
AkMemID_SpatialAudioPaths
@ AkMemID_SpatialAudioPaths
Spatial audio paths data.
Definition: AkMemoryMgr.h:55
AkMemID_MonitorQueue
@ AkMemID_MonitorQueue
Monitor Queue.
Definition: AkMemoryMgr.h:57
AkMemID_FilePackage
@ AkMemID_FilePackage
File packager.
Definition: AkMemoryMgr.h:59
AK::MemoryMgr::TermForThread
AKSOUNDENGINE_API void TermForThread()
AK::MemoryMgr::CategoryStats::uPeakUsed
AkUInt64 uPeakUsed
Peak used memory (in bytes)
Definition: AkMemoryMgr.h:89
AkUInt64
uint64_t AkUInt64
Unsigned 64-bit integer.
Definition: AkTypes.h:86
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:32
AkMemID_StreamingIO
@ AkMemID_StreamingIO
Streaming Manager I/O memory.
Definition: AkMemoryMgr.h:52
AkMemID_Media
@ AkMemID_Media
Media from the Wwise project.
Definition: AkMemoryMgr.h:47
AkMemID_Object
@ AkMemID_Object
Generic placeholder for allocations tied to the Wwise project.
Definition: AkMemoryMgr.h:44
AK::MemoryMgr::Free
AKSOUNDENGINE_API void Free(AkMemPoolId in_poolId, void *in_pMemAddress)
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:78
AK::MemoryMgr::Malloc
AKSOUNDENGINE_API void * Malloc(AkMemPoolId in_poolId, size_t in_uSize)
AkMemPoolId
AkInt32 AkMemPoolId
Memory pool ID.
Definition: AkTypes.h:67
AkMemID_Profiler
@ AkMemID_Profiler
Profiler.
Definition: AkMemoryMgr.h:58
AkMemID
AkMemID
Memory category IDs.
Definition: AkMemoryMgr.h:43
AK::MemoryMgr::CategoryStats::uAllocs
AkUInt32 uAllocs
Number of allocation calls since initialization.
Definition: AkMemoryMgr.h:90
AK::MemoryMgr::Term
AKSOUNDENGINE_API void Term()
AK::MemoryMgr::GetGlobalStats
AKSOUNDENGINE_API void GetGlobalStats(GlobalStats &out_stats)
AK::MemoryMgr::InitForThread
AKSOUNDENGINE_API void InitForThread()
AK::MemoryMgr::Falign
AKSOUNDENGINE_API void Falign(AkMemPoolId in_poolId, void *in_pMemAddress)
AkMemID_SpatialAudioGeometry
@ AkMemID_SpatialAudioGeometry
Spatial audio geometry data.
Definition: AkMemoryMgr.h:54
AK::MemoryMgr::Malign
AKSOUNDENGINE_API void * Malign(AkMemPoolId in_poolId, size_t in_uSize, AkUInt32 in_uAlignment)
AkMemID_SoundEngine
@ AkMemID_SoundEngine
Base sound engine allocations (managers, etc).
Definition: AkMemoryMgr.h:60
AK::MemoryMgr::StartProfileThreadUsage
AKSOUNDENGINE_API void StartProfileThreadUsage()
AkMemID_GameSim
@ AkMemID_GameSim
Game Simulator allocations.
Definition: AkMemoryMgr.h:56
AkMemID_GameObject
@ AkMemID_GameObject
Game Objects and related.
Definition: AkMemoryMgr.h:48
AkMemID_Streaming
@ AkMemID_Streaming
Streaming Manager objects.
Definition: AkMemoryMgr.h:51
AkMemID_NUM
@ AkMemID_NUM
Category count.
Definition: AkMemoryMgr.h:62
AkMemID_MASK
@ AkMemID_MASK
Mask for category IDs.
Definition: AkMemoryMgr.h:63
AK::MemoryMgr::Realloc
AKSOUNDENGINE_API void * Realloc(AkMemPoolId in_poolId, void *in_pAlloc, size_t in_uSize)
AkMemID_Structure
@ AkMemID_Structure
Structures from the Wwise project.
Definition: AkMemoryMgr.h:46
AkMemID_Event
@ AkMemID_Event
Events from the Wwise project.
Definition: AkMemoryMgr.h:45
AK::MemoryMgr::StopProfileThreadUsage
AKSOUNDENGINE_API AkUInt64 StopProfileThreadUsage()
AK::MemoryMgr::CategoryStats::uUsed
AkUInt64 uUsed
Used memory (in bytes)
Definition: AkMemoryMgr.h:86
AkMemID_ProcessingPlugin
@ AkMemID_ProcessingPlugin
Plug-in allocations related to the DSP graph.
Definition: AkMemoryMgr.h:50
AK::MemoryMgr::GetCategoryStats
AKSOUNDENGINE_API void GetCategoryStats(AkMemPoolId in_poolId, CategoryStats &out_poolStats)
AK::MemoryMgr::IsInitialized
AKSOUNDENGINE_API bool IsInitialized()
AkMemID_SpatialAudio
@ AkMemID_SpatialAudio
Spatial audio.
Definition: AkMemoryMgr.h:53
AkMemType_Device
@ AkMemType_Device
Device memory type bit.
Definition: AkMemoryMgr.h:66
AkMemType_Media
@ AkMemType_Media
Media memory type bit.
Definition: AkMemoryMgr.h:65
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:85
AK::MemoryMgr::CategoryStats::uFrees
AkUInt32 uFrees
Number of free calls since initialization.
Definition: AkMemoryMgr.h:91

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise