Table of Contents

Wwise SDK 2019.1.8
AkSoundEngine.h
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 // AkSoundEngine.h
29 
30 /// \file
31 /// The main sound engine interface.
32 
33 
34 #ifndef _AK_SOUNDENGINE_H_
35 #define _AK_SOUNDENGINE_H_
36 
37 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
38 #include <AK/SoundEngine/Common/AkTypes.h>
39 #include <AK/SoundEngine/Common/IAkPlugin.h>
40 #include <AK/SoundEngine/Common/AkCallback.h>
41 
42 #ifdef AK_WIN
43 #include <AK/SoundEngine/Platforms/Windows/AkWinSoundEngine.h>
44 #include <AK/SoundEngine/Platforms/Windows/AkPlatformContext.h>
45 
46 #elif defined (AK_MAC_OS_X)
47 #include <AK/SoundEngine/Platforms/Mac/AkMacSoundEngine.h>
48 #include <AK/SoundEngine/Platforms/Mac/AkPlatformContext.h>
49 
50 #elif defined (AK_IOS)
51 #include <AK/SoundEngine/Platforms/iOS/AkiOSSoundEngine.h>
52 #include <AK/SoundEngine/Platforms/iOS/AkPlatformContext.h>
53 
54 #elif defined(AK_GAMINGXBOX)
55 #include <AK/SoundEngine/Platforms/GX/AkGXSoundEngine.h>
56 #include <AK/SoundEngine/Platforms/GX/AkPlatformContext.h>
57 
58 #elif defined (AK_XBOXONE)
59 #include <AK/SoundEngine/Platforms/XboxOne/AkXboxOneSoundEngine.h>
60 #include <AK/SoundEngine/Platforms/XboxOne/AkPlatformContext.h>
61 
62 #elif defined( AK_LUMIN )
63 #include <AK/SoundEngine/Platforms/Lumin/AkLuminSoundEngine.h>
64 #include <AK/SoundEngine/Platforms/Lumin/AkPlatformContext.h>
65 
66 #elif defined( AK_ANDROID )
67 #include <AK/SoundEngine/Platforms/Android/AkAndroidSoundEngine.h>
68 #include <AK/SoundEngine/Platforms/Android/AkPlatformContext.h>
69 
70 #elif defined (AK_PS4)
71 #include <AK/SoundEngine/Platforms/PS4/AkPS4SoundEngine.h>
72 #include <AK/SoundEngine/Platforms/PS4/AkPlatformContext.h>
73 
74 #elif defined (AK_PELLEGRINO)
75 #include <AK/SoundEngine/Platforms/Pellegrino/AkPellegrinoSoundEngine.h>
76 #include <AK/SoundEngine/Platforms/Pellegrino/AkPlatformContext.h>
77 
78 #elif defined( AK_GGP )
79 #include <AK/SoundEngine/Platforms/GGP/AkGGPSoundEngine.h>
80 #include <AK/SoundEngine/Platforms/GGP/AkPlatformContext.h>
81 
82 #elif defined( AK_LINUX_DESKTOP )
83 #include <AK/SoundEngine/Platforms/Linux/AkLinuxSoundEngine.h>
84 #include <AK/SoundEngine/Platforms/Linux/AkPlatformContext.h>
85 
86 #elif defined( AK_EMSCRIPTEN )
87 #include <AK/SoundEngine/Platforms/Emscripten/AkEmscriptenSoundEngine.h>
88 #include <AK/SoundEngine/Platforms/Emscripten/AkPlatformContext.h>
89 
90 #elif defined( AK_QNX )
91 #include <AK/SoundEngine/Platforms/QNX/AkQNXSoundEngine.h>
92 #include <AK/SoundEngine/Platforms/QNX/AkPlatformContext.h>
93 
94 #elif defined( AK_NX )
95 #include <AK/SoundEngine/Platforms/NX/AkNXSoundEngine.h>
96 #include <AK/SoundEngine/Platforms/NX/AkPlatformContext.h>
97 
98 #else
99 #error AkSoundEngine.h: Undefined platform
100 #endif
101 
102 #ifndef AK_ASSERT_HOOK
103  /// Function called on assert handling, optional
104  /// \sa
105  /// - AkInitSettings
106  AK_CALLBACK( void, AkAssertHook)(
107  const char * in_pszExpression, ///< Expression
108  const char * in_pszFileName, ///< File Name
109  int in_lineNumber ///< Line Number
110  );
111  #define AK_ASSERT_HOOK
112 #endif
113 
114 /// Callback function prototype for User Music notifications
115 /// It is useful for reacting to user music playback.
116 ///
117 /// \sa
118 /// - \ref AkGlobalCallbackFunc
119 /// - \ref AkPlatformInitSettings
120 /// - \ref background_music_and_dvr
121 ///
122 typedef AKRESULT ( * AkBackgroundMusicChangeCallbackFunc )(
123  bool in_bBackgroundMusicMuted, ///< Flag indicating whether the busses tagged as "background music" in the project are muted or not.
124  void* in_pCookie ///< User-provided data, e.g. a user structure.
125  );
126 
127 /// Platform-independent initialization settings of output devices.
129 {
131  audioDeviceShareset(AK_INVALID_UNIQUE_ID),
132  idDevice(0),
133  ePanningRule(AkPanningRule_Speakers),
134  channelConfig(){};
135 
136  AkOutputSettings(const char* in_szDeviceShareSet, AkUniqueID in_idDevice = AK_INVALID_UNIQUE_ID, AkChannelConfig in_channelConfig = AkChannelConfig(), AkPanningRule in_ePanning = AkPanningRule_Speakers);
137 
138 #ifdef AK_SUPPORT_WCHAR
139  AkOutputSettings(const wchar_t* in_szDeviceShareSet, AkUniqueID in_idDevice = AK_INVALID_UNIQUE_ID, AkChannelConfig in_channelConfig = AkChannelConfig(), AkPanningRule in_ePanning = AkPanningRule_Speakers);
140 #endif
141 
142  AkUniqueID audioDeviceShareset; ///< Unique ID of a custom audio device to be used. Custom audio devices are defined in the Audio Device Shareset section of the Wwise project.
143  ///< If you want to output normally through the default system, leave this field to its default value (AK_INVALID_UNIQUE_ID).
144  ///< Typical usage: AkInitSettings.eOutputSettings.audioDeviceShareset = AK::SoundEngine::GetIDFromString("InsertYourAudioDeviceSharesetNameHere");
145  /// \sa <tt>\ref AK::SoundEngine::GetIDFromString()</tt>
146  /// \sa \ref soundengine_plugins_audiodevices
147  /// \sa \ref integrating_secondary_outputs
148  /// \sa \ref default_audio_devices
149 
150  AkUInt32 idDevice; ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
151  ///< - PS4 Controller-Speakers: UserID as returned from sceUserServiceGetLoginUserIdList
152  ///< - XBoxOne Controller-Headphones: Use the AK::GetDeviceID function to get the ID from an IMMDevice. Find the player's device with the WASAPI API (IMMDeviceEnumerator, see Microsoft documentation) or use AK::GetDeviceIDFromName.
153  ///< - Windows: Use AK::GetDeviceID or AK::GetDeviceIDFromName to get the correct ID. Leave to 0 for the default Windows device as seen in Audio Properties.
154  ///< - All other outputs: use 0 to select the default for the selected audio device type (shareset)
155 
156  AkPanningRule ePanningRule; ///< Rule for 3D panning of signals routed to a stereo bus. In AkPanningRule_Speakers mode, the angle of the front loudspeakers
157  ///< (uSpeakerAngles[0]) is used. In AkPanningRule_Headphones mode, the speaker angles are superseded with constant power panning
158  ///< between two virtual microphones spaced 180 degrees apart.
159 
160  AkChannelConfig channelConfig; ///< Channel configuration for this output. Call AkChannelConfig::Clear() to let the engine use the default output configuration.
161  ///< Hardware might not support the selected configuration.
162 };
163 
164 /// Possible values for the floor plane axis used in the Game Object 3D Viewer in Wwise
165 enum AkFloorPlane
166 {
167  AkFloorPlane_XZ = 0,
168  AkFloorPlane_XY,
169  AkFloorPlane_YZ,
170  AkFloorPlane_Default = AkFloorPlane_XZ
171 };
172 
173 /// The execution context for a task.
175 {
176  AkUInt32 uIdxThread; ///< The current thread index [0, AkTaskSchedulerDesc::uNumSchedulerWorkerThreads[.
177 };
178 
179 /// Task function: process the [in_uIdxBegin,in_uIdxEnd[ range of items in the in_pData array.
180 typedef void(*AkParallelForFunc)(void* in_pData, AkUInt32 in_uIdxBegin, AkUInt32 in_uIdxEnd, AkTaskContext in_ctx, void* in_pUserData);
181 
182 /// Description of the client task scheduler.
184 {
185  /// Execute in_func in parallel over the [in_uIdxBegin,in_uIdxEnd[ range of items in the in_pData array,
186  /// and wait for the work to finish.
187  typedef void(*ParallelForFunc)(
188  void * in_pData, ///< A pointer to a data array.
189  AkUInt32 in_uIdxBegin, ///< The first element of data to process.
190  AkUInt32 in_uIdxEnd, ///< The one past the last element of data to process.
191  AkUInt32 in_uTileSize, ///< The desired maximum tile size in which to subdivide the data.
192  AkParallelForFunc in_func, ///< The data processing function.
193  void * in_pUserData, ///< User data to be passed into 'func'.
194  const char * in_szDebugName); ///< Debug name for the workload.
195 
196  ParallelForFunc fcnParallelFor; ///< ParallelForFunc callback.
197  AkUInt32 uNumSchedulerWorkerThreads; ///< The number of worker threads in the schduler.
198 };
199 
200 /// Platform-independent initialization settings of the sound engine
201 /// \sa
202 /// - <tt>AK::SoundEngine::Init()</tt>
203 /// - <tt>AK::SoundEngine::GetDefaultInitSettings()</tt>
204 /// - \ref soundengine_integration_init_advanced
205 /// - \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
207 {
208  AkAssertHook pfnAssertHook; ///< External assertion handling function (optional)
209 
210  AkUInt32 uMaxNumPaths; ///< Maximum number of paths for positioning
211  AkUInt32 uDefaultPoolSize; ///< Size of the default memory pool, in bytes
212  AkReal32 fDefaultPoolRatioThreshold; ///< 0.0f to 1.0f value: The percentage of occupied memory where the sound engine should enter in Low memory Mode. \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
213  AkUInt32 uCommandQueueSize; ///< Size of the command queue, in bytes
214  AkMemPoolId uPrepareEventMemoryPoolID; ///< Memory pool where data allocated by <tt>AK::SoundEngine::PrepareEvent()</tt> and <tt>AK::SoundEngine::PrepareGameSyncs()</tt> will be done.
215  bool bEnableGameSyncPreparation; ///< Sets to true to enable AK::SoundEngine::PrepareGameSync usage.
216  AkUInt32 uContinuousPlaybackLookAhead; ///< Number of quanta ahead when continuous containers should instantiate a new voice before which next sounds should start playing. This look-ahead time allows I/O to occur, and is especially useful to reduce the latency of continuous containers with trigger rate or sample-accurate transitions.
217  ///< Default is 1 audio quantum, also known as an audio frame. Its size is equal to AkInitSettings::uNumSamplesPerFrame / AkPlatformInitSettings::uSampleRate. For many platforms the default values - which can be overridden - are respectively 1,024 samples and 48 kHz. This gives a default 21.3 ms for an audio quantum, which is adequate if you have a RAM-based streaming device that completes transfers within 20 ms. With 1 look-ahead quantum, voices spawned by continuous containers are more likely to be ready when they are required to play, thereby improving the overall precision of sound scheduling. If your device completes transfers in 30 ms instead, you might consider increasing this value to 2 because it will grant new voices 2 audio quanta (~43 ms) to fetch data.
218 
219  AkUInt32 uNumSamplesPerFrame; ///< Number of samples per audio frame (256, 512, 1024, or 2048).
220 
221  AkUInt32 uMonitorPoolSize; ///< Size of the monitoring pool, in bytes. This parameter is not used in Release build.
222  AkUInt32 uMonitorQueuePoolSize; ///< Size of the monitoring queue pool, in bytes. This parameter is not used in Release build.
223 
224  AkOutputSettings settingsMainOutput; ///< Main output device settings.
225  AkUInt32 uMaxHardwareTimeoutMs; ///< Amount of time to wait for HW devices to trigger an audio interrupt. If there is no interrupt after that time, the sound engine will revert to silent mode and continue operating until the HW finally comes back. Default value: 2000 (2 seconds)
226 
227  bool bUseSoundBankMgrThread; ///< Use a separate thread for loading sound banks. Allows asynchronous operations.
228  bool bUseLEngineThread; ///< Use a separate thread for processing audio. If set to false, audio processing will occur in RenderAudio(). \ref goingfurther_eventmgrthread
229 
230  AkBackgroundMusicChangeCallbackFunc BGMCallback; ///< Application-defined audio source change event callback function.
231  void* BGMCallbackCookie; ///< Application-defined user data for the audio source change event callback function.
232  AkOSChar * szPluginDLLPath; ///< When using DLLs for plugins, specify their path. Leave NULL if DLLs are in the same folder as the game executable.
233 
234  AkFloorPlane eFloorPlane; ///< Floor plane axis for 3D game object viewing.
235  AkTaskSchedulerDesc taskSchedulerDesc; ///< The defined client task scheduler that AkSoundEngine will use to schedule internal tasks.
236  AkReal32 fDebugOutOfRangeLimit; ///< Debug setting: Only used when bDebugOutOfRangeCheckEnabled is true. This defines the maximum values samples can have. Normal audio must be contained within +1/-1. This limit should be set higher to allow temporary or short excursions out of range. Default is 16.
237  bool bDebugOutOfRangeCheckEnabled; ///< Debug setting: Enable checks for out-of-range (and NAN) floats in the processing code. Do not enable in any normal usage, this setting uses a lot of CPU. Will print error messages in the log if invalid values are found at various point in the pipeline. Contact AK Support with the new error messages for more information.
238 };
239 
240 /// Necessary settings for setting externally-loaded sources
242 {
243  AkUniqueID sourceID; ///< Source ID (available in the SoundBank content files)
244  AkUInt8* pMediaMemory; ///< Pointer to the data to be set for the source
245  AkUInt32 uMediaSize; ///< Size, in bytes, of the data to be set for the source
246 };
247 
248 /// Return values for GetSourcePlayPositions.
250 {
251  AkUniqueID audioNodeID; ///< Audio Node ID of playing item
252  AkUniqueID mediaID; ///< Media ID of playing item. (corresponds to 'ID' attribute of 'File' element in SoundBank metadata file)
253  AkTimeMs msTime; ///< Position of the source (in ms) associated with that playing item
254 };
255 
256 /// Audiokinetic namespace
257 namespace AK
258 {
259  class IReadBytes;
260  class IWriteBytes;
261 
262  /// Audiokinetic sound engine namespace
263  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
264  namespace SoundEngine
265  {
266  ///////////////////////////////////////////////////////////////////////
267  /// @name Initialization
268  //@{
269 
270  /// Query whether or not the sound engine has been successfully initialized.
271  /// \warning This function is not thread-safe. It should not be called at the same time as \c SoundEngine::Init() or \c SoundEngine::Term().
272  /// \return \c True if the sound engine has been initialized, \c False otherwise.
273  /// \sa
274  /// - \ref soundengine_integration_init_advanced
275  /// - <tt>AK::SoundEngine::Init()</tt>
276  /// - <tt>AK::SoundEngine::Term()</tt>
277  AK_EXTERNAPIFUNC( bool, IsInitialized )();
278 
279  /// Initialize the sound engine.
280  /// \warning This function is not thread-safe.
281  /// \remark The initial settings should be initialized using <tt>AK::SoundEngine::GetDefaultInitSettings()</tt>
282  /// and <tt>AK::SoundEngine::GetDefaultPlatformInitSettings()</tt> to fill the structures with their
283  /// default settings. This is not mandatory, but it helps avoid backward compatibility problems.
284  ///
285  /// \return
286  /// - AK_Success if the initialization was successful
287  /// - AK_MemManagerNotInitialized if the memory manager is not available or not properly initialized
288  /// - AK_StreamMgrNotInitialized if the stream manager is not available or not properly initialized
289  /// - AK_SSEInstructionsNotSupported if the machine does not support SSE instruction (only on the PC)
290  /// - AK_InsufficientMemory or AK_Fail if there is not enough memory available to initialize the sound engine properly
291  /// - AK_InvalidParameter if some parameters are invalid
292  /// - AK_Fail if the sound engine is already initialized, or if the provided settings result in insufficient
293  /// resources for the initialization.
294  /// \sa
295  /// - \ref soundengine_integration_init_advanced
296  /// - <tt>AK::SoundEngine::Term()</tt>
297  /// - <tt>AK::SoundEngine::GetDefaultInitSettings()</tt>
298  /// - <tt>AK::SoundEngine::GetDefaultPlatformInitSettings()</tt>
299  AK_EXTERNAPIFUNC( AKRESULT, Init )(
300  AkInitSettings * in_pSettings, ///< Initialization settings (can be NULL, to use the default values)
301  AkPlatformInitSettings * in_pPlatformSettings ///< Platform-specific settings (can be NULL, to use the default values)
302  );
303 
304  /// Gets the default values of the platform-independent initialization settings.
305  /// \warning This function is not thread-safe.
306  /// \sa
307  /// - \ref soundengine_integration_init_advanced
308  /// - <tt>AK::SoundEngine::Init()</tt>
309  /// - <tt>AK::SoundEngine::GetDefaultPlatformInitSettings()</tt>
310  AK_EXTERNAPIFUNC( void, GetDefaultInitSettings )(
311  AkInitSettings & out_settings ///< Returned default platform-independent sound engine settings
312  );
313 
314  /// Gets the default values of the platform-specific initialization settings.
315  ///
316  /// Windows Specific:
317  /// When initializing for Windows platform, the HWND value returned in the
318  /// AkPlatformInitSettings structure is the foreground HWND at the moment of the
319  /// initialization of the sound engine and may not be the correct one for your need.
320  /// Each game must specify the HWND that will be passed to DirectSound initialization.
321  /// It is required that each game provides the correct HWND to be used or it could cause
322  /// one of the following problem:
323  /// - Random Sound engine initialization failure.
324  /// - Audio focus to be located on the wrong window.
325  ///
326  /// \warning This function is not thread-safe.
327  /// \sa
328  /// - \ref soundengine_integration_init_advanced
329  /// - <tt>AK::SoundEngine::Init()</tt>
330  /// - <tt>AK::SoundEngine::GetDefaultInitSettings()</tt>
331  AK_EXTERNAPIFUNC( void, GetDefaultPlatformInitSettings )(
332  AkPlatformInitSettings & out_platformSettings ///< Returned default platform-specific sound engine settings
333  );
334 
335  /// Terminates the sound engine.
336  /// If some sounds are still playing or events are still being processed when this function is
337  /// called, they will be stopped.
338  /// \warning This function is not thread-safe.
339  /// \warning Before calling Term, you must ensure that no other thread is accessing the sound engine.
340  /// \sa
341  /// - \ref soundengine_integration_init_advanced
342  /// - <tt>AK::SoundEngine::Init()</tt>
343  AK_EXTERNAPIFUNC( void, Term )();
344 
345  /// Gets the configured audio settings.
346  /// Call this function to get the configured audio settings.
347  ///
348  /// \warning This function is not thread-safe.
349  /// \warning Call this function only after the sound engine has been properly initialized.
350  AK_EXTERNAPIFUNC( AKRESULT, GetAudioSettings )(
351  AkAudioSettings & out_audioSettings ///< Returned audio settings
352  );
353 
354  /// Gets the output speaker configuration of the specified output.
355  /// Call this function to get the speaker configuration of the output (which may not correspond
356  /// to the physical output format of the platform, in the case of downmixing provided by the platform itself).
357  /// You may initialize the sound engine with a user-specified configuration, but the resulting
358  /// configuration is determined by the sound engine, based on the platform, output type and
359  /// platform settings (for e.g. system menu or control panel option).
360  ///
361  /// \warning Call this function only after the sound engine has been properly initialized. If you are initializing the sound engine with AkInitSettings::bUseLEngineThread to false, it is required to call RenderAudio() at least once before calling this function to complete the sound engine initialization.
362  /// \return The output configuration. An empty AkChannelConfig AkChannelConfig::IsValid() == false if device does not exist.
363  /// \sa
364  /// - AkSpeakerConfig.h
365  /// - AkOutputSettings
366  AK_EXTERNAPIFUNC( AkChannelConfig, GetSpeakerConfiguration )(
367  AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
368  );
369 
370  /// Gets the panning rule of the specified output.
371  /// \warning Call this function only after the sound engine has been properly initialized.
372  /// \return One of the supported configuration:
373  /// - AkPanningRule_Speakers
374  /// - AkPanningRule_Headphone
375  /// \sa
376  /// - AkSpeakerConfig.h
377  AK_EXTERNAPIFUNC( AKRESULT, GetPanningRule )(
378  AkPanningRule & out_ePanningRule, ///< Returned panning rule (AkPanningRule_Speakers or AkPanningRule_Headphone) for given output.
379  AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
380  );
381 
382  /// Sets the panning rule of the specified output.
383  /// This may be changed anytime once the sound engine is initialized.
384  /// \warning This function posts a message through the sound engine's internal message queue, whereas GetPanningRule() queries the current panning rule directly.
385  AK_EXTERNAPIFUNC( AKRESULT, SetPanningRule )(
386  AkPanningRule in_ePanningRule, ///< Panning rule.
387  AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
388  );
389 
390  /// Gets speaker angles of the specified device. Speaker angles are used for 3D positioning of sounds over standard configurations.
391  /// Note that the current version of Wwise only supports positioning on the plane.
392  /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180].
393  /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles.
394  /// Angles must be set in ascending order.
395  /// You may call this function with io_pfSpeakerAngles set to NULL to get the expected number of angle values in io_uNumAngles,
396  /// in order to allocate your array correctly. You may also obtain this number by calling
397  /// AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ).
398  /// If io_pfSpeakerAngles is not NULL, the array is filled with up to io_uNumAngles.
399  /// Typical usage:
400  /// - AkUInt32 uNumAngles;
401  /// - GetSpeakerAngles( NULL, uNumAngles, AkOutput_Main );
402  /// - AkReal32 * pfSpeakerAngles = AkAlloca( uNumAngles * sizeof(AkReal32) );
403  /// - GetSpeakerAngles( pfSpeakerAngles, uNumAngles, AkOutput_Main );
404  /// \aknote
405  /// On most platforms, the angle set on the plane consists of 3 angles, to account for 7.1.
406  /// - When panning to stereo (speaker mode, see <tt>AK::SoundEngine::SetPanningRule()</tt>), only angle[0] is used, and 3D sounds in the back of the listener are mirrored to the front.
407  /// - When panning to 5.1, the front speakers use angle[0], and the surround speakers use (angle[2] - angle[1]) / 2.
408  /// \endaknote
409  /// \warning Call this function only after the sound engine has been properly initialized.
410  /// \return AK_Success if device exists.
411  /// \sa SetSpeakerAngles()
412  AK_EXTERNAPIFUNC( AKRESULT, GetSpeakerAngles )(
413  AkReal32 * io_pfSpeakerAngles, ///< Returned array of loudspeaker pair angles, in degrees relative to azimuth [0,180]. Pass NULL to get the required size of the array.
414  AkUInt32 & io_uNumAngles, ///< Returned number of angles in io_pfSpeakerAngles, which is the minimum between the value that you pass in, and the number of angles corresponding to AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ), or just the latter if io_pfSpeakerAngles is NULL.
415  AkReal32 & out_fHeightAngle, ///< Elevation of the height layer, in degrees relative to the plane [-90,90].
416  AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
417  );
418 
419  /// Sets speaker angles of the specified device. Speaker angles are used for 3D positioning of sounds over standard configurations.
420  /// Note that the current version of Wwise only supports positioning on the plane.
421  /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180].
422  /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles.
423  /// Angles must be set in ascending order.
424  /// Typical usage:
425  /// - Initialize the sound engine and/or add secondary output(s).
426  /// - Get number of speaker angles and their value into an array using GetSpeakerAngles().
427  /// - Modify the angles and call SetSpeakerAngles().
428  /// This function posts a message to the audio thread through the command queue, so it is thread safe. However the result may not be immediately read with GetSpeakerAngles().
429  /// \warning This function only applies to configurations (or subset of these configurations) that are standard and whose speakers are on the plane (2D).
430  /// \return
431  /// - AK_Success if successful.
432  /// - AK_InvalidFloatValue if the value specified was NaN or Inf
433  /// - AK_InsufficientMemory if there wasn't enough memory in the message queue
434  /// \sa GetSpeakerAngles()
435  AK_EXTERNAPIFUNC( AKRESULT, SetSpeakerAngles )(
436  const AkReal32 * in_pfSpeakerAngles, ///< Array of loudspeaker pair angles, in degrees relative to azimuth [0,180].
437  AkUInt32 in_uNumAngles, ///< Number of elements in in_pfSpeakerAngles. It must correspond to AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ) (the value returned by GetSpeakerAngles()).
438  AkReal32 in_fHeightAngle, ///< Elevation of the height layer, in degrees relative to the plane [-90,90].
439  AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
440  );
441 
442  /// Allows the game to set the volume threshold to be used by the sound engine to determine if a voice must go virtual.
443  /// This may be changed anytime once the sound engine was initialized.
444  /// If this function is not called, the used value will be the value specified in the platform specific project settings.
445  /// \return
446  /// - AK_Success if successful
447  /// - AK_InvalidParameter if the threshold was not between 0 and -96.3 dB.
448  /// - AK_InvalidFloatValue if the value specified was NaN or Inf
449  AK_EXTERNAPIFUNC( AKRESULT, SetVolumeThreshold )(
450  AkReal32 in_fVolumeThresholdDB ///< Volume Threshold, must be a value between 0 and -96.3 dB
451  );
452 
453  /// Allows the game to set the maximum number of non virtual voices to be played simultaneously.
454  /// This may be changed anytime once the sound engine was initialized.
455  /// If this function is not called, the used value will be the value specified in the platform specific project settings.
456  /// \return
457  /// - AK_InvalidParameter if the threshold was not between 1 and MaxUInt16.
458  /// - AK_Success if successful
459  AK_EXTERNAPIFUNC( AKRESULT, SetMaxNumVoicesLimit )(
460  AkUInt16 in_maxNumberVoices ///< Maximum number of non-virtual voices.
461  );
462 
463  //@}
464 
465  ////////////////////////////////////////////////////////////////////////
466  /// @name Rendering Audio
467  //@{
468 
469  /// Processes all commands in the sound engine's command queue.
470  /// This method has to be called periodically (usually once per game frame).
471  /// \sa
472  /// - \ref concept_events
473  /// - \ref soundengine_events
474  /// - <tt>AK::SoundEngine::PostEvent()</tt>
475  /// \return Always returns AK_Success
476  AK_EXTERNAPIFUNC( AKRESULT, RenderAudio )(
477  bool in_bAllowSyncRender = true ///< When AkInitSettings::bUseLEngineThread is false, RenderAudio may generate an audio buffer -- unless in_bAllowSyncRender is set to false. Use in_bAllowSyncRender=false when calling RenderAudio from a Sound Engine callback.
478  );
479 
480  //@}
481 
482  ////////////////////////////////////////////////////////////////////////
483  /// @name Component Registration
484  //@{
485 
486  /// Query interface to global plug-in context used for plug-in registration/initialization.
487  /// \return Global plug-in context.
488  AK_EXTERNAPIFUNC(AK::IAkGlobalPluginContext *, GetGlobalPluginContext)();
489 
490  /// Registers a plug-in with the sound engine and sets the callback functions to create the
491  /// plug-in and its parameter node.
492  /// \aknote
493  /// This function is deprecated. Registration is now automatic if you link plug-ins statically. If plug-ins are dynamic libraries (such as DLLs or SOs), use \c RegisterPluginDLL.
494  /// \endaknote
495  /// \sa
496  /// - \ref register_effects
497  /// - \ref plugin_xml
498  /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided or Ak_Fail otherwise. Possible reasons for an AK_Fail result are:
499  /// - Insufficient memory to register the plug-in
500  /// - Plug-in ID already registered
501  /// \remarks
502  /// Codecs and plug-ins must be registered before loading banks that use them.\n
503  /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
504  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
505  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
506  /// posting the event will fail.
507  AK_EXTERNAPIFUNC( AKRESULT, RegisterPlugin )(
508  AkPluginType in_eType, ///< Plug-in type (for example, source or effect)
509  AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
510  AkUInt32 in_ulPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file)
511  AkCreatePluginCallback in_pCreateFunc, ///< Pointer to the plug-in's creation function
512  AkCreateParamCallback in_pCreateParamFunc ///< Pointer to the plug-in's parameter node creation function
513  );
514 
515  /// Loads a plug-in dynamic library and registers it with the sound engine.
516  /// With dynamic linking, all plugins are automatically registered.
517  /// The plug-in DLL must be in the OS-specific library path or in the same location as the executable. If not, set AkInitSettings.szPluginDLLPath.
518  /// \return
519  /// - Ak_Success if successful.
520  /// - AK_FileNotFound if the DLL is not found in the OS path or if it has extraneous dependencies not found.
521  /// - AK_InvalidFile if the symbol g_pAKPluginList is not exported by the dynamic library
522  AK_EXTERNAPIFUNC( AKRESULT, RegisterPluginDLL ) (
523  const AkOSChar* in_DllName, ///< Name of the DLL to load, without "lib" prefix or extension.
524  const AkOSChar* in_DllPath = NULL ///< Optional path to the DLL. Will override szPLuginDLLPath that was set in AkInitSettings.
525  );
526 
527  /// Registers a codec type with the sound engine and set the callback functions to create the
528  /// codec's file source and bank source nodes.
529  /// \aknote
530  /// This function is deprecated. Registration is now automatic if you link plugins statically. If plugins are dynamic libraries (such as DLLs or SOs), use RegisterPluginDLL.
531  /// \endaknote
532  /// \sa
533  /// - \ref register_effects
534  /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided, or Ak_Fail otherwise. Possible reasons for an AK_Fail result are:
535  /// - Insufficient memory to register the codec
536  /// - Codec ID already registered
537  /// \remarks
538  /// Codecs and plug-ins must be registered before loading banks that use them.\n
539  /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
540  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
541  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
542  /// posting the Event will fail.
543  AK_EXTERNAPIFUNC( AKRESULT, RegisterCodec )(
544  AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
545  AkUInt32 in_ulCodecID, ///< Codec identifier (as declared in the plug-in description XML file)
546  AkCreateFileSourceCallback in_pFileCreateFunc, ///< Pointer to the codec's file source node creation function
547  AkCreateBankSourceCallback in_pBankCreateFunc ///< Pointer to the codec's bank source node creation function
548  );
549 
550  /// Registers a global callback function. This function will be called from the audio rendering thread, at the
551  /// location specified by in_eLocation. This function will also be called from the thread calling
552  /// AK::SoundEngine::Term with in_eLocation set to AkGlobalCallbackLocation_Term.
553  /// For example, in order to be called at every audio rendering pass, and once during teardown for releasing resources, you would call
554  /// RegisterGlobalCallback(myCallback, AkGlobalCallbackLocation_BeginRender | AkGlobalCallbackLocation_Term, myCookie, AkPluginTypeNone, 0, 0);
555  /// \remarks
556  /// A Plugin Type, Company ID and Plugin ID can be provided to this function to enable timing in the performance montior.
557  /// If the callback is being timed, it will contribute to the Total Plug-in CPU measurement, and also appear in the Plug-ins tab of the Advanced Profiler by plug-in type and ID.
558  /// It is illegal to call this function while already inside of a global callback.
559  /// This function might stall for several milliseconds before returning.
560  /// \sa
561  /// - <tt>AK::SoundEngine::UnregisterGlobalCallback()</tt>
562  /// - AkGlobalCallbackFunc
563  /// - AkGlobalCallbackLocation
564  AK_EXTERNAPIFUNC(AKRESULT, RegisterGlobalCallback)(
565  AkGlobalCallbackFunc in_pCallback, ///< Function to register as a global callback.
566  AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender, ///< Callback location defined in AkGlobalCallbackLocation. Bitwise OR multiple locations if needed.
567  void * in_pCookie = NULL, ///< User cookie.
568  AkPluginType in_eType = AkPluginTypeNone, ///< Plug-in type (for example, source or effect). AkPluginTypeNone for no timing.
569  AkUInt32 in_ulCompanyID = 0, ///< Company identifier (as declared in the plug-in description XML file). 0 for no timing.
570  AkUInt32 in_ulPluginID = 0 ///< Plug-in identifier (as declared in the plug-in description XML file). 0 for no timing.
571  );
572 
573  /// Unregisters a global callback function, previously registered using RegisterGlobalCallback.
574  /// \remarks
575  /// It is legal to call this function while already inside of a global callback, If it is unregistering itself and not
576  /// another callback.
577  /// This function might stall for several milliseconds before returning.
578  /// \sa
579  /// - <tt>AK::SoundEngine::RegisterGlobalCallback()</tt>
580  /// - AkGlobalCallbackFunc
581  /// - AkGlobalCallbackLocation
582  AK_EXTERNAPIFUNC(AKRESULT, UnregisterGlobalCallback)(
583  AkGlobalCallbackFunc in_pCallback, ///< Function to unregister as a global callback.
584  AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender ///< Must match in_eLocation as passed to RegisterGlobalCallback for this callback.
585  );
586 
587  /// Registers a callback for the Audio Device status changes.
588  /// The callback will be called from the audio thread
589  /// Can be called prior to AK::SoundEngine::Init
590  AK_EXTERNAPIFUNC(AKRESULT, RegisterAudioDeviceStatusCallback)(
591  AK::AkDeviceStatusCallbackFunc in_pCallback ///< Function to register as a status callback.
592  );
593 
594  /// Unregisters the callback for the Audio Device status changes, registered by RegisterAudioDeviceStatusCallback
595  AK_EXTERNAPIFUNC(AKRESULT, UnregisterAudioDeviceStatusCallback)();
596  //@}
597 
598 #ifdef AK_SUPPORT_WCHAR
599  ////////////////////////////////////////////////////////////////////////
600  /// @name Getting ID from strings
601  //@{
602 
603  /// Universal converter from Unicode string to ID for the sound engine.
604  /// This function will hash the name based on a algorithm ( provided at : /AK/Tools/Common/AkFNVHash.h )
605  /// Note:
606  /// This function does return a AkUInt32, which is totally compatible with:
607  /// AkUniqueID, AkStateGroupID, AkStateID, AkSwitchGroupID, AkSwitchStateID, AkRtpcID, and so on...
608  /// \sa
609  /// - <tt>AK::SoundEngine::PostEvent</tt>
610  /// - <tt>AK::SoundEngine::SetRTPCValue</tt>
611  /// - <tt>AK::SoundEngine::SetSwitch</tt>
612  /// - <tt>AK::SoundEngine::SetState</tt>
613  /// - <tt>AK::SoundEngine::PostTrigger</tt>
614  /// - <tt>AK::SoundEngine::SetGameObjectAuxSendValues</tt>
615  /// - <tt>AK::SoundEngine::LoadBank</tt>
616  /// - <tt>AK::SoundEngine::UnloadBank</tt>
617  /// - <tt>AK::SoundEngine::PrepareEvent</tt>
618  /// - <tt>AK::SoundEngine::PrepareGameSyncs</tt>
619  AK_EXTERNAPIFUNC( AkUInt32, GetIDFromString )( const wchar_t* in_pszString );
620 #endif //AK_SUPPORT_WCHAR
621 
622  /// Universal converter from string to ID for the sound engine.
623  /// This function will hash the name based on a algorithm ( provided at : /AK/Tools/Common/AkFNVHash.h )
624  /// Note:
625  /// This function does return a AkUInt32, which is totally compatible with:
626  /// AkUniqueID, AkStateGroupID, AkStateID, AkSwitchGroupID, AkSwitchStateID, AkRtpcID, and so on...
627  /// \sa
628  /// - <tt>AK::SoundEngine::PostEvent</tt>
629  /// - <tt>AK::SoundEngine::SetRTPCValue</tt>
630  /// - <tt>AK::SoundEngine::SetSwitch</tt>
631  /// - <tt>AK::SoundEngine::SetState</tt>
632  /// - <tt>AK::SoundEngine::PostTrigger</tt>
633  /// - <tt>AK::SoundEngine::SetGameObjectAuxSendValues</tt>
634  /// - <tt>AK::SoundEngine::LoadBank</tt>
635  /// - <tt>AK::SoundEngine::UnloadBank</tt>
636  /// - <tt>AK::SoundEngine::PrepareEvent</tt>
637  /// - <tt>AK::SoundEngine::PrepareGameSyncs</tt>
638  AK_EXTERNAPIFUNC( AkUInt32, GetIDFromString )( const char* in_pszString );
639 
640  //@}
641 
642  ////////////////////////////////////////////////////////////////////////
643  /// @name Event Management
644  //@{
645 
646  /// Asynchronously posts an Event to the sound engine (by event ID).
647  /// The callback function can be used to be noticed when markers are reached or when the event is finished.
648  /// An array of wave file sources can be provided to resolve External Sources triggered by the event.
649  /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed
650  /// \remarks
651  /// If used, the array of external sources should contain the information for each external source triggered by the
652  /// event. When triggering an event with multiple external sources, you need to differentiate each source
653  /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
654  /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project
655  /// (therefore have a unique cookie) in order to tell them apart when filling the AkExternalSourceInfo structures.
656  /// \endaknote
657  /// \sa
658  /// - \ref concept_events
659  /// - \ref integrating_external_sources
660  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
661  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
662  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
663  AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
664  AkUniqueID in_eventID, ///< Unique ID of the event
665  AkGameObjectID in_gameObjectID, ///< Associated game object ID
666  AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
667  AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
668  void * in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information
669  AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
670  AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
671  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID///< Optional (advanced users only) Specify the playing ID to target with the event. Will Cause active actions in this event to target an existing Playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any for normal playback.
672  );
673 
674 #ifdef AK_SUPPORT_WCHAR
675  /// Posts an Event to the sound engine (by Event name), using callbacks.
676  /// The callback function can be used to be noticed when markers are reached or when the event is finished.
677  /// An array of wave file sources can be provided to resolve External Sources triggered by the event.
678  /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed
679  /// \remarks
680  /// If used, the array of external sources should contain the information for each external source triggered by the
681  /// event. When triggering an event with multiple external sources, you need to differentiate each source
682  /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
683  /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project
684  /// (therefore have a unique cookie) in order to tell them appart when filling the AkExternalSourceInfo structures.
685  /// \endaknote
686  /// \sa
687  /// - \ref concept_events
688  /// - \ref integrating_external_sources
689  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
690  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
691  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
692  AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
693  const wchar_t* in_pszEventName, ///< Name of the event
694  AkGameObjectID in_gameObjectID, ///< Associated game object ID
695  AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
696  AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
697  void * in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information.
698  AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
699  AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
700  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID///< Optional (advanced users only) Specify the playing ID to target with the event. Will Cause active actions in this event to target an existing Playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any for normal playback.
701  );
702 #endif //AK_SUPPORT_WCHAR
703 
704  /// Posts an Event to the sound engine (by Event name), using callbacks.
705  /// The callback function can be used to be noticed when markers are reached or when the event is finished.
706  /// An array of Wave file sources can be provided to resolve External Sources triggered by the event. P
707  /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed
708  /// \remarks
709  /// If used, the array of external sources should contain the information for each external source triggered by the
710  /// event. When triggering an Event with multiple external sources, you need to differentiate each source
711  /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
712  /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project
713  /// (therefore have a unique cookie) in order to tell them apart when filling the AkExternalSourceInfo structures.
714  /// \endaknote
715  /// \sa
716  /// - \ref concept_events
717  /// - \ref integrating_external_sources
718  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
719  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
720  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
721  AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
722  const char* in_pszEventName, ///< Name of the event
723  AkGameObjectID in_gameObjectID, ///< Associated game object ID
724  AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
725  AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
726  void * in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information.
727  AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
728  AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
729  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID///< Optional (advanced users only) Specify the playing ID to target with the event. Will Cause active actions in this event to target an existing Playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any for normal playback.
730  );
731 
732  // If you modify AkActionOnEventType, don't forget to modify the WAAPI validation schema accordingly.
733 
734  /// AkActionOnEventType
735  /// \sa
736  /// - <tt>AK::SoundEngine::ExecuteActionOnEvent()</tt>
738  {
739  AkActionOnEventType_Stop = 0, ///< Stop
740  AkActionOnEventType_Pause = 1, ///< Pause
741  AkActionOnEventType_Resume = 2, ///< Resume
742  AkActionOnEventType_Break = 3, ///< Break
743  AkActionOnEventType_ReleaseEnvelope = 4 ///< Release envelope
744  };
745 
746  /// Executes an action on all nodes that are referenced in the specified event in an action of type play.
747  /// \sa
748  /// - <tt>AK::SoundEngine::AkActionOnEventType</tt>
749  AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
750  AkUniqueID in_eventID, ///< Unique ID of the event
751  AkActionOnEventType in_ActionType, ///< Action to execute on all the elements that were played using the specified event.
752  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT, ///< Associated game object ID
753  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
754  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the transition
755  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Associated PlayingID
756  );
757 
758 #ifdef AK_SUPPORT_WCHAR
759  /// Executes an action on all nodes that are referenced in the specified event in an action of type play.
760  /// \sa
761  /// - <tt>AK::SoundEngine::AkActionOnEventType</tt>
762  AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
763  const wchar_t* in_pszEventName, ///< Name of the event
764  AkActionOnEventType in_ActionType, ///< Action to execute on all the elements that were played using the specified event.
765  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT, ///< Associated game object ID
766  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
767  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the transition
768  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Associated PlayingID
769  );
770 #endif //AK_SUPPORT_WCHAR
771 
772  /// Executes an Action on all nodes that are referenced in the specified Event in an Action of type Play.
773  /// \sa
774  /// - <tt>AK::SoundEngine::AkActionOnEventType</tt>
775  AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
776  const char* in_pszEventName, ///< Name of the event
777  AkActionOnEventType in_ActionType, ///< Action to execute on all the elements that were played using the specified event.
778  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT, ///< Associated game object ID
779  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
780  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the transition
781  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Associated PlayingID
782  );
783 
784 
785  /// Executes a number of MIDI Events on all nodes that are referenced in the specified Event in an Action of type Play.
786  /// Each MIDI event will be posted in AkMIDIPost::uOffset samples from the start of the current frame. The duration of
787  /// a sample can be determined from the sound engine's audio settings, via a call to AK::SoundEngine::GetAudioSettings.
788  /// \sa
789  /// - <tt>AK::SoundEngine::GetAudioSettings</tt>
790  /// - <tt>AK::SoundEngine::StopMIDIOnEvent</tt>
791  AK_EXTERNAPIFUNC( AKRESULT, PostMIDIOnEvent )(
792  AkUniqueID in_eventID, ///< Unique ID of the Event
793  AkGameObjectID in_gameObjectID, ///< Associated game object ID
794  AkMIDIPost* in_pPosts, ///< MIDI Events to post
795  AkUInt16 in_uNumPosts ///< Number of MIDI Events to post
796  );
797 
798  /// Stops MIDI notes on all nodes that are referenced in the specified event in an action of type play,
799  /// with the specified Game Object. Invalid parameters are interpreted as wildcards. For example, calling
800  /// this function with in_eventID set to AK_INVALID_UNIQUE_ID will stop all MIDI notes for Game Object
801  /// in_gameObjectID.
802  /// \sa
803  /// - <tt>AK::SoundEngine::PostMIDIOnEvent</tt>
804  AK_EXTERNAPIFUNC( AKRESULT, StopMIDIOnEvent )(
805  AkUniqueID in_eventID = AK_INVALID_UNIQUE_ID, ///< Unique ID of the Event
806  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< Associated game object ID
807  );
808 
809 
810  /// Starts streaming the first part of all streamed files referenced by an Event into a cache buffer. Caching streams are serviced when no other streams require the
811  /// available bandwidth. The files will remain cached until UnpinEventInStreamCache is called, or a higher priority pinned file needs the space and the limit set by
812  /// uMaxCachePinnedBytes is exceeded.
813  /// \remarks The amount of data from the start of the file that will be pinned to cache is determined by the prefetch size. The prefetch size is set via the authoring tool and stored in the sound banks.
814  /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO. For more information see <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt> and AkFileSystemFlags.
815  /// \remarks If this function is called additional times with the same event, then the priority of the caching streams are updated. Note however that priority is passed down to the stream manager
816  /// on a file-by-file basis, and if another event is pinned to cache that references the same file but with a different priority, then the first priority will be updated with the most recent value.
817  /// \remarks If the event references files that are chosen based on a State Group (via a switch container), all files in all states will be cached. Those in the current active state
818  /// will get cached with active priority, while all other files will get cached with inactive priority.
819  /// \remarks in_uInactivePriority is only relevant for events that reference switch containers that are assigned to State Groups. This parameter is ignored for all other events, including events that only reference
820  /// switch containers that are assigned to Switch Groups. Files that are chosen based on a Switch Group have a different switch value per game object, and are all effectively considered active by the pin-to-cache system.
821  /// \sa
822  /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
823  /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
824  /// - <tt>AK::StreamMgr::IAkFileLocationResolver::Open</tt>
825  /// - AkFileSystemFlags
826  AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
827  AkUniqueID in_eventID, ///< Unique ID of the event
828  AkPriority in_uActivePriority, ///< Priority of active stream caching I/O
829  AkPriority in_uInactivePriority ///< Priority of inactive stream caching I/O
830  );
831 
832 #ifdef AK_SUPPORT_WCHAR
833  /// Starts streaming the first part of all streamed files referenced by an event into a cache buffer. Caching streams are serviced when no other streams require the
834  /// available bandwidth. The files will remain cached until UnpinEventInStreamCache is called, or a higher priority pinned file needs the space and the limit set by
835  /// uMaxCachePinnedBytes is exceeded.
836  /// \remarks The amount of data from the start of the file that will be pinned to cache is determined by the prefetch size. The prefetch size is set via the authoring tool and stored in the sound banks.
837  /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO. For more information see <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt> and AkFileSystemFlags.
838  /// \remarks If this function is called additional times with the same event, then the priority of the caching streams are updated. Note however that priority is passed down to the stream manager
839  /// on a file-by-file basis, and if another event is pinned to cache that references the same file but with a different priority, then the first priority will be updated with the most recent value.
840  /// \remarks If the event references files that are chosen based on a State Group (via a Switch Container), all files in all states will be cached. Those in the current active state
841  /// will get cached with active priority, while all other files will get cached with inactive priority.
842  /// \remarks in_uInactivePriority is only relevant for events that reference switch containers that are assigned to State Groups. This parameter is ignored for all other events, including events that only reference
843  /// switch containers that are assigned to Switch Groups. Files that are chosen based on a Switch Group have a different switch value per game object, and are all effectively considered active by the pin-to-cache system.
844  /// \sa
845  /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
846  /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
847  /// - <tt>AK::StreamMgr::IAkFileLocationResolver::Open</tt>
848  /// - AkFileSystemFlags
849  AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
850  const wchar_t* in_pszEventName, ///< Name of the event
851  AkPriority in_uActivePriority, ///< Priority of active stream caching I/O
852  AkPriority in_uInactivePriority ///< Priority of inactive stream caching I/O
853  );
854 #endif //AK_SUPPORT_WCHAR
855 
856  /// Starts streaming the first part of all streamed files referenced by an event into a cache buffer. Caching streams are serviced when no other streams require the
857  /// available bandwidth. The files will remain cached until UnpinEventInStreamCache is called, or a higher priority pinned file needs the space and the limit set by
858  /// uMaxCachePinnedBytes is exceeded.
859  /// \remarks The amount of data from the start of the file that will be pinned to cache is determined by the prefetch size. The prefetch size is set via the authoring tool and stored in the sound banks.
860  /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO. For more information see <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt> and AkFileSystemFlags.
861  /// \remarks If this function is called additional times with the same event, then the priority of the caching streams are updated. Note however that priority is passed down to the stream manager
862  /// on a file-by-file basis, and if another event is pinned to cache that references the same file but with a different priority, then the first priority will be updated with the most recent value.
863  /// \remarks If the event references files that are chosen based on a State Group (via a switch container), all files in all states will be cached. Those in the current active state
864  /// will get cached with active priority, while all other files will get cached with inactive priority.
865  /// \remarks in_uInactivePriority is only relevant for events that reference switch containers that are assigned to State Groups. This parameter is ignored for all other events, including events that only reference
866  /// switch containers that are assigned to Switch Groups. Files that are chosen based on a Switch Group have a different switch value per game object, and are all effectively considered active by the pin-to-cache system.
867  /// \sa
868  /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
869  /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
870  /// - <tt>AK::StreamMgr::IAkFileLocationResolver::Open</tt>
871  /// - AkFileSystemFlags
872  AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
873  const char* in_pszEventName, ///< Name of the event
874  AkPriority in_uActivePriority, ///< Priority of active stream caching I/O
875  AkPriority in_uInactivePriority ///< Priority of inactive stream caching I/O
876  );
877 
878  /// Releases the set of files that were previously requested to be pinned into cache via <tt>AK::SoundEngine::PinEventInStreamCache()</tt>. The file may still remain in stream cache
879  /// after <tt>AK::SoundEngine::UnpinEventInStreamCache()</tt> is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
880  /// \sa
881  /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
882  /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
883  AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
884  AkUniqueID in_eventID ///< Unique ID of the event
885  );
886 
887 #ifdef AK_SUPPORT_WCHAR
888  /// Releases the set of files that were previously requested to be pinned into cache via <tt>AK::SoundEngine::PinEventInStreamCache()</tt>. The file may still remain in stream cache
889  /// after <tt>AK::SoundEngine::UnpinEventInStreamCache()</tt> is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
890  /// \sa
891  /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
892  /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
893  AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
894  const wchar_t* in_pszEventName ///< Name of the event
895  );
896 #endif //AK_SUPPORT_WCHAR
897 
898  /// Releases the set of files that were previously requested to be pinned into cache via <tt>AK::SoundEngine::PinEventInStreamCache()</tt>. The file may still remain in stream cache
899  /// after <tt>AK::SoundEngine::UnpinEventInStreamCache()</tt> is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
900  /// \sa
901  /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
902  /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
903  AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
904  const char* in_pszEventName ///< Name of the event
905  );
906 
907  /// Returns information about an Event that was requested to be pinned into cache via <tt>AK::SoundEngine::PinEventInStreamCache()</tt>.
908  /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether
909  /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
910  /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see \c AkDeviceSettings
911  /// \sa
912  /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
913  /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
914  /// - AkDeviceSettings
915  AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
916  AkUniqueID in_eventID, ///< Unique ID of the event
917  AkReal32& out_fPercentBuffered, ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
918  bool& out_bCachePinnedMemoryFull ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
919  );
920 
921  /// Returns information about an Event that was requested to be pinned into cache via \c <tt>AK::SoundEngine::PinEventInStreamCache()</tt>.
922  /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether
923  /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
924  /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see AkDeviceSettings
925  /// \sa
926  /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
927  /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
928  /// - AkDeviceSettings
929  AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
930  const char* in_pszEventName, ///< Name of the event
931  AkReal32& out_fPercentBuffered, ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
932  bool& out_bCachePinnedMemoryFull ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
933  );
934 
935 #ifdef AK_SUPPORT_WCHAR
936  /// Returns information about an Event that was requested to be pinned into cache via \c <tt>AK::SoundEngine::PinEventInStreamCache()</tt>.
937  /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether
938  /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
939  /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see AkDeviceSettings
940  /// \sa
941  /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
942  /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
943  /// - AkDeviceSettings
944  AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
945  const wchar_t* in_pszEventName, ///< Name of the event
946  AkReal32& out_fPercentBuffered, ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
947  bool& out_bCachePinnedMemoryFull ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
948  );
949 #endif
950 
951  /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
952  ///
953  /// Notes:
954  /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
955  /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
956  /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
957  /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
958  /// the sound that is currently playing is the first sound of the sequence.
959  /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
960  /// - Sounds/segments are stopped if in_iPosition is greater than their duration.
961  /// - in_iPosition is clamped internally to the beginning of the sound/segment.
962  /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
963  /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
964  /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
965  /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
966  /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
967  /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
968  /// - This method posts a command in the sound engine queue, thus seeking will not occur before
969  /// the audio thread consumes it (after a call to RenderAudio()).
970  ///
971  /// Notes specific to Music Segments:
972  /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
973  /// value to seek within the Pre-Entry.
974  /// - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification
975  /// in order to restart them if required.
976  /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
977  /// take the "look-ahead time" property of their streamed tracks into account for seeking.
978  /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
979  /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
980  /// the exact position of a segment. Also, the segment will be silent during that time
981  /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
982  /// also informs you about the remaining look-ahead time.
983  ///
984  /// Notes specific to Music Switch Containers:
985  /// - Seeking triggers a music transition towards the current (or target) segment.
986  /// This transition is subject to the container's transition rule that matches the current and defined in the container,
987  /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
988  /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
989  /// - If the specified time is greater than the destination segment's length, the modulo is taken.
990  ///
991  /// \sa
992  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
993  /// - <tt>AK::SoundEngine::PostEvent()</tt>
994  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
995  /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
996  AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
997  AkUniqueID in_eventID, ///< Unique ID of the event
998  AkGameObjectID in_gameObjectID, ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
999  AkTimeMs in_iPosition, ///< Desired position where playback should restart, in milliseconds
1000  bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
1001  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
1002  );
1003 
1004 #ifdef AK_SUPPORT_WCHAR
1005  /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
1006  ///
1007  /// Notes:
1008  /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
1009  /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
1010  /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
1011  /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
1012  /// the sound that is currently playing is the first sound of the sequence.
1013  /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
1014  /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
1015  /// value to seek within the Pre-Entry.
1016  /// - Sounds/segments are stopped if in_iPosition is greater than their duration.
1017  /// - in_iPosition is clamped internally to the beginning of the sound/segment.
1018  /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
1019  /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
1020  /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
1021  /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
1022  /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
1023  /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
1024  /// - This method posts a command in the sound engine queue, thus seeking will not occur before
1025  /// the audio thread consumes it (after a call to RenderAudio()).
1026  ///
1027  /// Notes specific to Music Segments:
1028  /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
1029  /// value to seek within the Pre-Entry.
1030  /// - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification
1031  /// in order to restart them if required.
1032  /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
1033  /// take the "look-ahead time" property of their streamed tracks into account for seeking.
1034  /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
1035  /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
1036  /// the exact position of a segment. Also, the segment will be silent during that time
1037  /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1038  /// also informs you about the remaining look-ahead time.
1039  ///
1040  /// Notes specific to Music Switch Containers:
1041  /// - Seeking triggers a music transition towards the current (or target) segment.
1042  /// This transition is subject to the container's transition rule that matches the current and defined in the container,
1043  /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
1044  /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
1045  /// - If the specified time is greater than the destination segment's length, the modulo is taken.
1046  ///
1047  /// \sa
1048  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
1049  /// - <tt>AK::SoundEngine::PostEvent()</tt>
1050  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
1051  /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1052  AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
1053  const wchar_t* in_pszEventName, ///< Name of the event
1054  AkGameObjectID in_gameObjectID, ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
1055  AkTimeMs in_iPosition, ///< Desired position where playback should restart, in milliseconds
1056  bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
1057  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
1058  );
1059 #endif //AK_SUPPORT_WCHAR
1060 
1061  /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
1062  ///
1063  /// Notes:
1064  /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
1065  /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
1066  /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
1067  /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
1068  /// the sound that is currently playing is the first sound of the sequence.
1069  /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
1070  /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
1071  /// value to seek within the Pre-Entry.
1072  /// - Sounds/segments are stopped if in_iPosition is greater than their duration.
1073  /// - in_iPosition is clamped internally to the beginning of the sound/segment.
1074  /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
1075  /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
1076  /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
1077  /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
1078  /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
1079  /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
1080  /// - This method posts a command in the sound engine queue, thus seeking will not occur before
1081  /// the audio thread consumes it (after a call to RenderAudio()).
1082  ///
1083  /// Notes specific to Music Segments:
1084  /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
1085  /// value to seek within the Pre-Entry.
1086  /// - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification
1087  /// in order to restart them if required.
1088  /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
1089  /// take the "look-ahead time" property of their streamed tracks into account for seeking.
1090  /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
1091  /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
1092  /// the exact position of a segment. Also, the segment will be silent during that time
1093  /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1094  /// also informs you about the remaining look-ahead time.
1095  ///
1096  /// Notes specific to Music Switch Containers:
1097  /// - Seeking triggers a music transition towards the current (or target) segment.
1098  /// This transition is subject to the container's transition rule that matches the current and defined in the container,
1099  /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
1100  /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
1101  /// - If the specified time is greater than the destination segment's length, the modulo is taken.
1102  ///
1103  /// \sa
1104  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
1105  /// - <tt>AK::SoundEngine::PostEvent()</tt>
1106  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
1107  /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1108  AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
1109  const char* in_pszEventName, ///< Name of the event
1110  AkGameObjectID in_gameObjectID, ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
1111  AkTimeMs in_iPosition, ///< Desired position where playback should restart, in milliseconds
1112  bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
1113  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
1114  );
1115 
1116  /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
1117  /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account.
1118  ///
1119  /// Notes:
1120  /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
1121  /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
1122  /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
1123  /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
1124  /// the sound that is currently playing is the first sound of the sequence.
1125  /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
1126  /// - in_iPosition is clamped internally to the beginning of the sound/segment.
1127  /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
1128  /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
1129  /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
1130  /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
1131  /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
1132  /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
1133  /// - This method posts a command in the sound engine queue, thus seeking will not occur before
1134  /// the audio thread consumes it (after a call to RenderAudio()).
1135  ///
1136  /// Notes specific to Music Segments:
1137  /// - With Music Segments, \c in_fPercent is relative to the Entry Cue, and the segment's duration is the
1138  /// duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
1139  /// post-exit of a segment using this method. Use absolute values instead.
1140  /// - Music Segments cannot be looped. You may want to listen to the \c AK_EndOfEvent notification
1141  /// in order to restart them if required.
1142  /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
1143  /// take the "look-ahead time" property of their streamed tracks into account for seeking.
1144  /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
1145  /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
1146  /// the exact position of a segment. Also, the segment will be silent during the time that period
1147  /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1148  /// also informs you about the remaining look-ahead time.
1149  ///
1150  /// Notes specific to Music Switch Containers:
1151  /// - Seeking triggers a music transition towards the current (or target) segment.
1152  /// This transition is subject to the container's transition rule that matches the current and defined in the container,
1153  /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
1154  /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
1155  /// - If the specified time is greater than the destination segment's length, the modulo is taken.
1156  ///
1157  /// \sa
1158  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
1159  /// - <tt>AK::SoundEngine::PostEvent()</tt>
1160  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
1161  /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1162  AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
1163  AkUniqueID in_eventID, ///< Unique ID of the event
1164  AkGameObjectID in_gameObjectID , ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
1165  AkReal32 in_fPercent, ///< Desired position where playback should restart, expressed in a percentage of the file's total duration, between 0 and 1.f (see note above about infinite looping sounds)
1166  bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
1167  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
1168  );
1169 
1170 #ifdef AK_SUPPORT_WCHAR
1171  /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
1172  /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account.
1173  ///
1174  /// Notes:
1175  /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
1176  /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
1177  /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
1178  /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
1179  /// the sound that is currently playing is the first sound of the sequence.
1180  /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
1181  /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
1182  /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
1183  /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
1184  /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
1185  /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
1186  /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
1187  /// - This method posts a command in the sound engine queue, thus seeking will not occur before
1188  /// the audio thread consumes it (after a call to RenderAudio()).
1189  ///
1190  /// Notes specific to Music Segments:
1191  /// - With Music Segments, \c in_fPercent is relative to the Entry Cue, and the segment's duration is the
1192  /// duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
1193  /// post-exit of a segment using this method. Use absolute values instead.
1194  /// - Music Segments cannot be looped. You may want to listen to the \c AK_EndOfEvent notification
1195  /// in order to restart them if required.
1196  /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
1197  /// take the "look-ahead time" property of their streamed tracks into account for seeking.
1198  /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
1199  /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
1200  /// the exact position of a segment. Also, the segment will be silent during the time that period
1201  /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1202  /// also informs you about the remaining look-ahead time.
1203  ///
1204  /// Notes specific to Music Switch Containers:
1205  /// - Seeking triggers a music transition towards the current (or target) segment.
1206  /// This transition is subject to the container's transition rule that matches the current and defined in the container,
1207  /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
1208  /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
1209  /// - If the specified time is greater than the destination segment's length, the modulo is taken.
1210  ///
1211  /// \sa
1212  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
1213  /// - <tt>AK::SoundEngine::PostEvent()</tt>
1214  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
1215  /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1216  AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
1217  const wchar_t* in_pszEventName, ///< Name of the event
1218  AkGameObjectID in_gameObjectID , ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
1219  AkReal32 in_fPercent , ///< Desired position where playback should restart, expressed in a percentage of the file's total duration, between 0 and 1.f (see note above about infinite looping sounds)
1220  bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
1221  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
1222  );
1223 #endif //AK_SUPPORT_WCHAR
1224 
1225  /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
1226  /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account.
1227  ///
1228  /// Notes:
1229  /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
1230  /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
1231  /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
1232  /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
1233  /// the sound that is currently playing is the first sound of the sequence.
1234  /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
1235  /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
1236  /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
1237  /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
1238  /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
1239  /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
1240  /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
1241  /// - This method posts a command in the sound engine queue, thus seeking will not occur before
1242  /// the audio thread consumes it (after a call to RenderAudio()).
1243  ///
1244  /// Notes specific to Music Segments:
1245  /// - With Music Segments, in_fPercent is relative to the Entry Cue, and the segment's duration is the
1246  /// duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
1247  /// post-exit of a segment using this method. Use absolute values instead.
1248  /// - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification
1249  /// in order to restart them if required.
1250  /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
1251  /// take the "look-ahead time" property of their streamed tracks into account for seeking.
1252  /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
1253  /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
1254  /// the exact position of a segment. Also, the segment will be silent during the time that period
1255  /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1256  /// also informs you about the remaining look-ahead time.
1257  ///
1258  /// Notes specific to Music Switch Containers:
1259  /// - Seeking triggers a music transition towards the current (or target) segment.
1260  /// This transition is subject to the container's transition rule that matches the current and defined in the container,
1261  /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
1262  /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
1263  /// - If the specified time is greater than the destination segment's length, the modulo is taken.
1264  ///
1265  /// \sa
1266  /// - <tt>AK::SoundEngine::RenderAudio()</tt>
1267  /// - <tt>AK::SoundEngine::PostEvent()</tt>
1268  /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
1269  /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
1270  AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
1271  const char* in_pszEventName, ///< Name of the event
1272  AkGameObjectID in_gameObjectID, ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
1273  AkReal32 in_fPercent, ///< Desired position where playback should restart, expressed in a percentage of the file's total duration, between 0 and 1.f (see note above about infinite looping sounds)
1274  bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see notes above).
1275  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
1276  );
1277 
1278  /// Cancels all Event callbacks associated with a specific callback cookie.\n
1279  /// \sa
1280  /// - \c <tt>AK::SoundEngine::PostEvent()</tt>
1281  AK_EXTERNAPIFUNC( void, CancelEventCallbackCookie )(
1282  void * in_pCookie ///< Callback cookie to be cancelled
1283  );
1284 
1285  /// Cancels all Event callbacks associated with a specific game object.\n
1286  /// \sa
1287  /// - \c <tt>AK::SoundEngine::PostEvent()</tt>
1288  AK_EXTERNAPIFUNC( void, CancelEventCallbackGameObject )(
1289  AkGameObjectID in_gameObjectID ///< ID of the game object to be cancelled
1290  );
1291 
1292  /// Cancels all Event callbacks for a specific playing ID.
1293  /// \sa
1294  /// - \c <tt>AK::SoundEngine::PostEvent()</tt>
1295  AK_EXTERNAPIFUNC( void, CancelEventCallback )(
1296  AkPlayingID in_playingID ///< Playing ID of the event that must not use callbacks
1297  );
1298 
1299  /// Gets the current position of the source associated with this playing ID, obtained from PostEvent(). If more than one source is playing,
1300  /// the first to play is returned.
1301  /// Notes:
1302  /// - You need to pass AK_EnableGetSourcePlayPosition to PostEvent() in order to use this function, otherwise
1303  /// it returns AK_Fail, even if the playing ID is valid.
1304  /// - The source's position is updated at every audio frame, and the time at which this occurs is stored.
1305  /// When you call this function from your thread, you therefore query the position that was updated in the previous audio frame.
1306  /// If in_bExtrapolate is true (default), the returned position is extrapolated using the elapsed time since last
1307  /// sound engine update and the source's playback rate.
1308  /// \return AK_Success if successful.
1309  /// It returns AK_InvalidParameter if the provided pointer is not valid.
1310  /// It returns AK_Fail if the playing ID is invalid (not playing yet, or finished playing).
1311  /// \sa
1312  /// - \ref soundengine_query_pos
1313  /// - \ref concept_events
1314  AK_EXTERNAPIFUNC( AKRESULT, GetSourcePlayPosition )(
1315  AkPlayingID in_PlayingID, ///< Playing ID returned by <tt>AK::SoundEngine::PostEvent()</tt>
1316  AkTimeMs* out_puPosition, ///< Position of the source (in ms) associated with the specified playing ID
1317  bool in_bExtrapolate = true ///< Position is extrapolated based on time elapsed since last sound engine update.
1318  );
1319 
1320  /// Gets the current position of the sources associated with this playing ID, obtained from PostEvent().
1321  /// Notes:
1322  /// - You need to pass AK_EnableGetSourcePlayPosition to PostEvent() in order to use this function, otherwise
1323  /// it returns AK_Fail, even if the playing ID is valid.
1324  /// - The source's position is updated at every audio frame, and the time at which this occurs is stored.
1325  /// When you call this function from your thread, you therefore query the position that was updated in the previous audio frame.
1326  /// If in_bExtrapolate is true (default), the returned position is extrapolated using the elapsed time since last
1327  /// sound engine update and the source's playback rate.
1328  /// - If 0 is passed in for the number of entries (*in_pcPositions == 0) then only the number of positions will be returned and the
1329  /// position array (out_puPositions) will not be updated.
1330  /// - The io_pcPositions pointer must be non-NULL.
1331  /// out_puPositions may be NULL if *io_pcPositions == 0, otherwise it must be non-NULL.
1332  /// \return AK_Success if successful.
1333  /// It returns AK_InvalidParameter if the provided pointers are not valid.
1334  /// It returns AK_Fail if the playing ID is invalid (not playing yet, or finished playing).
1335  /// \sa
1336  /// - \ref soundengine_query_pos
1337  /// - \ref concept_events
1338  AK_EXTERNAPIFUNC(AKRESULT, GetSourcePlayPositions)(
1339  AkPlayingID in_PlayingID, ///< Playing ID returned by <tt>AK::SoundEngine::PostEvent()</tt>
1340  AkSourcePosition* out_puPositions, ///< Audio Node IDs and positions of sources associated with the specified playing ID
1341  AkUInt32 * io_pcPositions, ///< Number of entries in out_puPositions. Needs to be set to the size of the array: it is adjusted to the actual number of returned entries
1342  bool in_bExtrapolate = true ///< Position is extrapolated based on time elapsed since last sound engine update
1343  );
1344 
1345  /// Gets the stream buffering of the sources associated with this playing ID, obtained from PostEvent().
1346  /// Notes:
1347  /// - You need to pass AK_EnableGetSourceStreamBuffering to PostEvent() in order to use this function, otherwise
1348  /// it returns AK_Fail, even if the playing ID is valid.
1349  /// - The sources stream buffering is updated at every audio frame. If there are multiple sources associated with this playing ID,
1350  /// the value returned corresponds to the least buffered source.
1351  /// - The returned buffering status out_bIsBuffering will be true If any of the sources associated with the playing ID are actively being buffered.
1352  /// It will be false if all of them have reached the end of file, or have reached a state where they are buffered enough and streaming is temporarily idle.
1353  /// - Purely in-memory sources are excluded from this database. If all sources are in-memory, GetSourceStreamBuffering() will return AK_Fail.
1354  /// - The returned buffering amount and state is not completely accurate with some hardware-accelerated codecs. In such cases, the amount of stream buffering is generally underestimated.
1355  /// On the other hand, it is not guaranteed that the source will be ready to produce data at the next audio frame even if out_bIsBuffering has turned to false.
1356  /// \return
1357  /// - AK_Success if successful.
1358  /// - AK_Fail if the source data associated with this playing ID is not found, for example if PostEvent() was not called with AK_EnableGetSourceStreamBuffering, or if the header was not parsed.
1359  /// \sa
1360  /// - \ref concept_events
1361  AK_EXTERNAPIFUNC( AKRESULT, GetSourceStreamBuffering )(
1362  AkPlayingID in_PlayingID, ///< Playing ID returned by <tt>AK::SoundEngine::PostEvent()</tt>
1363  AkTimeMs & out_buffering, ///< Returned amount of buffering (in ms) of the source (or one of the sources) associated with that playing ID
1364  bool & out_bIsBuffering ///< Returned buffering status of the source(s) associated with that playing ID
1365  );
1366 
1367  /// Stops the current content playing associated to the specified game object ID.
1368  /// If no game object is specified, all sounds will be stopped.
1369  AK_EXTERNAPIFUNC( void, StopAll )(
1370  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< (Optional)Specify a game object to stop only playback associated to the provided game object ID.
1371  );
1372 
1373  /// Stop the current content playing associated to the specified playing ID.
1374  /// \aknote
1375  /// This function is deprecated. Please use ExecuteActionOnPlayingID() in its place.
1376  /// \endaknote
1377  /// \sa
1378  /// - <tt>AK::SoundEngine::ExecuteActionOnPlayingID()</tt>
1379  AK_EXTERNAPIFUNC( void, StopPlayingID )(
1380  AkPlayingID in_playingID, ///< Playing ID to be stopped.
1381  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
1382  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
1383  );
1384 
1385  /// Executes an Action on the content associated to the specified playing ID.
1386  /// \sa
1387  /// - <tt>AK::SoundEngine::AkActionOnEventType</tt>
1388  AK_EXTERNAPIFUNC(void, ExecuteActionOnPlayingID)(
1389  AkActionOnEventType in_ActionType, ///< Action to execute on the specified playing ID.
1390  AkPlayingID in_playingID, ///< Playing ID on which to execute the action.
1391  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
1392  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
1393  );
1394 
1395  /// Sets the random seed value. Can be used to synchronize randomness
1396  /// across instances of the Sound Engine.
1397  /// \remark This seeds the number generator used for all container randomizations;
1398  /// since it acts globally, this should be called right before any PostEvent
1399  /// call where randomness synchronization is required, and cannot guarantee
1400  /// similar results for continuous containers.
1401  AK_EXTERNAPIFUNC( void, SetRandomSeed )(
1402  AkUInt32 in_uSeed ///< Random seed.
1403  );
1404 
1405  /// Mutes/Unmutes the busses tagged as background music.
1406  /// This is automatically called for platforms that have user-music support.
1407  /// This function is provided to give the same behavior on platforms that don't have user-music support.
1408  AK_EXTERNAPIFUNC( void, MuteBackgroundMusic ) (
1409  bool in_bMute ///< Sets true to mute, false to unmute.
1410  );
1411  //@}
1412 
1413  /// Gets the state of the Background Music busses. This state is either set directly
1414  /// with \c AK::SoundEngine::MuteBackgroundMusic or by the OS, if it has User Music services.
1415  /// \return true if the background music busses are muted, false if not.
1416  AK_EXTERNAPIFUNC(bool, GetBackgroundMusicMute) ();
1417  //@}
1418 
1419 
1420  /// Sends custom game data to a plug-in that resides on a bus (insert Effect or mixer plug-in).
1421  /// Data will be copied and stored into a separate list.
1422  /// Previous entry is deleted when a new one is sent.
1423  /// Sets the data pointer to NULL to clear item from the list.
1424  /// \aknote The plug-in type and ID is passed and matched with plugins set on the desired bus.
1425  /// This means that you cannot send different data to various instances of the plug-in on a same bus.\endaknote
1426  /// \return AK_Success if data was sent successfully.
1427  AK_EXTERNAPIFUNC( AKRESULT, SendPluginCustomGameData ) (
1428  AkUniqueID in_busID, ///< Bus ID
1429  AkGameObjectID in_busObjectID, ///< Bus Object ID. Pass AK_INVALID_GAME_OBJECT to send custom data with global scope. Game object scope supersedes global scope, as with RTPCs.
1430  AkPluginType in_eType, ///< Plug-in type (for example, source or effect)
1431  AkUInt32 in_uCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
1432  AkUInt32 in_uPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file)
1433  const void* in_pData, ///< The data blob
1434  AkUInt32 in_uSizeInBytes ///< Size of data
1435  );
1436  //@}
1437 
1438  ////////////////////////////////////////////////////////////////////////
1439  /// @name Game Objects
1440  //@{
1441 
1442  /// Registers a game object.
1443  /// \return
1444  /// - AK_Success if successful
1445  /// - AK_Fail if the specified AkGameObjectID is invalid (0 and -1 are invalid)
1446  /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no
1447  /// matter how many times it has been registered.
1448  /// \sa
1449  /// - <tt>AK::SoundEngine::UnregisterGameObj()</tt>
1450  /// - <tt>AK::SoundEngine::UnregisterAllGameObj()</tt>
1451  /// - \ref concept_gameobjects
1452  AK_EXTERNAPIFUNC(AKRESULT, RegisterGameObj)(
1453  AkGameObjectID in_gameObjectID ///< ID of the game object to be registered
1454  );
1455 
1456  /// Registers a game object.
1457  /// \return
1458  /// - AK_Success if successful
1459  /// - AK_Fail if the specified AkGameObjectID is invalid (0 and -1 are invalid)
1460  /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no
1461  /// matter how many times it has been registered.
1462  /// \sa
1463  /// - <tt>AK::SoundEngine::UnregisterGameObj()</tt>
1464  /// - <tt>AK::SoundEngine::UnregisterAllGameObj()</tt>
1465  /// - \ref concept_gameobjects
1466  AK_EXTERNAPIFUNC( AKRESULT, RegisterGameObj )(
1467  AkGameObjectID in_gameObjectID, ///< ID of the game object to be registered
1468  const char * in_pszObjName ///< Name of the game object (for monitoring purpose)
1469  );
1470 
1471  /// Unregisters a game object.
1472  /// \return
1473  /// - AK_Success if successful
1474  /// - AK_Fail if the specified AkGameObjectID is invalid (0 is an invalid ID)
1475  /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no
1476  /// matter how many times it has been registered. Unregistering a game object while it is
1477  /// in use is allowed, but the control over the parameters of this game object is lost.
1478  /// For example, say a sound associated with this game object is a 3D moving sound. This sound will
1479  /// stop moving when the game object is unregistered, and there will be no way to regain control over the game object.
1480  /// \sa
1481  /// - <tt>AK::SoundEngine::RegisterGameObj()</tt>
1482  /// - <tt>AK::SoundEngine::UnregisterAllGameObj()</tt>
1483  /// - \ref concept_gameobjects
1484  AK_EXTERNAPIFUNC( AKRESULT, UnregisterGameObj )(
1485  AkGameObjectID in_gameObjectID ///< ID of the game object to be unregistered. Use
1486  /// AK_INVALID_GAME_OBJECT to unregister all game objects.
1487  );
1488 
1489  /// Unregister all game objects, or all game objects with a particular matching set of property flags.
1490  /// This function to can be used to unregister all game objects.
1491  /// \return
1492  /// - AK_Success if successful
1493  /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no
1494  /// matter how many times it has been registered. Unregistering a game object while it is
1495  /// in use is allowed, but the control over the parameters of this game object is lost.
1496  /// For example, if a sound associated with this game object is a 3D moving sound, it will
1497  /// stop moving once the game object is unregistered, and there will be no way to recover
1498  /// the control over this game object.
1499  /// \sa
1500  /// - <tt>AK::SoundEngine::RegisterGameObj()</tt>
1501  /// - <tt>AK::SoundEngine::UnregisterGameObj()</tt>
1502  /// - \ref concept_gameobjects
1503  AK_EXTERNAPIFUNC( AKRESULT, UnregisterAllGameObj )(
1504  );
1505 
1506  /// Sets the position of a game object.
1507  /// \warning The object's orientation vector (in_Position.Orientation) must be normalized.
1508  /// \return
1509  /// - AK_Success when successful
1510  /// - AK_InvalidParameter if parameters are not valid.
1511  /// \sa
1512  /// - \ref soundengine_3dpositions
1513  AK_EXTERNAPIFUNC( AKRESULT, SetPosition )(
1514  AkGameObjectID in_GameObjectID, ///< Game Object identifier
1515  const AkSoundPosition & in_Position ///< Position to set; in_Position.Orientation must be normalized.
1516  );
1517 
1518  /// Sets multiple positions to a single game object.
1519  /// Setting multiple positions on a single game object is a way to simulate multiple emission sources while using the resources of only one voice.
1520  /// This can be used to simulate wall openings, area sounds, or multiple objects emitting the same sound in the same area.
1521  /// \aknote Calling <tt>AK::SoundEngine::SetMultiplePositions()</tt> with only one position is the same as calling <tt>AK::SoundEngine::SetPosition()</tt> \endaknote
1522  /// \return
1523  /// - AK_Success when successful
1524  /// - AK_InvalidParameter if parameters are not valid.
1525  /// \sa
1526  /// - \ref soundengine_3dpositions
1527  /// - \ref soundengine_3dpositions_multiplepos
1528  /// - \ref AK::SoundEngine::MultiPositionType
1529  AK_EXTERNAPIFUNC( AKRESULT, SetMultiplePositions )(
1530  AkGameObjectID in_GameObjectID, ///< Game Object identifier.
1531  const AkSoundPosition * in_pPositions, ///< Array of positions to apply.
1532  AkUInt16 in_NumPositions, ///< Number of positions specified in the provided array.
1533  MultiPositionType in_eMultiPositionType = MultiPositionType_MultiDirections ///< \ref AK::SoundEngine::MultiPositionType
1534  );
1535 
1536  /// Sets multiple positions to a single game object, with flexible assignment of input channels.
1537  /// Setting multiple positions on a single game object is a way to simulate multiple emission sources while using the resources of only one voice.
1538  /// This can be used to simulate wall openings, area sounds, or multiple objects emitting the same sound in the same area.
1539  /// \aknote Calling <tt>AK::SoundEngine::SetMultiplePositions()</tt> with only one position is the same as calling <tt>AK::SoundEngine::SetPosition()</tt> \endaknote
1540  /// \return
1541  /// - AK_Success when successful
1542  /// - AK_InvalidParameter if parameters are not valid.
1543  /// \sa
1544  /// - \ref soundengine_3dpositions
1545  /// - \ref soundengine_3dpositions_multiplepos
1546  /// - \ref AK::SoundEngine::MultiPositionType
1547  AK_EXTERNAPIFUNC( AKRESULT, SetMultiplePositions )(
1548  AkGameObjectID in_GameObjectID, ///< Game Object identifier.
1549  const AkChannelEmitter * in_pPositions, ///< Array of positions to apply, each using its own channel mask.
1550  AkUInt16 in_NumPositions, ///< Number of positions specified in the provided array.
1551  MultiPositionType in_eMultiPositionType = MultiPositionType_MultiDirections ///< \ref AK::SoundEngine::MultiPositionType
1552  );
1553 
1554  /// Sets the scaling factor of a Game Object.
1555  /// Modify the attenuation computations on this Game Object to simulate sounds with a larger or smaller area of effect.
1556  /// \return
1557  /// - AK_Success when successful
1558  /// - AK_InvalidParameter if the scaling factor specified was 0 or negative.
1559  /// - AK_InvalidFloatValue if the value specified was NaN or Inf
1560  AK_EXTERNAPIFUNC( AKRESULT, SetScalingFactor )(
1561  AkGameObjectID in_GameObjectID, ///< Game object identifier
1562  AkReal32 in_fAttenuationScalingFactor ///< Scaling Factor, 1 means 100%, 0.5 means 50%, 2 means 200%, and so on.
1563  );
1564 
1565  //@}
1566 
1567  ////////////////////////////////////////////////////////////////////////
1568  /// @name Bank Management
1569  //@{
1570 
1571  /// Unload all currently loaded banks.
1572  /// It also internally calls ClearPreparedEvents() since at least one bank must have been loaded to allow preparing events.
1573  /// \return
1574  /// - AK_Success if successful
1575  /// - AK_Fail if the sound engine was not correctly initialized or if there is not enough memory to handle the command
1576  /// \sa
1577  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1578  /// - <tt>AK::SoundEngine::LoadBank()</tt>
1579  /// - \ref soundengine_banks
1580  AK_EXTERNAPIFUNC( AKRESULT, ClearBanks )();
1581 
1582  /// Sets the I/O settings of the bank load and prepare event processes.
1583  /// The sound engine uses default values unless explicitly set by calling this method.
1584  /// \warning This function must be called before loading banks.
1585  /// \return
1586  /// - AK_Success if successful
1587  /// - AK_Fail if the sound engine was not correctly initialized
1588  /// - AK_InvalidParameter if some parameters are invalid
1589  /// \sa
1590  /// - \ref soundengine_banks
1591  /// - \ref streamingdevicemanager
1592  AK_EXTERNAPIFUNC( AKRESULT, SetBankLoadIOSettings )(
1593  AkReal32 in_fThroughput, ///< Average throughput of bank data streaming (bytes/ms) (the default value is AK_DEFAULT_BANK_THROUGHPUT)
1594  AkPriority in_priority ///< Priority of bank streaming (the default value is AK_DEFAULT_PRIORITY)
1595  );
1596 
1597 #ifdef AK_SUPPORT_WCHAR
1598  /// Load a bank synchronously (by Unicode string).\n
1599  /// The bank name is passed to the Stream Manager.
1600  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
1601  /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
1602  /// A bank load request will be posted, and consumed by the Bank Manager thread.
1603  /// The function returns when the request has been completely processed.
1604  /// \return
1605  /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
1606  /// You may use this ID with UnloadBank().
1607  /// - AK_Success: Load or unload successful.
1608  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
1609  /// - AK_BankReadError: I/O error.
1610  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
1611  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
1612  /// - AK_InvalidFile: File specified could not be opened.
1613  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
1614  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
1615  /// \remarks
1616  /// - The initialization bank must be loaded first.
1617  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
1618  /// initialization bank. If you need to load SoundBanks from a different project, you
1619  /// must first unload ALL banks, including the initialization bank, then load the
1620  /// initialization bank from the other project, and finally load banks from that project.
1621  /// - Codecs and plug-ins must be registered before loading banks that use them.
1622  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1623  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1624  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1625  /// posting the event will fail.
1626  /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
1627  /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
1628  /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in
1629  /// your implementation of the Stream Manager, or in the Low-Level I/O module if you use the default Stream Manager's implementation.
1630  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
1631  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
1632  /// of the UnloadBank() function.
1633  /// \sa
1634  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1635  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
1636  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
1637  /// - <tt>AK::MemoryMgr::CreatePool()</tt>
1638  /// - \ref soundengine_banks
1639  /// - \ref integrating_elements_plugins
1640  /// - \ref streamingdevicemanager
1641  /// - \ref streamingmanager_lowlevel
1642  /// - \ref sdk_bank_training
1643  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
1644  const wchar_t* in_pszString, ///< Name of the bank to load
1645  AkMemPoolId in_memPoolId, ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
1646  AkBankID & out_bankID ///< Returned bank ID
1647  );
1648 #endif //AK_SUPPORT_WCHAR
1649 
1650  /// Loads a bank synchronously.\n
1651  /// The bank name is passed to the Stream Manager.
1652  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
1653  /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
1654  /// A bank load request will be posted, and consumed by the Bank Manager thread.
1655  /// The function returns when the request has been completely processed.
1656  /// \return
1657  /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
1658  /// You may use this ID with UnloadBank().
1659  /// - AK_Success: Load or unload successful.
1660  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
1661  /// - AK_BankReadError: I/O error.
1662  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
1663  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
1664  /// - AK_InvalidFile: File specified could not be opened.
1665  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
1666  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
1667  /// \remarks
1668  /// - The initialization bank must be loaded first.
1669  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
1670  /// initialization bank. If you need to load SoundBanks from a different project, you
1671  /// must first unload ALL banks, including the initialization bank, then load the
1672  /// initialization bank from the other project, and finally load banks from that project.
1673  /// - Codecs and plug-ins must be registered before loading banks that use them.
1674  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1675  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1676  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1677  /// posting the event will fail.
1678  /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
1679  /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
1680  /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in
1681  /// your implementation of the Stream Manager, or in the Low-Level I/O module if you use the default Stream Manager's implementation.
1682  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
1683  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
1684  /// of the UnloadBank() function.
1685  /// \sa
1686  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1687  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
1688  /// - <tt>AK::SoundEngine::GetIDFromString</tt>
1689  /// - <tt>AK::MemoryMgr::CreatePool()</tt>
1690  /// - \ref soundengine_banks
1691  /// - \ref integrating_elements_plugins
1692  /// - \ref streamingdevicemanager
1693  /// - \ref streamingmanager_lowlevel
1694  /// - \ref sdk_bank_training
1695  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
1696  const char* in_pszString, ///< Name of the bank to load
1697  AkMemPoolId in_memPoolId, ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
1698  AkBankID & out_bankID ///< Returned bank ID
1699  );
1700 
1701  /// Loads a bank synchronously (by ID).\n
1702  /// \aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
1703  /// The bank ID is passed to the Stream Manager.
1704  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
1705  /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
1706  /// A bank load request will be posted, and consumed by the Bank Manager thread.
1707  /// The function returns when the request has been completely processed.
1708  /// \return
1709  /// - AK_Success: Load or unload successful.
1710  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
1711  /// - AK_BankReadError: I/O error.
1712  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
1713  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
1714  /// - AK_InvalidFile: File specified could not be opened.
1715  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
1716  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
1717  /// \remarks
1718  /// - The initialization bank must be loaded first.
1719  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
1720  /// initialization bank. If you need to load SoundBanks from a different project, you
1721  /// must first unload ALL banks, including the initialization bank, then load the
1722  /// initialization bank from the other project, and finally load banks from that project.
1723  /// - Codecs and plug-ins must be registered before loading banks that use them.
1724  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1725  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1726  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1727  /// posting the event will fail.
1728  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
1729  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
1730  /// of the UnloadBank function.
1731  /// \sa
1732  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1733  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
1734  /// - <tt>AK::MemoryMgr::CreatePool()</tt>
1735  /// - \ref soundengine_banks
1736  /// - \ref integrating_elements_plugins
1737  /// - \ref sdk_bank_training
1738  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
1739  AkBankID in_bankID, ///< Bank ID of the bank to load
1740  AkMemPoolId in_memPoolId ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
1741  );
1742 
1743  /// Loads a bank synchronously (from in-memory data, in-place).\n
1744  ///
1745  /// IMPORTANT: Banks loaded from memory with in-place data MUST be unloaded using the UnloadBank function
1746  /// providing the same memory pointer. Make sure you are using the correct UnloadBank(...) overload
1747  ///
1748  /// Use this overload when you want to manage I/O on your side. Load the bank file
1749  /// in a buffer and pass its address to the sound engine.
1750  /// In-memory loading is in-place: *** the memory must be valid until the bank is unloaded. ***
1751  /// A bank load request will be posted, and consumed by the Bank Manager thread.
1752  /// The function returns when the request has been completely processed.
1753  /// \return
1754  /// The bank ID, which is stored in the first few bytes of the bank file. You may use this
1755  /// ID with UnloadBank().
1756  /// - AK_Success: Load or unload successful.
1757  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
1758  /// - AK_BankReadError: I/O error.
1759  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
1760  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
1761  /// - AK_InvalidFile: File specified could not be opened.
1762  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
1763  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
1764  /// \remarks
1765  /// - The initialization bank must be loaded first.
1766  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
1767  /// initialization bank. If you need to load SoundBanks from a different project, you
1768  /// must first unload ALL banks, including the initialization bank, then load the
1769  /// initialization bank from the other project, and finally load banks from that project.
1770  /// - Codecs and plug-ins must be registered before loading banks that use them.
1771  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1772  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1773  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1774  /// posting the event will fail.
1775  /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
1776  /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Physical memory allocator.
1777  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
1778  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
1779  /// of the UnloadBank function.
1780  /// - Avoid using this function for banks containing a lot of events or structure data.
1781  /// This data will be loaded in the Default Pool anyway thus duplicating memory (one copy in the Default Pool
1782  /// and one in the block you provided). For event/structure-only banks, prefer the other versions of LoadBank().
1783  /// \sa
1784  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1785  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
1786  /// - \ref soundengine_banks
1787  /// - \ref integrating_elements_plugins
1788  /// - \ref sdk_bank_training
1789  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
1790  const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is stored in sound engine, memory must remain valid)
1791  AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
1792  AkBankID & out_bankID ///< Returned bank ID
1793  );
1794 
1795  /// Loads a bank synchronously (from in-memory data, out-of-place).\n
1796  ///
1797  /// NOTE: Banks loaded from in-memory with out-of-place data must be unloaded using the standard UnloadBank function
1798  /// (with no memory pointer). Make sure you are using the correct UnloadBank(...) overload
1799  ///
1800  /// Use this overload when you want to manage I/O on your side. Load the bank file
1801  /// in a buffer and pass its address to the sound engine, the media section of the bank will be copied into the
1802  /// specified memory pool.
1803  /// In-memory loading is out-of-place: the buffer can be release as soon as the function returns. The advantage of using this
1804  /// over the in-place version is that there is no duplication of bank structures.
1805  /// A bank load request will be posted, and consumed by the Bank Manager thread.
1806  /// The function returns when the request has been completely processed.
1807  /// \return
1808  /// The bank ID, which is stored in the first few bytes of the bank file. You may use this
1809  /// ID with UnloadBank().
1810  /// - AK_Success: Load or unload successful.
1811  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
1812  /// - AK_BankReadError: I/O error.
1813  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
1814  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
1815  /// - AK_InvalidFile: File specified could not be opened.
1816  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
1817  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
1818  /// \remarks
1819  /// - The initialization bank must be loaded first.
1820  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
1821  /// initialization bank. If you need to load SoundBanks from a different project, you
1822  /// must first unload ALL banks, including the initialization bank, then load the
1823  /// initialization bank from the other project, and finally load banks from that project.
1824  /// - Codecs and plug-ins must be registered before loading banks that use them.
1825  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1826  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1827  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1828  /// posting the event will fail.
1829  /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
1830  /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Physical memory allocator.
1831  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
1832  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
1833  /// of the UnloadBank function.
1834  /// - Avoid using this function for banks containing a lot of events or structure data.
1835  /// This data will be loaded in the Default Pool anyway thus duplicating memory (one copy in the Default Pool
1836  /// and one in the block you provided). For event/structure-only banks, prefer the other versions of LoadBank().
1837  /// \sa
1838  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1839  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
1840  /// - \ref soundengine_banks
1841  /// - \ref integrating_elements_plugins
1842  /// - \ref sdk_bank_training
1843  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
1844  const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is not stored in sound engine, memory can be released after return)
1845  AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
1846  AkMemPoolId in_uPoolForBankMedia, ///< Memory pool to copy the media section of the bank to (the pool is created if AK_DEFAULT_POOL_ID is passed).
1847  AkBankID & out_bankID ///< Returned bank ID
1848  );
1849 
1850  /// Synchronously decodes Vorbis-encoded and Opus-encoded (Software version) media in a SoundBank. The file should already be read in memory before the decode operation. The out_pDecodedBankPtr can then be used with variants of LoadBank that load from in-memory data.
1851  /// \n
1852  /// CPU usage, RAM size, storage size and Internet bandwidth must be accounted for when developing a game, especially when it is aimed at mobile platforms. The DecodeBank function makes it possible to decode media at load time instead of decoding them every time they are played.
1853  AK_EXTERNAPIFUNC( AKRESULT, DecodeBank )(
1854  const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to decode (pointer is not stored in sound engine, memory can be released after return)
1855  AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to decode
1856  AkMemPoolId in_uPoolForDecodedBank, ///< Memory pool to allocate decoded bank into. Specify AK_INVALID_POOL_ID and out_pDecodedBankPtr=NULL to obtain decoded bank size without performing the decode operation. Pass AK_INVALID_POOL_ID and out_pDecodedBankPtr!=NULL to decode bank into specified pointer.
1857  void * & out_pDecodedBankPtr, ///< Decoded bank memory location.
1858  AkUInt32 & out_uDecodedBankSize ///< Decoded bank memory size.
1859  );
1860 
1861 #ifdef AK_SUPPORT_WCHAR
1862  /// Loads a bank asynchronously (by Unicode string).\n
1863  /// The bank name is passed to the Stream Manager.
1864  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
1865  /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
1866  /// A bank load request will be posted to the Bank Manager consumer thread.
1867  /// The function returns immediately.
1868  /// \return
1869  /// AK_Success if the scheduling was successful, AK_Fail otherwise.
1870  /// Use a callback to be notified when completed, and get the status of the request.
1871  /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
1872  /// You may use this ID with UnloadBank().
1873  /// \remarks
1874  /// - The initialization bank must be loaded first.
1875  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
1876  /// initialization bank. If you need to load SoundBanks from a different project, you
1877  /// must first unload ALL banks, including the initialization bank, then load the
1878  /// initialization bank from the other project, and finally load banks from that project.
1879  /// - Codecs and plug-ins must be registered before loading banks that use them.
1880  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1881  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1882  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1883  /// posting the event will fail.
1884  /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
1885  /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
1886  /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in
1887  /// your implementation of the Stream Manager (<tt>AK::IAkStreamMgr::CreateStd()</tt>), or in the Low-Level I/O module
1888  /// (<tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt>) if you use the default Stream Manager's implementation.
1889  /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt>
1890  // as AkFileSystemFlags::pCustomParam.
1891  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
1892  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
1893  /// of the UnloadBank function.
1894  /// \sa
1895  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1896  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
1897  /// - <tt>AK::MemoryMgr::CreatePool()</tt>
1898  /// - AkBankCallbackFunc
1899  /// - \ref soundengine_banks
1900  /// - \ref integrating_elements_plugins
1901  /// - \ref streamingdevicemanager
1902  /// - \ref streamingmanager_lowlevel
1903  /// - \ref sdk_bank_training
1904  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
1905  const wchar_t* in_pszString, ///< Name/path of the bank to load
1906  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
1907  void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function, and also to <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt> as AkFileSystemFlags::pCustomParam)
1908  AkMemPoolId in_memPoolId, ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
1909  AkBankID & out_bankID ///< Returned bank ID
1910  );
1911 #endif //AK_SUPPORT_WCHAR
1912 
1913  /// Loads a bank asynchronously.\n
1914  /// The bank name is passed to the Stream Manager.
1915  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
1916  /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
1917  /// A bank load request will be posted to the Bank Manager consumer thread.
1918  /// The function returns immediately.
1919  /// \return
1920  /// AK_Success if the scheduling was successful, AK_Fail otherwise.
1921  /// Use a callback to be notified when completed, and get the status of the request.
1922  /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
1923  /// You may use this ID with UnloadBank().
1924  /// \remarks
1925  /// - The initialization bank must be loaded first.
1926  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
1927  /// initialization bank. If you need to load SoundBanks from a different project, you
1928  /// must first unload ALL banks, including the initialization bank, then load the
1929  /// initialization bank from the other project, and finally load banks from that project.
1930  /// - Codecs and plug-ins must be registered before loading banks that use them.
1931  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1932  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1933  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1934  /// posting the Event will fail.
1935  /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
1936  /// Therefore, \c in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
1937  /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in
1938  /// your implementation of the Stream Manager (<tt>AK::IAkStreamMgr::CreateStd()</tt>), or in the Low-Level I/O module
1939  /// (<tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt>) if you use the default Stream Manager's implementation.
1940  /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt>
1941  // as <tt>AkFileSystemFlags::pCustomParam</tt>.
1942  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
1943  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
1944  /// of the \c UnloadBank function.
1945  /// \sa
1946  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1947  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
1948  /// - <tt>AK::MemoryMgr::CreatePool()</tt>
1949  /// - AkBankCallbackFunc
1950  /// - \ref soundengine_banks
1951  /// - \ref integrating_elements_plugins
1952  /// - \ref streamingdevicemanager
1953  /// - \ref streamingmanager_lowlevel
1954  /// - \ref sdk_bank_training
1955  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
1956  const char* in_pszString, ///< Name/path of the bank to load
1957  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
1958  void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function, and also to <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt> as AkFileSystemFlags::pCustomParam)
1959  AkMemPoolId in_memPoolId, ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
1960  AkBankID & out_bankID ///< Returned bank ID
1961  );
1962 
1963  /// Loads a bank asynchronously (by ID).\n
1964  /// \aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
1965  /// The bank ID is passed to the Stream Manager.
1966  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
1967  /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
1968  /// A bank load request will be posted to the Bank Manager consumer thread.
1969  /// The function returns immediately.
1970  /// \return
1971  /// AK_Success if the scheduling was successful, AK_Fail otherwise.
1972  /// Use a callback to be notified when completed, and get the status of the request.
1973  /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
1974  /// You may use this ID with \c UnloadBank().
1975  /// \remarks
1976  /// - The initialization bank must be loaded first.
1977  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
1978  /// initialization bank. If you need to load SoundBanks from a different project, you
1979  /// must first unload ALL banks, including the initialization bank, then load the
1980  /// initialization bank from the other project, and finally load banks from that project.
1981  /// - Codecs and plug-ins must be registered before loading banks that use them.
1982  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1983  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1984  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1985  /// posting the event will fail.
1986  /// - The file path should be resolved in your implementation of the Stream Manager, or in the Low-Level I/O module if
1987  /// you use the default Stream Manager's implementation. The ID overload of <tt>AK::IAkStreamMgr::CreateStd()</tt> and <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt> are called.
1988  /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt>
1989  // as AkFileSystemFlags::pCustomParam.
1990  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
1991  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
1992  /// of the UnloadBank function.
1993  /// \sa
1994  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
1995  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
1996  /// - <tt>AK::MemoryMgr::CreatePool()</tt>
1997  /// - AkBankCallbackFunc
1998  /// - \ref soundengine_banks
1999  /// - \ref integrating_elements_plugins
2000  /// - \ref sdk_bank_training
2001  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
2002  AkBankID in_bankID, ///< Bank ID of the bank to load
2003  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2004  void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function, and also to <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt> as AkFileSystemFlags::pCustomParam)
2005  AkMemPoolId in_memPoolId ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
2006  );
2007 
2008  /// Loads a bank asynchronously (from in-memory data, in-place).\n
2009  ///
2010  /// IMPORTANT: Banks loaded from memory with in-place data MUST be unloaded using the UnloadBank function
2011  /// providing the same memory pointer. Make sure you are using the correct UnloadBank(...) overload
2012  ///
2013  /// Use this overload when you want to manage I/O on your side. Load the bank file
2014  /// in a buffer and pass its address to the sound engine.
2015  /// In-memory loading is in-place: *** the memory must be valid until the bank is unloaded. ***
2016  /// A bank load request will be posted to the Bank Manager consumer thread.
2017  /// The function returns immediately.
2018  /// \return
2019  /// AK_Success if the scheduling was successful, AK_Fail otherwise, or AK_InvalidParameter if memory alignment is not correct.
2020  /// Use a callback to be notified when completed, and get the status of the request.
2021  /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
2022  /// You may use this ID with UnloadBank().
2023  /// \remarks
2024  /// - The initialization bank must be loaded first.
2025  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
2026  /// initialization bank. If you need to load SoundBanks from a different project, you
2027  /// must first unload ALL banks, including the initialization bank, then load the
2028  /// initialization bank from the other project, and finally load banks from that project.
2029  /// - Codecs and plug-ins must be registered before loading banks that use them.
2030  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
2031  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
2032  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
2033  /// posting the event will fail.
2034  /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
2035  /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Physical memory allocator.
2036  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
2037  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
2038  /// of the UnloadBank function.
2039  /// \sa
2040  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
2041  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2042  /// - AkBankCallbackFunc
2043  /// - \ref soundengine_banks
2044  /// - \ref integrating_elements_plugins
2045  /// - \ref sdk_bank_training
2046  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
2047  const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is stored in sound engine, memory must remain valid)
2048  AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
2049  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2050  void * in_pCookie, ///< Callback cookie
2051  AkBankID & out_bankID ///< Returned bank ID
2052  );
2053 
2054  /// Loads a bank asynchronously (from in-memory data, out-of-place).\n
2055  ///
2056  /// NOTE: Banks loaded from in-memory with out-of-place data must be unloaded using the standard UnloadBank function
2057  /// (with no memory pointer). Make sure you are using the correct UnloadBank(...) overload
2058  ///
2059  /// Use this overload when you want to manage I/O on your side. Load the bank file
2060  /// in a buffer and pass its address to the sound engine, the media section of the bank will be copied into the
2061  /// specified memory pool.
2062  /// In-memory loading is out-of-place: the buffer can be released after the callback function is called. The advantage of using this
2063  /// over the in-place version is that there is no duplication of bank structures.
2064  /// A bank load request will be posted to the Bank Manager consumer thread.
2065  /// The function returns immediately.
2066  /// \return
2067  /// AK_Success if the scheduling was successful, AK_Fail otherwise, or AK_InvalidParameter if memory alignment is not correct.
2068  /// Use a callback to be notified when completed, and get the status of the request.
2069  /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
2070  /// You may use this ID with UnloadBank().
2071  /// \remarks
2072  /// - The initialization bank must be loaded first.
2073  /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
2074  /// initialization bank. If you need to load SoundBanks from a different project, you
2075  /// must first unload ALL banks, including the initialization bank, then load the
2076  /// initialization bank from the other project, and finally load banks from that project.
2077  /// - Codecs and plug-ins must be registered before loading banks that use them.
2078  /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
2079  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
2080  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
2081  /// posting the event will fail.
2082  /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
2083  /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Physical memory allocator.
2084  /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
2085  /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
2086  /// of the UnloadBank function.
2087  /// \sa
2088  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
2089  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2090  /// - AkBankCallbackFunc
2091  /// - \ref soundengine_banks
2092  /// - \ref integrating_elements_plugins
2093  /// - \ref sdk_bank_training
2094  AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
2095  const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is not stored in sound engine, memory can be released after callback)
2096  AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
2097  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2098  void * in_pCookie, ///< Callback cookie
2099  AkMemPoolId in_uPoolForBankMedia, ///< Memory pool to copy the media section of the bank to (the pool is created if AK_DEFAULT_POOL_ID is passed).
2100  AkBankID & out_bankID ///< Returned bank ID
2101  );
2102 
2103 #ifdef AK_SUPPORT_WCHAR
2104  /// Unloads a bank synchronously (by Unicode string).\n
2105  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
2106  /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
2107  /// \remarks
2108  /// - If you provided a pool memory ID when loading this bank, it is returned as well.
2109  /// Otherwise, the function returns AK_DEFAULT_POOL_ID.
2110  /// - The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID,
2111  /// then it calls the synchronous version of UnloadBank() by ID.
2112  /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
2113  /// not the name of the file (if you changed it), nor the full path of the file.
2114  /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
2115  /// This means that streamed sounds or generated sounds will not be stopped.
2116  /// \sa
2117  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2118  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2119  /// - \ref soundengine_banks
2120  AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
2121  const wchar_t* in_pszString, ///< Name of the bank to unload
2122  const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
2123  AkMemPoolId * out_pMemPoolId = NULL ///< Returned memory pool ID used with LoadBank() (can pass NULL)
2124  );
2125 #endif //AK_SUPPORT_WCHAR
2126 
2127  /// Unloads a bank synchronously.\n
2128  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
2129  /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
2130  /// \remarks
2131  /// - If you provided a pool memory ID when loading this bank, it is returned as well.
2132  /// Otherwise, the function returns AK_DEFAULT_POOL_ID.
2133  /// - The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID,
2134  /// then it calls the synchronous version of UnloadBank() by ID.
2135  /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
2136  /// not the name of the file (if you changed it), nor the full path of the file.
2137  /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
2138  /// This means that streamed sounds or generated sounds will not be stopped.
2139  /// \sa
2140  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2141  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2142  /// - \ref soundengine_banks
2143  AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
2144  const char* in_pszString, ///< Name of the bank to unload
2145  const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
2146  AkMemPoolId * out_pMemPoolId = NULL ///< Returned memory pool ID used with LoadBank() (can pass NULL)
2147  );
2148 
2149  /// Unloads a bank synchronously (by ID and memory pointer).\n
2150  /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
2151  /// \remarks
2152  /// If you provided a pool memory ID when loading this bank, it is returned as well.
2153  /// Otherwise, the function returns AK_DEFAULT_POOL_ID.
2154  /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
2155  /// This means that streamed sounds or generated sounds will not be stopped.
2156  /// \sa
2157  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2158  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2159  /// - \ref soundengine_banks
2160  AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
2161  AkBankID in_bankID, ///< ID of the bank to unload
2162  const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
2163  AkMemPoolId * out_pMemPoolId = NULL ///< Returned memory pool ID used with LoadBank() (can pass NULL)
2164  );
2165 
2166 #ifdef AK_SUPPORT_WCHAR
2167  /// Unloads a bank asynchronously (by Unicode string).\n
2168  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
2169  /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
2170  /// \remarks
2171  /// The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID,
2172  /// then it calls the synchronous version of UnloadBank() by ID.
2173  /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
2174  /// not the name of the file (if you changed it), nor the full path of the file.
2175  /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
2176  /// This means that streamed sounds or generated sounds will not be stopped.
2177  /// \sa
2178  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2179  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2180  /// - AkBankCallbackFunc
2181  /// - \ref soundengine_banks
2182  AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
2183  const wchar_t* in_pszString, ///< Name of the bank to unload
2184  const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
2185  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2186  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2187  );
2188 #endif //AK_SUPPORT_WCHAR
2189 
2190  /// Unloads a bank asynchronously.\n
2191  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
2192  /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
2193  /// \remarks
2194  /// The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID,
2195  /// then it calls the synchronous version of UnloadBank() by ID.
2196  /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
2197  /// not the name of the file (if you changed it), nor the full path of the file.
2198  /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
2199  /// This means that streamed sounds or generated sounds will not be stopped.
2200  /// \sa
2201  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2202  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2203  /// - AkBankCallbackFunc
2204  /// - \ref soundengine_banks
2205  AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
2206  const char* in_pszString, ///< Name of the bank to unload
2207  const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
2208  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2209  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2210  );
2211 
2212  /// Unloads a bank asynchronously (by ID and memory pointer).\n
2213  /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
2214  /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
2215  /// \remarks
2216  /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
2217  /// This means that streamed sounds or generated sounds will not be stopped.
2218  /// \sa
2219  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2220  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2221  /// - AkBankCallbackFunc
2222  /// - \ref soundengine_banks
2223  AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
2224  AkBankID in_bankID, ///< ID of the bank to unload
2225  const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
2226  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2227  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2228  );
2229 
2230  /// Cancels all Event callbacks associated with a specific callback cookie specified while loading Banks of preparing Events.\n
2231  /// \sa
2232  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2233  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2234  /// - <tt>AK::SoundEngine::UnloadBank()</tt>
2235  /// - <tt>AK::SoundEngine::ClearBanks()</tt>
2236  /// - AkBankCallbackFunc
2237  AK_EXTERNAPIFUNC( void, CancelBankCallbackCookie )(
2238  void * in_pCookie ///< Callback cookie to be canceled
2239  );
2240 
2241  /// Preparation type.
2242  /// \sa
2243  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2244  /// - <tt>AK::SoundEngine::PrepareGameSyncs()</tt>
2245  /// - <tt>AK::SoundEngine::PrepareBank()</tt>
2247  {
2248  Preparation_Load, ///< \c PrepareEvent() will load required information to play the specified event.
2249  Preparation_Unload, ///< \c PrepareEvent() will unload required information to play the specified event.
2250  Preparation_LoadAndDecode ///< Vorbis media is decoded when loading, and an uncompressed PCM version is used for playback.
2251  };
2252 
2253  /// Parameter to be passed to <tt>AK::SoundEngine::PrepareBank()</tt>.
2254  /// Use AkBankContent_All to load both the media and structural content from the bank.
2255  /// Use AkBankContent_StructureOnly to load only the structural content, including events, from the bank and then later use the PrepareEvent() functions to load media on demand from loose files on the disk.
2256  /// \sa
2257  /// - <tt>AK::SoundEngine::PrepareBank()</tt>
2258  /// - \ref soundengine_banks_preparingbanks
2260  {
2261  AkBankContent_StructureOnly, ///< Use AkBankContent_StructureOnly to load only the structural content, including Events, and then later use the PrepareEvent() functions to load media on demand from loose files on the disk.
2262  AkBankContent_All ///< Use AkBankContent_All to load both the media and structural content.
2263  };
2264 
2265 #ifdef AK_SUPPORT_WCHAR
2266  /// This function will load the Events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, PrepareBank() will load the media content from
2267  /// the bank; but, as opposed to LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using PrepareBank(), alone or in combination with PrepareEvent(),
2268  /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
2269  /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
2270  /// allowing using PrepareEvent() to load media on demand.
2271  /// \sa
2272  /// - \ref soundengine_banks_preparingbanks
2273  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2274  /// - <tt>AK::SoundEngine::PreparationType</tt>
2275  /// \remarks
2276  /// PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. PrepareEvent(), however, is unable to
2277  /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
2278  /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses LoadBank() to load the bank in entirety.
2279  AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
2280  AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2281  const wchar_t* in_pszString, ///< Name of the bank to Prepare/Unprepare.
2282  AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All ///< Structures only (including events) or all content.
2283  );
2284 #endif //AK_SUPPORT_WCHAR
2285 
2286  /// This function will load the Events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, PrepareBank() will load the media content from
2287  /// the bank; but, as opposed to LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using PrepareBank(), alone or in combination with PrepareEvent(),
2288  /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
2289  /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
2290  /// allowing using PrepareEvent() to load media on demand.
2291  /// \sa
2292  /// - \ref soundengine_banks_preparingbanks
2293  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2294  /// - <tt>AK::SoundEngine::PreparationType</tt>
2295  /// \remarks
2296  /// \c PrepareBank(), when called with the flag \c AkBankContent_StructureOnly, requires additional calls to \c PrepareEvent() to load the media for each event. \c PrepareEvent(), however, is unable to
2297  /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
2298  /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses \c LoadBank() to load the bank in entirety.
2299  AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
2300  AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2301  const char* in_pszString, ///< Name of the bank to Prepare/Unprepare.
2302  AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All ///< Structures only (including events) or all content.
2303  );
2304 
2305  /// \n\aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
2306  /// This function will load the events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, PrepareBank() will load the media content from
2307  /// the bank, but as opposed to LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using PrepareBank(), alone or in combination with PrepareEvent(),
2308  /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
2309  /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
2310  /// allowing using PrepareEvent() to load media on demand.
2311  /// \sa
2312  /// - \ref soundengine_banks_preparingbanks
2313  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2314  /// - <tt>AK::SoundEngine::PreparationType</tt>
2315  /// \remarks
2316  /// \c PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. PrepareEvent(), however, is unable to
2317  /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
2318  /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses LoadBank() to load the bank in entirety.
2319  AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
2320  AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2321  AkBankID in_bankID, ///< ID of the bank to Prepare/Unprepare.
2322  AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All ///< Structures only (including events) or all content.
2323  );
2324 
2325 #ifdef AK_SUPPORT_WCHAR
2326  /// This function will load the Events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, PrepareBank() will load the media content from
2327  /// the bank, but as opposed to LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using PrepareBank(), alone or in combination with PrepareEvent(),
2328  /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
2329  /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
2330  /// allowing using PrepareEvent() to load media on demand.
2331  /// \sa
2332  /// - \ref soundengine_banks_preparingbanks
2333  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2334  /// - <tt>AK::SoundEngine::PreparationType</tt>
2335  /// \remarks
2336  /// PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. PrepareEvent(), however, is unable to
2337  /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
2338  /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses LoadBank() to load the bank in entirety.
2339  AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
2340  AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2341  const wchar_t* in_pszString, ///< Name of the bank to Prepare/Unprepare.
2342  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2343  void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
2344  AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All ///< Structures only (including events) or all content.
2345  );
2346 #endif //AK_SUPPORT_WCHAR
2347 
2348  /// This function will load the events, structural content, and optionally, the media content from the SoundBank. If the flag \c AkBankContent_All is specified, \c PrepareBank() will load the media content from
2349  /// the bank, but as opposed to \c LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using \c PrepareBank(), alone or in combination with PrepareEvent(),
2350  /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
2351  /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
2352  /// allowing using PrepareEvent() to load media on demand.
2353  /// \sa
2354  /// - \ref soundengine_banks_preparingbanks
2355  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2356  /// - <tt>AK::SoundEngine::PreparationType()</tt>
2357  /// \remarks
2358  /// PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. PrepareEvent(), however, is unable to
2359  /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
2360  /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses LoadBank() to load the bank in entirety.
2361  AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
2362  AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2363  const char* in_pszString, ///< Name of the bank to Prepare/Unprepare.
2364  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2365  void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
2366  AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All ///< Structures only (including events) or all content.
2367  );
2368 
2369  /// \n\aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
2370  /// This function will load the events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, \c PrepareBank() will load the media content from
2371  /// the bank, but as opposed to \c LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using \c PrepareBank(), alone or in combination with \c PrepareEvent(),
2372  /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
2373  /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
2374  /// allowing using PrepareEvent() to load media on demand.
2375  /// \sa
2376  /// - \ref soundengine_banks_preparingbanks
2377  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2378  /// - <tt>AK::SoundEngine::PreparationType()</tt>
2379  /// \remarks
2380  /// \c PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. \c PrepareEvent(), however, is unable to
2381  /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
2382  /// for example, a game may have a tool mode that uses \c PrepareEvent() to load loose files on-demand and, also, a game mode that uses \c LoadBank() to load the bank in entirety.
2383  AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
2384  AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2385  AkBankID in_bankID, ///< ID of the bank to Prepare/Unprepare.
2386  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2387  void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
2388  AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All ///< Structures only (including events) or all content.
2389  );
2390 
2391  /// Clear all previously prepared events.\n
2392  /// \return
2393  /// - AK_Success if successful.
2394  /// - AK_Fail if the sound engine was not correctly initialized or if there is not enough memory to handle the command.
2395  /// \remarks
2396  /// The function \c ClearBanks() also clears all prepared events.
2397  /// \sa
2398  /// - \c <tt>AK::SoundEngine::PrepareEvent()</tt>
2399  /// - \c <tt>AK::SoundEngine::ClearBanks()</tt>
2400  AK_EXTERNAPIFUNC( AKRESULT, ClearPreparedEvents )();
2401 
2402 #ifdef AK_SUPPORT_WCHAR
2403  /// Prepares or unprepares Events synchronously (by Unicode string).\n
2404  /// The Events are identified by strings, and converted to IDs internally
2405  /// (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2406  /// Before invoking \c PrepareEvent(), use \c LoadBank() to explicitly load the SoundBank(s)
2407  /// that contain the Events and structures. When a request is posted to the
2408  /// Bank Manager consumer thread, it will resolve all dependencies needed to
2409  /// successfully post the specified Events and load the required loose media files.
2410  /// \aknote Before version 2015.1, the required media files could be included
2411  /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
2412  /// however,\c PrepareEvent() now only looks for loose media files.
2413  /// \endaknote
2414  /// The function returns when the request is completely processed.
2415  /// \return
2416  /// - AK_Success: Prepare/un-prepare successful.
2417  /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
2418  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
2419  /// - AK_BankReadError: I/O error.
2420  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
2421  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
2422  /// - AK_InvalidFile: File specified could not be opened.
2423  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
2424  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
2425  /// \remarks
2426  /// Whenever at least one event fails to be resolved, the actions performed for all
2427  /// other events are cancelled.
2428  /// \sa
2429  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2430  /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
2431  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2432  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2433  /// - \ref soundengine_banks
2434  /// - \ref sdk_bank_training
2435  AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
2436  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2437  const wchar_t** in_ppszString, ///< Array of event names
2438  AkUInt32 in_uNumEvent ///< Number of events in the array
2439  );
2440 #endif //AK_SUPPORT_WCHAR
2441 
2442  /// Prepares or unprepares events synchronously.\n
2443  /// The Events are identified by strings and converted to IDs internally
2444  /// (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2445  /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
2446  /// that contain the Events and structures. When a request is posted to the
2447  /// Bank Manager consumer thread, it will resolve all dependencies needed to
2448  /// successfully post the specified Events and load the required loose media files.
2449  /// \aknote Before version 2015.1, the required media files could be included
2450  /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
2451  /// however, PrepareEvent() now only looks for loose media files.
2452  /// \endaknote
2453  /// The function returns when the request is completely processed.
2454  /// \return
2455  /// - AK_Success: Prepare/un-prepare successful.
2456  /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
2457  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
2458  /// - AK_BankReadError: I/O error.
2459  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
2460  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
2461  /// - AK_InvalidFile: File specified could not be opened.
2462  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
2463  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
2464  /// \remarks
2465  /// Whenever at least one event fails to be resolved, the actions performed for all
2466  /// other events are cancelled.
2467  /// \sa
2468  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2469  /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
2470  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2471  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2472  /// - \ref soundengine_banks
2473  /// - \ref sdk_bank_training
2474  AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
2475  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2476  const char** in_ppszString, ///< Array of event names
2477  AkUInt32 in_uNumEvent ///< Number of events in the array
2478  );
2479 
2480  /// Prepares or unprepares events synchronously (by ID).
2481  /// The Events are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2482  /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
2483  /// that contain the Events and structures. When a request is posted to the
2484  /// Bank Manager consumer thread, it will resolve all dependencies needed to
2485  /// successfully post the specified Events and load the required loose media files.
2486  /// \aknote Before version 2015.1, the required media files could be included
2487  /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
2488  /// however, PrepareEvent() now only looks for loose media files.
2489  /// \endaknote
2490  /// The function returns when the request is completely processed.
2491  /// \return
2492  /// - AK_Success: Prepare/un-prepare successful.
2493  /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
2494  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
2495  /// - AK_BankReadError: I/O error.
2496  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
2497  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
2498  /// - AK_InvalidFile: File specified could not be opened.
2499  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
2500  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
2501  /// \remarks
2502  /// Whenever at least one event fails to be resolved, the actions performed for all
2503  /// other events are cancelled.
2504  /// \sa
2505  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2506  /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
2507  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2508  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2509  /// - \ref soundengine_banks
2510  /// - \ref sdk_bank_training
2511  AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
2512  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2513  AkUniqueID* in_pEventID, ///< Array of event IDs
2514  AkUInt32 in_uNumEvent ///< Number of event IDs in the array
2515  );
2516 
2517 #ifdef AK_SUPPORT_WCHAR
2518  /// Prepares or unprepares an event asynchronously (by Unicode string).
2519  /// The Events are identified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2520  /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
2521  /// that contain the Events and structures. When a request is posted to the
2522  /// Bank Manager consumer thread, it will resolve all dependencies needed to
2523  /// successfully post the specified Events and load the required loose media files.
2524  /// \aknote Before version 2015.1, the required media files could be included
2525  /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
2526  /// however, \c PrepareEvent() now only looks for loose media files.
2527  /// \endaknote
2528  /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
2529  /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
2530  /// \remarks
2531  /// Whenever at least one Event fails to be resolved, the actions performed for all
2532  /// other Events are cancelled.
2533  /// \sa
2534  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2535  /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
2536  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2537  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2538  /// - AkBankCallbackFunc
2539  /// - \ref soundengine_banks
2540  /// - \ref sdk_bank_training
2541  AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
2542  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2543  const wchar_t** in_ppszString, ///< Array of event names
2544  AkUInt32 in_uNumEvent, ///< Number of events in the array
2545  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2546  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2547  );
2548 #endif //AK_SUPPORT_WCHAR
2549 
2550  /// Prepares or unprepares an event asynchronously.
2551  /// The Events are identified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2552  /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
2553  /// that contain the Events and structures. When a request is posted to the
2554  /// Bank Manager consumer thread, it will resolve all dependencies needed to
2555  /// successfully post the specified Events and load the required loose media files.
2556  /// \aknote Before version 2015.1, the required media files could be included
2557  /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
2558  /// however, PrepareEvent() now only looks for loose media files.
2559  /// \endaknote
2560  /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
2561  /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
2562  /// \remarks
2563  /// Whenever at least one event fails to be resolved, the actions performed for all
2564  /// other events are cancelled.
2565  /// \sa
2566  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2567  /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
2568  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2569  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2570  /// - AkBankCallbackFunc
2571  /// - \ref soundengine_banks
2572  /// - \ref sdk_bank_training
2573  AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
2574  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2575  const char** in_ppszString, ///< Array of event names
2576  AkUInt32 in_uNumEvent, ///< Number of events in the array
2577  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2578  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2579  );
2580 
2581  /// Prepares or unprepares events asynchronously (by ID).\n
2582  /// The Events are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2583  /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
2584  /// that contain the Events and structures. When a request is posted to the
2585  /// Bank Manager consumer thread, it will resolve all dependencies needed to
2586  /// successfully post the specified Events and load the required loose media files.
2587  /// \aknote Before version 2015.1, the required media files could be included
2588  /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
2589  /// however, PrepareEvent() now only looks for loose media files.
2590  /// \endaknote
2591  /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
2592  /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
2593  /// \remarks
2594  /// Whenever at least one event fails to be resolved, the actions performed for all
2595  /// other events are cancelled.
2596  /// \sa
2597  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2598  /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
2599  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2600  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2601  /// - AkBankCallbackFunc
2602  /// - \ref soundengine_banks
2603  /// - \ref sdk_bank_training
2604  AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
2605  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2606  AkUniqueID* in_pEventID, ///< Array of event IDs
2607  AkUInt32 in_uNumEvent, ///< Number of event IDs in the array
2608  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2609  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2610  );
2611 
2612  /// Indicates the location of a specific Media ID in memory
2613  /// The sources are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2614  /// \return AK_Success if operation was successful, AK_InvalidParameter if in_pSourceSettings is invalid, and AK_Fail otherwise.
2615  AK_EXTERNAPIFUNC( AKRESULT, SetMedia )(
2616  AkSourceSettings * in_pSourceSettings, ///< Array of Source Settings
2617  AkUInt32 in_uNumSourceSettings ///< Number of Source Settings in the array
2618  );
2619 
2620  /// Removes the specified source from the list of loaded media.
2621  /// The sources are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2622  /// \return AK_Success if operation was successful, AK_InvalidParameter if in_pSourceSettings is invalid, and AK_Fail otherwise.
2623  AK_EXTERNAPIFUNC( AKRESULT, UnsetMedia )(
2624  AkSourceSettings * in_pSourceSettings, ///< Array of Source Settings
2625  AkUInt32 in_uNumSourceSettings ///< Number of Source Settings in the array
2626  );
2627 
2628 #ifdef AK_SUPPORT_WCHAR
2629  /// Prepares or unprepares game syncs synchronously (by Unicode string).\n
2630  /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2631  /// The game syncs definitions must already exist in the sound engine by having
2632  /// explicitly loaded the bank(s) that contain them (with LoadBank()).
2633  /// A request is posted to the Bank Manager consumer thread. It will resolve all
2634  /// dependencies needed to successfully set this game sync group to one of the
2635  /// game sync values specified, and load the required banks, if applicable.
2636  /// The function returns when the request has been completely processed.
2637  /// \return
2638  /// - AK_Success: Prepare/un-prepare successful.
2639  /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
2640  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
2641  /// - AK_BankReadError: I/O error.
2642  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
2643  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
2644  /// - AK_InvalidFile: File specified could not be opened.
2645  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
2646  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
2647  /// \remarks
2648  /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation
2649  /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
2650  /// so you never need to call this function.
2651  /// \sa
2652  /// - \c <tt>AK::SoundEngine::GetIDFromString()</tt>
2653  /// - \c <tt>AK::SoundEngine::PrepareEvent()</tt>
2654  /// - \c <tt>AK::SoundEngine::LoadBank()</tt>
2655  /// - \c AkInitSettings
2656  /// - \ref soundengine_banks
2657  /// - \ref sdk_bank_training
2658  AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
2659  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2660  AkGroupType in_eGameSyncType, ///< The type of game sync.
2661  const wchar_t* in_pszGroupName, ///< The State Group Name or the Switch Group Name.
2662  const wchar_t** in_ppszGameSyncName, ///< The specific ID of the state to either support or not support.
2663  AkUInt32 in_uNumGameSyncs ///< The number of game sync in the string array.
2664  );
2665 #endif //AK_SUPPORT_WCHAR
2666 
2667  /// Prepares or unprepares game syncs synchronously.\n
2668  /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2669  /// The game syncs definitions must already exist in the sound engine by having
2670  /// explicitly loaded the bank(s) that contain them (with LoadBank()).
2671  /// A request is posted to the Bank Manager consumer thread. It will resolve all
2672  /// dependencies needed to successfully set this game sync group to one of the
2673  /// game sync values specified, and load the required banks, if applicable.
2674  /// The function returns when the request has been completely processed.
2675  /// \return
2676  /// - AK_Success: Prepare/un-prepare successful.
2677  /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
2678  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
2679  /// - AK_BankReadError: I/O error.
2680  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
2681  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
2682  /// - AK_InvalidFile: File specified could not be opened.
2683  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
2684  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
2685  /// \remarks
2686  /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation
2687  /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
2688  /// so you never need to call this function.
2689  /// \sa
2690  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2691  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2692  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2693  /// - AkInitSettings
2694  /// - \ref soundengine_banks
2695  /// - \ref sdk_bank_training
2696  AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
2697  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2698  AkGroupType in_eGameSyncType, ///< The type of game sync.
2699  const char* in_pszGroupName, ///< The State Group Name or the Switch Group Name.
2700  const char** in_ppszGameSyncName, ///< The specific ID of the state to either support or not support.
2701  AkUInt32 in_uNumGameSyncs ///< The number of game sync in the string array.
2702  );
2703 
2704  /// Prepares or unprepares game syncs synchronously (by ID).\n
2705  /// The group and game syncs are specified by ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2706  /// The game syncs definitions must already exist in the sound engine by having
2707  /// explicitly loaded the bank(s) that contain them (with LoadBank()).
2708  /// A request is posted to the Bank Manager consumer thread. It will resolve all
2709  /// dependencies needed to successfully set this game sync group to one of the
2710  /// game sync values specified, and load the required banks, if applicable.
2711  /// The function returns when the request has been completely processed.
2712  /// \return
2713  /// - AK_Success: Prepare/un-prepare successful.
2714  /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
2715  /// - AK_InsufficientMemory: Insufficient memory to store bank data.
2716  /// - AK_BankReadError: I/O error.
2717  /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
2718  /// you used to generate the SoundBanks matches that of the SDK you are currently using.
2719  /// - AK_InvalidFile: File specified could not be opened.
2720  /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.
2721  /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
2722  /// \remarks
2723  /// You need to call \c PrepareGameSyncs() if the sound engine was initialized with \c AkInitSettings::bEnableGameSyncPreparation
2724  /// set to \c true. When set to \c false, the sound engine automatically prepares all game syncs when preparing Events,
2725  /// so you never need to call this function.
2726  /// \sa
2727  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2728  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2729  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2730  /// - AkInitSettings
2731  /// - \ref soundengine_banks
2732  /// - \ref sdk_bank_training
2733  AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
2734  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2735  AkGroupType in_eGameSyncType, ///< The type of game sync.
2736  AkUInt32 in_GroupID, ///< The State Group ID or the Switch Group ID.
2737  AkUInt32* in_paGameSyncID, ///< Array of ID of the game syncs to either support or not support.
2738  AkUInt32 in_uNumGameSyncs ///< The number of game sync ID in the array.
2739  );
2740 
2741 #ifdef AK_SUPPORT_WCHAR
2742  /// Prepares or unprepares game syncs asynchronously (by Unicode string).\n
2743  /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2744  /// The game syncs definitions must already exist in the sound engine by having
2745  /// explicitly loaded the bank(s) that contain them (with <tt>LoadBank()</tt>).
2746  /// A request is posted to the Bank Manager consumer thread. It will resolve all
2747  /// dependencies needed to successfully set this game sync group to one of the
2748  /// game sync values specified, and load the required banks, if applicable.
2749  /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
2750  /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
2751  /// \remarks
2752  /// You need to call \c PrepareGameSyncs() if the sound engine was initialized with \c AkInitSettings::bEnableGameSyncPreparation
2753  /// set to \c true. When set to \c false, the sound engine automatically prepares all game syncs when preparing Events,
2754  /// so you never need to call this function.
2755  /// \sa
2756  /// - \c <tt>AK::SoundEngine::GetIDFromString()</tt>
2757  /// - \c <tt>AK::SoundEngine::PrepareEvent()</tt>
2758  /// - \c <tt>AK::SoundEngine::LoadBank()</tt>
2759  /// - \c AkInitSettings
2760  /// - \c AkBankCallbackFunc
2761  /// - \ref soundengine_banks
2762  /// - \ref sdk_bank_training
2763  AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
2764  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2765  AkGroupType in_eGameSyncType, ///< The type of game sync.
2766  const wchar_t* in_pszGroupName, ///< The State Group Name or the Switch Group Name.
2767  const wchar_t** in_ppszGameSyncName, ///< The specific ID of the state to either support or not support.
2768  AkUInt32 in_uNumGameSyncs, ///< The number of game sync in the string array.
2769  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2770  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2771  );
2772 #endif //AK_SUPPORT_WCHAR
2773 
2774  /// Prepares or unprepares game syncs asynchronously.\n
2775  /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2776  /// The game syncs definitions must already exist in the sound engine by having
2777  /// explicitly loaded the bank(s) that contain them (with LoadBank()).
2778  /// A request is posted to the Bank Manager consumer thread. It will resolve all
2779  /// dependencies needed to successfully set this game sync group to one of the
2780  /// game sync values specified, and load the required banks, if applicable.
2781  /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
2782  /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
2783  /// \remarks
2784  /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation
2785  /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
2786  /// so you never need to call this function.
2787  /// \sa
2788  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2789  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2790  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2791  /// - AkInitSettings
2792  /// - AkBankCallbackFunc
2793  /// - \ref soundengine_banks
2794  /// - \ref sdk_bank_training
2795  AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
2796  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2797  AkGroupType in_eGameSyncType, ///< The type of game sync.
2798  const char* in_pszGroupName, ///< The State Group Name or the Switch Group Name.
2799  const char** in_ppszGameSyncName, ///< The specific ID of the state to either support or not support.
2800  AkUInt32 in_uNumGameSyncs, ///< The number of game sync in the string array.
2801  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2802  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2803  );
2804 
2805  /// Prepares or un-prepare game syncs asynchronously (by ID).\n
2806  /// The group and game syncs are specified by ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
2807  /// The game syncs definitions must already exist in the sound engine by having
2808  /// explicitly loaded the bank(s) that contain them (with LoadBank()).
2809  /// A request is posted to the Bank Manager consumer thread. It will resolve all
2810  /// dependencies needed to successfully set this game sync group to one of the
2811  /// game sync values specified, and load the required banks, if applicable.
2812  /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
2813  /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
2814  /// \remarks
2815  /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation
2816  /// set to true. When set to false, the sound engine automatically prepares all Game Syncs when preparing Events,
2817  /// so you never need to call this function.
2818  /// \sa
2819  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2820  /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
2821  /// - <tt>AK::SoundEngine::LoadBank()</tt>
2822  /// - AkInitSettings
2823  /// - AkBankCallbackFunc
2824  /// - \ref soundengine_banks
2825  /// - \ref sdk_bank_training
2826  AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
2827  PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
2828  AkGroupType in_eGameSyncType, ///< The type of game sync.
2829  AkUInt32 in_GroupID, ///< The State Group ID or the Switch Group ID.
2830  AkUInt32* in_paGameSyncID, ///< Array of ID of the Game Syncs to either support or not support.
2831  AkUInt32 in_uNumGameSyncs, ///< The number of game sync ID in the array.
2832  AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
2833  void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
2834  );
2835 
2836  //@}
2837 
2838 
2839  ////////////////////////////////////////////////////////////////////////
2840  /// @name Listeners
2841  //@{
2842 
2843  /// Sets a game object's associated listeners.
2844  /// All listeners that have previously been added via AddListener or set via SetListeners will be removed and replaced with the listeners in the array in_pListenerGameObjs.
2845  /// Calling this function will override the default set of listeners and in_emitterGameObj will now reference its own, unique set of listeners.
2846  /// \return Always returns AK_Success
2847  /// \sa
2848  /// - <tt>AK::SoundEngine::AddListener</tt>
2849  /// - <tt>AK::SoundEngine::RemoveListener</tt>
2850  /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
2851  /// - \ref soundengine_listeners
2852  AK_EXTERNAPIFUNC( AKRESULT, SetListeners )(
2853  AkGameObjectID in_emitterGameObj, ///< Emitter game object. Must have been previously registered via RegisterGameObj.
2854  const AkGameObjectID* in_pListenerGameObjs, ///< Array of listener game object IDs that will be activated for in_emitterGameObj.
2855  AkUInt32 in_uNumListeners ///< Length of array
2856  );
2857 
2858  /// Add a single listener to a game object's set of associated listeners.
2859  /// Any listeners that have previously been added or set via AddListener or SetListeners will remain as listeners and in_listenerGameObj will be added as an additional listener.
2860  /// Calling this function will override the default set of listeners and in_emitterGameObj will now reference its own, unique set of listeners.
2861  /// \sa
2862  /// - <tt>AK::SoundEngine::SetListeners</tt>
2863  /// - <tt>AK::SoundEngine::RemoveListener</tt>
2864  /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
2865  /// - \ref soundengine_listeners
2866  AK_EXTERNAPIFUNC(AKRESULT, AddListener)(
2867  AkGameObjectID in_emitterGameObj, ///< Emitter game object. Must have been previously registered via RegisterGameObj.
2868  AkGameObjectID in_listenerGameObj ///< Listener game object IDs that will be activated for in_emitterGameObj.
2869  );
2870 
2871  /// Remove a single listener from a game object's set of active listeners.
2872  /// Calling this function will override the default set of listeners and in_emitterGameObj will now reference its own, unique set of listeners.
2873  /// \sa
2874  /// - <tt>AK::SoundEngine::SetListeners</tt>
2875  /// - <tt>AK::SoundEngine::AddListener</tt>
2876  /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
2877  /// - \ref soundengine_listeners
2878  AK_EXTERNAPIFUNC(AKRESULT, RemoveListener)(
2879  AkGameObjectID in_emitterGameObj, ///< Emitter game object.
2880  AkGameObjectID in_listenerGameObj ///< Listener game object IDs that will be deactivated for in_emitterGameObj. Game objects must have been previously registered.
2881  );
2882 
2883  /// Sets the default set of associated listeners for game objects that have not explicitly overridden their listener sets. Upon registration, all game objects reference the default listener set, until
2884  /// a call to AddListener, RemoveListener, SetListeners or SetGameObjectOutputBusVolume is made on that game object.
2885  /// All default listeners that have previously been added via AddDefaultListener or set via SetDefaultListeners will be removed and replaced with the listeners in the array in_pListenerGameObjs.
2886  /// \return Always returns AK_Success
2887  /// \sa
2888  /// - \ref soundengine_listeners
2889  AK_EXTERNAPIFUNC(AKRESULT, SetDefaultListeners)(
2890  const AkGameObjectID* in_pListenerObjs, ///< Array of listener game object IDs that will be activated for subsequent registrations. Game objects must have been previously registered.
2891  AkUInt32 in_uNumListeners ///< Length of array
2892  );
2893 
2894  /// Add a single listener to the default set of listeners. Upon registration, all game objects reference the default listener set, until
2895  /// a call to AddListener, RemoveListener, SetListeners or SetGameObjectOutputBusVolume is made on that game object.
2896  /// \sa
2897  /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
2898  /// - <tt>AK::SoundEngine::RemoveDefaultListener</tt>
2899  /// - \ref soundengine_listeners
2900  AK_EXTERNAPIFUNC(AKRESULT, AddDefaultListener)(
2901  AkGameObjectID in_listenerGameObj ///< Listener game object IDs that will be added to the default set of listeners.
2902  );
2903 
2904  /// Remove a single listener from the default set of listeners. Upon registration, all game objects reference the default listener set, until
2905  /// a call to AddListener, RemoveListener, SetListeners or SetGameObjectOutputBusVolume is made on that game object.
2906  /// \sa
2907  /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
2908  /// - <tt>AK::SoundEngine::AddDefaultListener</tt>
2909  /// - \ref soundengine_listeners
2910  AK_EXTERNAPIFUNC(AKRESULT, RemoveDefaultListener)(
2911  AkGameObjectID in_listenerGameObj ///< Listener game object IDs that will be removed from the default set of listeners.
2912  );
2913 
2914  /// Resets the listener associations to the default listener(s), as set by <tt>SetDefaultListeners</tt>. This will also reset per-listener gains that have been set using <tt>SetGameObjectOutputBusVolume</tt>.
2915  /// \return Always returns AK_Success
2916  /// \sa
2917  /// - <tt>AK::SoundEngine::SetListeners</tt>
2918  /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
2919  /// - <tt>AK::SoundEngine::SetGameObjectOutputBusVolume</tt>
2920  /// - \ref soundengine_listeners
2921  AK_EXTERNAPIFUNC(AKRESULT, ResetListenersToDefault)(
2922  AkGameObjectID in_emitterGameObj ///< Emitter game object.
2923  );
2924 
2925  /// Sets a listener's spatialization parameters. This lets you define listener-specific
2926  /// volume offsets for each audio channel.
2927  /// If \c in_bSpatialized is false, only \c in_pVolumeOffsets is used for this listener (3D positions
2928  /// have no effect on the speaker distribution). Otherwise, \c in_pVolumeOffsets is added to the speaker
2929  /// distribution computed for this listener.
2930  /// Use helper functions of \c AK::SpeakerVolumes to manipulate the vector of volume offsets in_pVolumeOffsets.
2931  ///
2932  /// \remarks
2933  /// - If a sound is mixed into a bus that has a different speaker configuration than in_channelConfig,
2934  /// standard up/downmix rules apply.
2935  /// - Sounds with 3D Spatialization set to None will not be affected by these parameters.
2936  /// \return
2937  /// \c AK_Success if message was successfully posted to sound engine queue
2938  /// \c AK_InvalidFloatValue if the value specified was NaN or Inf
2939  /// \c AK_InsufficientMemory if there wasn't enough memory in the message queue
2940  /// \sa
2941  /// - \ref soundengine_listeners_spatial
2942  AK_EXTERNAPIFUNC( AKRESULT, SetListenerSpatialization )(
2943  AkGameObjectID in_uListenerID, ///< Listener game object ID
2944  bool in_bSpatialized, ///< Spatialization toggle (True : enable spatialization, False : disable spatialization)
2945  AkChannelConfig in_channelConfig, ///< Channel configuration associated with volumes in_pVolumeOffsets. Ignored if in_pVolumeOffsets is NULL.
2946  AK::SpeakerVolumes::VectorPtr in_pVolumeOffsets = NULL ///< Per-speaker volume offset, in dB. See AkSpeakerVolumes.h for how to manipulate this vector.
2947  );
2948 
2949  //@}
2950 
2951 
2952  ////////////////////////////////////////////////////////////////////////
2953  /// @name Game Syncs
2954  //@{
2955 
2956  /// Sets the value of a real-time parameter control (by ID).
2957  /// With this function, you may set a game parameter value with global scope or with game object scope.
2958  /// Game object scope supersedes global scope. (Once a value is set for the game object scope, it will not be affected by changes to the global scope value.) Game parameter values set with a global scope are applied to all
2959  /// game objects that not yet registered, or already registered but not overridden with a value with game object scope.
2960  /// To set a game parameter value with global scope, pass \c AK_INVALID_GAME_OBJECT as the game object.
2961  /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
2962  /// value for \c in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
2963  /// according to the interpolation curve. If you call \c <tt><tt>SetRTPCValue()</tt></tt> with <tt>in_uValueChangeDuration = 0</tt> in the
2964  /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
2965  /// function at every game frame, you should not use \c in_uValueChangeDuration, as it would have no effect and it is less efficient.
2966  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
2967  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
2968  /// \return
2969  /// \c AK_Success if the value was successfully set
2970  /// \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
2971  /// \sa
2972  /// - \ref soundengine_rtpc
2973  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
2974  AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )(
2975  AkRtpcID in_rtpcID, ///< ID of the game parameter
2976  AkRtpcValue in_value, ///< Value to set
2977  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
2978  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
2979  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
2980  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
2981  );
2982 
2983 #ifdef AK_SUPPORT_WCHAR
2984  /// Sets the value of a real-time parameter control (by Unicode string name).
2985  /// With this function, you may set a game parameter value to global scope or to game object scope.
2986  /// Game object scope supersedes global scope. (Once a value is set for the game object scope, it will not be affected by changes to the global scope value.) Game parameter values set with global scope are applied to all
2987  /// game objects that not yet registered, or already registered but not overridden with a value with game object scope.
2988  /// To set a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
2989  /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
2990  /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
2991  /// according to the interpolation curve. If you call SetRTPCValue() with in_uValueChangeDuration = 0 in the
2992  /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
2993  /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
2994  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
2995  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
2996  /// \return
2997  /// \c AK_Success if the value was successfully set
2998  /// \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
2999  /// \c AK_IDNotFound if in_pszRtpcName is NULL.
3000  /// \aknote Strings are case-insensitive. \endaknote
3001  /// \sa
3002  /// - \ref soundengine_rtpc
3003  AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )(
3004  const wchar_t* in_pszRtpcName, ///< Name of the game parameter
3005  AkRtpcValue in_value, ///< Value to set
3006  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
3007  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
3008  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
3009  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
3010  );
3011 #endif //AK_SUPPORT_WCHAR
3012 
3013  /// Sets the value of a real-time parameter control.
3014  /// With this function, you may set a game parameter value with global scope or with game object scope.
3015  /// Game object scope supersedes global scope. (Once a value is set for the game object scope, it will not be affected by changes to the global scope value.) Game parameter values set with global scope are applied to all
3016  /// game objects that not yet registered, or already registered but not overridden with a value with game object scope.
3017  /// To set a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
3018  /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
3019  /// value for \c in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
3020  /// according to the interpolation curve. If you call SetRTPCValue() with in_uValueChangeDuration = 0 in the
3021  /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
3022  /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
3023  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
3024  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
3025  /// \return
3026  /// \c AK_Success if the value was successfully set
3027  /// \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
3028  /// \c AK_IDNotFound if in_pszRtpcName is NULL.
3029  /// \aknote Strings are case-insensitive. \endaknote
3030  /// \sa
3031  /// - \ref soundengine_rtpc
3032  AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )(
3033  const char* in_pszRtpcName, ///< Name of the game parameter
3034  AkRtpcValue in_value, ///< Value to set
3035  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
3036  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
3037  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
3038  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
3039  );
3040 
3041  /// Sets the value of a real-time parameter control (by ID).
3042  /// With this function, you may set a game parameter value on playing id scope.
3043  /// Playing id scope supersedes both game object scope and global scope.
3044  /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
3045  /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
3046  /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the
3047  /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
3048  /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
3049  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
3050  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
3051  /// \return
3052  /// \c AK_Success if the value was successfully set
3053  /// \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
3054  /// \sa
3055  /// - \ref soundengine_rtpc
3056  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3057  AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )(
3058  AkRtpcID in_rtpcID, ///< ID of the game parameter
3059  AkRtpcValue in_value, ///< Value to set
3060  AkPlayingID in_playingID, ///< Associated playing ID
3061  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
3062  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
3063  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when, for example, loading a level and you don't want the values to interpolate.
3064  );
3065 
3066 #ifdef AK_SUPPORT_WCHAR
3067  /// Sets the value of a real-time parameter control (by Unicode string name).
3068  /// With this function, you may set a game parameter value on playing ID scope.
3069  /// Playing id scope supersedes both game object scope and global scope.
3070  /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
3071  /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
3072  /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the
3073  /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
3074  /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
3075  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
3076  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
3077  /// \return
3078  /// \c AK_Success if the value was successfully set
3079  /// \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
3080  /// \c AK_IDNotFound if in_pszRtpcName is NULL.
3081  /// \sa
3082  /// - \ref soundengine_rtpc
3083  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3084  AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )(
3085  const wchar_t* in_pszRtpcName, ///< Name of the game parameter
3086  AkRtpcValue in_value, ///< Value to set
3087  AkPlayingID in_playingID, ///< Associated playing ID
3088  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
3089  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
3090  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when, for example, loading a level and you don't want the values to interpolate.
3091  );
3092 #endif //AK_SUPPORT_WCHAR
3093 
3094  /// Sets the value of a real-time parameter control (by string name).
3095  /// With this function, you may set a game parameter value on playing id scope.
3096  /// Playing id scope supersedes both game object scope and global scope.
3097  /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
3098  /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
3099  /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the
3100  /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
3101  /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
3102  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
3103  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
3104  /// \return
3105  /// \c AK_Success if the value was successfully set
3106  /// \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
3107  /// \c AK_IDNotFound if in_pszRtpcName is NULL.
3108  /// \sa
3109  /// - \ref soundengine_rtpc
3110  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3111  AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )(
3112  const char* in_pszRtpcName, ///< Name of the game parameter
3113  AkRtpcValue in_value, ///< Value to set
3114  AkPlayingID in_playingID, ///< Associated playing ID
3115  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
3116  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
3117  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
3118  );
3119 
3120  /// Resets the value of the game parameter to its default value, as specified in the Wwise project.
3121  /// With this function, you may reset a game parameter to its default value with global scope or with game object scope.
3122  /// Game object scope supersedes global scope. Game parameter values reset with global scope are applied to all
3123  /// game objects that were not overridden with a value with game object scope.
3124  /// To reset a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
3125  /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero
3126  /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
3127  /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the
3128  /// middle of an interpolation, the interpolation stops and the new value is set directly.
3129  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
3130  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
3131  /// \return
3132  /// \sa
3133  /// - \ref soundengine_rtpc
3134  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3135  /// - <tt>AK::SoundEngine::SetRTPCValue()</tt>
3136  AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
3137  AkRtpcID in_rtpcID, ///< ID of the game parameter
3138  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
3139  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards its default value
3140  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
3141  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
3142  );
3143 
3144 #ifdef AK_SUPPORT_WCHAR
3145  /// Resets the value of the game parameter to its default value, as specified in the Wwise project.
3146  /// With this function, you may reset a game parameter to its default value with global scope or with game object scope.
3147  /// Game object scope supersedes global scope. Game parameter values reset with global scope are applied to all
3148  /// game objects that were not overridden with a value with game object scope.
3149  /// To reset a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
3150  /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero
3151  /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
3152  /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the
3153  /// middle of an interpolation, the interpolation stops and the new value is set directly.
3154  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
3155  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
3156  /// \return
3157  /// - AK_Success if successful
3158  /// - AK_IDNotFound if in_pszParamName is NULL.
3159  /// \aknote Strings are case-insensitive. \endaknote
3160  /// \sa
3161  /// - \ref soundengine_rtpc
3162  /// - <tt>AK::SoundEngine::SetRTPCValue()</tt>
3163  AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
3164  const wchar_t* in_pszRtpcName, ///< Name of the game parameter
3165  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
3166  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards its default value
3167  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
3168  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
3169  );
3170 #endif //AK_SUPPORT_WCHAR
3171 
3172  /// Resets the value of the game parameter to its default value, as specified in the Wwise project.
3173  /// With this function, you may reset a game parameter to its default value with global scope or with game object scope.
3174  /// Game object scope supersedes global scope. Game parameter values reset with global scope are applied to all
3175  /// game objects that were not overridden with a value with game object scope.
3176  /// To reset a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
3177  /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero
3178  /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
3179  /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the
3180  /// middle of an interpolation, the interpolation stops and the new value is set directly.
3181  /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
3182  /// \ref soundengine_rtpc_effects for more details on RTPC scope.
3183  /// \return
3184  /// - AK_Success if successful
3185  /// - AK_IDNotFound if in_pszParamName is NULL.
3186  /// \aknote Strings are case-insensitive. \endaknote
3187  /// \sa
3188  /// - \ref soundengine_rtpc
3189  /// - <tt>AK::SoundEngine::SetRTPCValue()</tt>
3190  AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
3191  const char* in_pszRtpcName, ///< Name of the game parameter
3192  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
3193  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards its default value
3194  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
3195  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
3196  );
3197 
3198  /// Sets the State of a Switch Group (by IDs).
3199  /// \return Always returns AK_Success
3200  /// \sa
3201  /// - \ref soundengine_switch
3202  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3203  AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )(
3204  AkSwitchGroupID in_switchGroup, ///< ID of the Switch Group
3205  AkSwitchStateID in_switchState, ///< ID of the Switch
3206  AkGameObjectID in_gameObjectID ///< Associated game object ID
3207  );
3208 
3209 #ifdef AK_SUPPORT_WCHAR
3210  /// Sets the State of a Switch Group (by Unicode string names).
3211  /// \return
3212  /// - AK_Success if successful
3213  /// - AK_IDNotFound if the switch or Switch Group name was not resolved to an existing ID\n
3214  /// Make sure that the banks were generated with the "include string" option.
3215  /// \aknote Strings are case-insensitive. \endaknote
3216  /// \sa
3217  /// - \ref soundengine_switch
3218  AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )(
3219  const wchar_t* in_pszSwitchGroup, ///< Name of the Switch Group
3220  const wchar_t* in_pszSwitchState, ///< Name of the Switch
3221  AkGameObjectID in_gameObjectID ///< Associated game object ID
3222  );
3223 #endif //AK_SUPPORT_WCHAR
3224 
3225  /// Sets the state of a Switch Group.
3226  /// \return
3227  /// - AK_Success if successful
3228  /// - AK_IDNotFound if the switch or Switch Group name was not resolved to an existing ID\n
3229  /// Make sure that the banks were generated with the "include string" option.
3230  /// \aknote Strings are case-insensitive. \endaknote
3231  /// \sa
3232  /// - \ref soundengine_switch
3233  AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )(
3234  const char* in_pszSwitchGroup, ///< Name of the Switch Group
3235  const char* in_pszSwitchState, ///< Name of the Switch
3236  AkGameObjectID in_gameObjectID ///< Associated game object ID
3237  );
3238 
3239  /// Post the specified trigger (by IDs).
3240  /// \return Always returns AK_Success
3241  /// \sa
3242  /// - \ref soundengine_triggers
3243  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3244  AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )(
3245  AkTriggerID in_triggerID, ///< ID of the trigger
3246  AkGameObjectID in_gameObjectID ///< Associated game object ID
3247  );
3248 
3249 #ifdef AK_SUPPORT_WCHAR
3250  /// Posts the specified trigger (by Unicode string name).
3251  /// \return
3252  /// - AK_Success if successful
3253  /// - AK_IDNotFound if the trigger name was not resolved to an existing ID\n
3254  /// Make sure that the banks were generated with the "include string" option.
3255  /// \aknote Strings are case-insensitive. \endaknote
3256  /// \sa
3257  /// - \ref soundengine_triggers
3258  AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )(
3259  const wchar_t* in_pszTrigger, ///< Name of the trigger
3260  AkGameObjectID in_gameObjectID ///< Associated game object ID
3261  );
3262 #endif //AK_SUPPORT_WCHAR
3263 
3264  /// Posts the specified trigger.
3265  /// \return
3266  /// - AK_Success if successful
3267  /// - AK_IDNotFound if the trigger name was not resolved to an existing ID\n
3268  /// Make sure that the banks were generated with the "include string" option.
3269  /// \aknote Strings are case-insensitive. \endaknote
3270  /// \sa
3271  /// - \ref soundengine_triggers
3272  AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )(
3273  const char* in_pszTrigger, ///< Name of the trigger
3274  AkGameObjectID in_gameObjectID ///< Associated game object ID
3275  );
3276 
3277  /// Sets the state of a State Group (by IDs).
3278  /// \return Always returns AK_Success
3279  /// \sa
3280  /// - \ref soundengine_states
3281  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3282  AK_EXTERNAPIFUNC( AKRESULT, SetState )(
3283  AkStateGroupID in_stateGroup, ///< ID of the State Group
3284  AkStateID in_state ///< ID of the state
3285  );
3286 
3287 #ifdef AK_SUPPORT_WCHAR
3288  /// Sets the state of a State Group (by Unicode string names).
3289  /// \return
3290  /// - AK_Success if successful
3291  /// - AK_IDNotFound if the state or State Group name was not resolved to an existing ID\n
3292  /// Make sure that the banks were generated with the "include string" option.
3293  /// \aknote Strings are case-insensitive. \endaknote
3294  /// \sa
3295  /// - \ref soundengine_states
3296  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3297  AK_EXTERNAPIFUNC( AKRESULT, SetState )(
3298  const wchar_t* in_pszStateGroup, ///< Name of the State Group
3299  const wchar_t* in_pszState ///< Name of the state
3300  );
3301 #endif //AK_SUPPORT_WCHAR
3302 
3303  /// Sets the state of a State Group.
3304  /// \return
3305  /// - AK_Success if successful
3306  /// - AK_IDNotFound if the state or State Group name was not resolved to an existing ID\n
3307  /// Make sure that the banks were generated with the "include string" option.
3308  /// \aknote Strings are case-insensitive. \endaknote
3309  /// \sa
3310  /// - \ref soundengine_states
3311  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3312  AK_EXTERNAPIFUNC( AKRESULT, SetState )(
3313  const char* in_pszStateGroup, ///< Name of the State Group
3314  const char* in_pszState ///< Name of the state
3315  );
3316 
3317  //@}
3318 
3319  ////////////////////////////////////////////////////////////////////////
3320  /// @name Environments
3321  //@{
3322 
3323  /// Sets the Auxiliary Busses to route the specified game object
3324  /// To clear the game object's auxiliary sends, \c in_uNumSendValues must be 0.
3325  /// \sa
3326  /// - \ref soundengine_environments
3327  /// - \ref soundengine_environments_dynamic_aux_bus_routing
3328  /// - \ref soundengine_environments_id_vs_string
3329  /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
3330  /// \return
3331  /// - AK_Success if successful
3332  /// - AK_InvalidParameter if a duplicated environment is found in the array
3333  /// - AK_InvalidFloatValue if the value specified was NaN or Inf
3334  AK_EXTERNAPIFUNC( AKRESULT, SetGameObjectAuxSendValues )(
3335  AkGameObjectID in_gameObjectID, ///< Associated game object ID
3336  AkAuxSendValue* in_aAuxSendValues, ///< Variable-size array of AkAuxSendValue structures
3337  ///< (it may be NULL if no environment must be set)
3338  AkUInt32 in_uNumSendValues ///< The number of auxiliary busses at the pointer's address
3339  ///< (it must be 0 if no environment is set)
3340  );
3341 
3342  /// Registers a callback to allow the game to modify or override the volume to be applied at the output of an audio bus.
3343  /// The callback must be registered once per bus ID.
3344  /// Call with <tt>in_pfnCallback = NULL</tt> to unregister.
3345  /// \aknote The bus in_busID needs to be a mixing bus.\endaknote
3346  /// \aknote Beware when using this callback on the Master Audio Bus: since the output of this bus is not a bus, but is instead a system end-point, <tt>AkSpeakerVolumeMatrixCallbackInfo::pMixerContext</tt> will be \c NULL. You cannot modify panning at the output of the Master Audio Bus.\endaknote
3347  /// \sa
3348  /// - \ref goingfurther_speakermatrixcallback
3349  /// - \ref soundengine_environments
3350  /// - AkSpeakerVolumeMatrixCallbackInfo
3351  /// - <tt>AK::IAkMixerInputContext</tt>
3352  /// - <tt>AK::IAkMixerPluginContext</tt>
3353  /// \return
3354  /// - AK_Success if successful
3355  /// - AK_Fail if AK::SoundEngine::Init has not been called prior to this call.
3356  AK_EXTERNAPIFUNC( AKRESULT, RegisterBusVolumeCallback )(
3357  AkUniqueID in_busID, ///< Bus ID, as obtained by GetIDFromString( bus_name ).
3358  AkBusCallbackFunc in_pfnCallback ///< Callback function.
3359  );
3360 
3361  /// Registers a callback to be called to allow the game to access metering data from any mixing bus. You may use this to monitor loudness at any point of the mixing hierarchy
3362  /// by querying the peak, RMS, True Peak and K-weighted power (according to loudness standard ITU BS.1770). See \ref goingfurther_speakermatrixcallback for an example.
3363  /// The callback must be registered once per bus ID.
3364  /// Call with in_pfnCallback = NULL to unregister.
3365  /// \aknote The bus in_busID needs to be a mixing bus.\endaknote
3366  /// \sa
3367  /// - \ref goingfurther_speakermatrixcallback
3368  /// - AkBusMeteringCallbackFunc
3369  /// - <tt>AK::IAkMetering</tt>
3370  /// \return
3371  /// - AK_Success if successful
3372  /// - AK_Fail if AK::SoundEngine::Init has not been called prior to this call.
3373  AK_EXTERNAPIFUNC( AKRESULT, RegisterBusMeteringCallback )(
3374  AkUniqueID in_busID, ///< Bus ID, as obtained by GetIDFromString( bus_name ).
3375  AkBusMeteringCallbackFunc in_pfnCallback, ///< Callback function.
3376  AkMeteringFlags in_eMeteringFlags ///< Metering flags.
3377  );
3378 
3379  /// Sets the Output Bus Volume (direct) to be used for the specified game object.
3380  /// The control value is a number ranging from 0.0f to 1.0f.
3381  /// Output Bus Volumes are stored per listener association, so calling this function will override the default set of listeners. The game object in_emitterObjID will now reference its own set of listeners which will
3382  /// be the same as the old set of listeners, but with the new associated gain. Future changes to the default listener set will not be picked up by this game object unless ResetListenersToDefault() is called.
3383  /// \sa
3384  /// - \ref AK::SoundEngine::ResetListenersToDefault
3385  /// - \ref soundengine_environments
3386  /// - \ref soundengine_environments_setting_dry_environment
3387  /// - \ref soundengine_environments_id_vs_string
3388  /// \return
3389  /// - AK_Success when successful
3390  /// - AK_InvalidFloatValue if the value specified was NaN or Inf
3391  AK_EXTERNAPIFUNC( AKRESULT, SetGameObjectOutputBusVolume )(
3392  AkGameObjectID in_emitterObjID, ///< Associated emitter game object ID
3393  AkGameObjectID in_listenerObjID, ///< Associated listener game object ID. Pass AK_INVALID_GAME_OBJECT to set the Output Bus Volume for all connected listeners.
3394  AkReal32 in_fControlValue ///< A multiplier where 0 means silence and 1 means no change.
3395  ///< (Therefore, values between 0 and 1 will attenuate the sound, and values greater than 1 will amplify it.)
3396  );
3397 
3398  /// Sets an Effect ShareSet at the specified audio node and Effect slot index.
3399  /// The target node cannot be a Bus, to set effects on a bus, use SetBusEffect() instead.
3400  /// \aknote The option "Override Parent" in
3401  /// the Effect section in Wwise must be enabled for this node, otherwise the parent's effect will
3402  /// still be the one in use and the call to SetActorMixerEffect will have no impact.
3403  /// \endaknote
3404  /// \return Always returns AK_Success
3405  AK_EXTERNAPIFUNC( AKRESULT, SetActorMixerEffect )(
3406  AkUniqueID in_audioNodeID, ///< Can be a member of the Actor-Mixer or Interactive Music Hierarchy (not a bus).
3407  AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
3408  AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
3409  );
3410 
3411  /// Sets an Effect ShareSet at the specified bus and Effect slot index.
3412  /// The Bus can either be an Audio Bus or an Auxiliary Bus.
3413  /// This adds a reference on the audio node to an existing ShareSet.
3414  /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
3415  /// Bus which does not have any Effects, or removing the last Effect on a currently playing bus.
3416  /// \endaknote
3417  /// \aknote This function will replace existing Effects on the node. If the target node is not at
3418  /// the top of the hierarchy and is in the actor-mixer hierarchy, the option "Override Parent" in
3419  /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will
3420  /// still be the one in use and the call to SetBusEffect will have no impact.
3421  /// \endaknote
3422  /// \return Always returns AK_Success
3423  AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )(
3424  AkUniqueID in_audioNodeID, ///< Bus Short ID.
3425  AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
3426  AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to clear the Effect slot
3427  );
3428 
3429 #ifdef AK_SUPPORT_WCHAR
3430  /// Sets an Effect ShareSet at the specified Bus and Effect slot index.
3431  /// The Bus can either be an Audio Bus or an Auxiliary Bus.
3432  /// This adds a reference on the audio node to an existing ShareSet.
3433  /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
3434  /// bus which does not have any Effects, or removing the last Effect on a currently playing Bus.
3435  /// \endaknote
3436  /// \aknote This function will replace existing Effects on the node. If the target node is not at
3437  /// the top of the hierarchy and is in the Actor-Mixer Hierarchy, the option "Override Parent" in
3438  /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will
3439  /// still be the one in use and the call to \c SetBusEffect will have no impact.
3440  /// \endaknote
3441  /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
3442  AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )(
3443  const wchar_t* in_pszBusName, ///< Bus name
3444  AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
3445  AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
3446  );
3447 #endif //AK_SUPPORT_WCHAR
3448 
3449  /// Sets an Effect ShareSet at the specified Bus and Effect slot index.
3450  /// The Bus can either be an Audio Bus or an Auxiliary Bus.
3451  /// This adds a reference on the audio node to an existing ShareSet.
3452  /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
3453  /// Bus which does not have any effects, or removing the last Effect on a currently playing bus.
3454  /// \endaknote
3455  /// \aknote This function will replace existing Effects on the node. If the target node is not at
3456  /// the top of the hierarchy and is in the Actor-Mixer Hierarchy, the option "Override Parent" in
3457  /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will
3458  /// still be the one in use and the call to SetBusEffect will have no impact.
3459  /// \endaknote
3460  /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
3461  AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )(
3462  const char* in_pszBusName, ///< Bus name
3463  AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
3464  AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
3465  );
3466 
3467  /// Sets a Mixer ShareSet at the specified bus.
3468  /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
3469  /// Bus which does not have any Effects or mixer, or removing the last mixer on a currently playing Bus.
3470  /// \endaknote
3471  /// \aknote This function will replace existing mixers on the node.
3472  /// \endaknote
3473  /// \return Always returns AK_Success
3474  AK_EXTERNAPIFUNC( AKRESULT, SetMixer )(
3475  AkUniqueID in_audioNodeID, ///< Bus Short ID.
3476  AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to remove.
3477  );
3478 
3479 #ifdef AK_SUPPORT_WCHAR
3480  /// Sets a Mixer ShareSet at the specified bus.
3481  /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
3482  /// bus which does not have any effects nor mixer, or removing the last mixer on a currently playing bus.
3483  /// \endaknote
3484  /// \aknote This function will replace existing mixers on the node.
3485  /// \endaknote
3486  /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
3487  AK_EXTERNAPIFUNC( AKRESULT, SetMixer )(
3488  const wchar_t* in_pszBusName, ///< Bus name
3489  AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to remove.
3490  );
3491 #endif //AK_SUPPORT_WCHAR
3492 
3493  /// Sets a Mixer ShareSet at the specified bus.
3494  /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
3495  /// bus which does not have any effects nor mixer, or removing the last mixer on a currently playing bus.
3496  /// \endaknote
3497  /// \aknote This function will replace existing mixers on the node.
3498  /// \endaknote
3499  /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
3500  AK_EXTERNAPIFUNC( AKRESULT, SetMixer )(
3501  const char* in_pszBusName, ///< Bus name
3502  AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to remove.
3503  );
3504 
3505  /// Forces channel configuration for the specified bus.
3506  /// \aknote You cannot change the configuration of the master bus.\endaknote
3507  ///
3508  /// \return Always returns AK_Success
3509  AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
3510  AkUniqueID in_audioNodeID, ///< Bus Short ID.
3511  AkChannelConfig in_channelConfig ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
3512  );
3513 
3514 #ifdef AK_SUPPORT_WCHAR
3515  /// Forces channel configuration for the specified bus.
3516  /// \aknote You cannot change the configuration of the master bus.\endaknote
3517  ///
3518  /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
3519  AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
3520  const wchar_t* in_pszBusName, ///< Bus name
3521  AkChannelConfig in_channelConfig ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
3522  );
3523 #endif //AK_SUPPORT_WCHAR
3524 
3525  /// Forces channel configuration for the specified bus.
3526  /// \aknote You cannot change the configuration of the master bus.\endaknote
3527  ///
3528  /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
3529  AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
3530  const char* in_pszBusName, ///< Bus name
3531  AkChannelConfig in_channelConfig ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
3532  );
3533 
3534  /// Sets a game object's obstruction and occlusion levels. If SetMultiplePositions were used, values are set for all positions.
3535  /// This function is used to affect how an object should be heard by a specific listener.
3536  /// \sa
3537  /// - \ref soundengine_obsocc
3538  /// - \ref soundengine_environments
3539  /// \return Always returns AK_Success
3540  AK_EXTERNAPIFUNC( AKRESULT, SetObjectObstructionAndOcclusion )(
3541  AkGameObjectID in_EmitterID, ///< Emitter game object ID
3542  AkGameObjectID in_ListenerID, ///< Listener game object ID
3543  AkReal32 in_fObstructionLevel, ///< ObstructionLevel: [0.0f..1.0f]
3544  AkReal32 in_fOcclusionLevel ///< OcclusionLevel: [0.0f..1.0f]
3545  );
3546 
3547  /// Sets a game object's obstruction and occlusion level for each positions defined by SetMultiplePositions.
3548  /// This function differs from SetObjectObstructionAndOcclusion as a list of obstruction/occlusion pair is provided
3549  /// and each obstruction/occlusion pair will affect the corresponding position defined at the same index.
3550  /// \aknote In the case the number of obstruction/occlusion pairs is smaller than the number of positions, remaining positions'
3551  /// obstrucion/occlusion values are set to 0.0. \endaknote
3552  /// \sa
3553  /// - \ref soundengine_obsocc
3554  /// - \ref soundengine_environments
3555  /// \return AK_Success if occlusion/obstruction values are successfully stored for this emitter
3556  AK_EXTERNAPIFUNC( AKRESULT, SetMultipleObstructionAndOcclusion )(
3557  AkGameObjectID in_EmitterID, ///< Emitter game object ID
3558  AkGameObjectID in_uListenerID, ///< Listener game object ID
3559  AkObstructionOcclusionValues* in_fObstructionOcclusionValues, ///< Array of obstruction/occlusion pairs to apply
3560  ///< ObstructionLevel: [0.0f..1.0f]
3561  ///< OcclusionLevel: [0.0f..1.0f]
3562  AkUInt32 in_uNumOcclusionObstruction ///< Number of obstruction/occlusion pairs specified in the provided array
3563  );
3564 
3565  /// Saves the playback history of container structures.
3566  /// This function will write history data for all currently loaded containers and instantiated game
3567  /// objects (for example, current position in Sequence Containers and previously played elements in
3568  /// Random Containers).
3569  /// \remarks
3570  /// This function acquires the main audio lock, and may block the caller for several milliseconds.
3571  /// \sa
3572  /// - <tt>AK::SoundEngine::SetContainerHistory()</tt>
3573  AK_EXTERNAPIFUNC( AKRESULT, GetContainerHistory)(
3574  AK::IWriteBytes * in_pBytes ///< Pointer to IWriteBytes interface used to save the history.
3575  );
3576 
3577  /// Restores the playback history of container structures.
3578  /// This function will read history data from the passed-in stream reader interface, and apply it to all
3579  /// currently loaded containers and instantiated game objects. Game objects are matched by
3580  /// ID. History for unloaded structures and unknown game objects will be skipped.
3581  /// \remarks
3582  /// This function acquires the main audio lock, and may block the caller for several milliseconds.
3583  /// \sa
3584  /// - <tt>AK::SoundEngine::GetContainerHistory()</tt>
3585  AK_EXTERNAPIFUNC(AKRESULT, SetContainerHistory)(
3586  AK::IReadBytes * in_pBytes ///< Pointer to IReadBytes interface used to load the history.
3587  );
3588 
3589  //@}
3590 
3591  ////////////////////////////////////////////////////////////////////////
3592  /// @name Capture
3593  //@{
3594 
3595  /// Starts recording the sound engine audio output.
3596  /// StartOutputCapture outputs a wav file per current output device of the sound engine.
3597  /// If more than one device is active, the system will create multiple files in the same output
3598  /// directory and will append numbers at the end of the provided filename.
3599  ///
3600  /// If no device is running yet, the system will return success AK_Success despite doing nothing.
3601  /// Use RegisterAudioDeviceStatusCallback to get notified when devices are created/destructed.
3602  ///
3603  /// \return AK_Success if successful, AK_Fail if there was a problem starting the output capture.
3604  /// \remark
3605  /// - The sound engine opens a stream for writing using <tt>AK::IAkStreamMgr::CreateStd()</tt>. If you are using the
3606  /// default implementation of the Stream Manager, file opening is executed in your implementation of
3607  /// the Low-Level IO interface <tt>AK::StreamMgr::IAkFileLocationResolver::Open()</tt>. The following
3608  /// AkFileSystemFlags are passed: uCompanyID = AKCOMPANYID_AUDIOKINETIC and uCodecID = AKCODECID_PCM,
3609  /// and the AkOpenMode is AK_OpenModeWriteOvrwr. Refer to \ref streamingmanager_lowlevel_location for
3610  /// more details on managing the deployment of your Wwise generated data.
3611  /// \sa
3612  /// - <tt>AK::SoundEngine::StopOutputCapture()</tt>
3613  /// - <tt>AK::StreamMgr::SetFileLocationResolver()</tt>
3614  /// - \ref streamingdevicemanager
3615  /// - \ref streamingmanager_lowlevel_location
3616  /// - RegisterAudioDeviceStatusCallback
3617  AK_EXTERNAPIFUNC( AKRESULT, StartOutputCapture )(
3618  const AkOSChar* in_CaptureFileName ///< Name of the output capture file
3619  );
3620 
3621  /// Stops recording the sound engine audio output.
3622  /// \return AK_Success if successful, AK_Fail if there was a problem stopping the output capture.
3623  /// \sa
3624  /// - <tt>AK::SoundEngine::StartOutputCapture()</tt>
3625  AK_EXTERNAPIFUNC( AKRESULT, StopOutputCapture )();
3626 
3627  /// Adds text marker in audio output file.
3628  /// \return AK_Success if successful, AK_Fail if there was a problem adding the output marker.
3629  /// \sa
3630  /// - <tt>AK::SoundEngine::StartOutputCapture()</tt>
3631  AK_EXTERNAPIFUNC( AKRESULT, AddOutputCaptureMarker )(
3632  const char* in_MarkerText ///< Text of the marker
3633  );
3634 
3635  /// Starts recording the sound engine profiling information into a file. This file can be read
3636  /// by Wwise Authoring.
3637  /// \remark This function is provided as a utility tool only. It does nothing if it is
3638  /// called in the release configuration and returns AK_NotCompatible.
3639  AK_EXTERNAPIFUNC( AKRESULT, StartProfilerCapture )(
3640  const AkOSChar* in_CaptureFileName ///< Name of the output profiler file (.prof extension recommended)
3641  );
3642 
3643  /// Stops recording the sound engine profiling information.
3644  /// \remark This function is provided as a utility tool only. It does nothing if it is
3645  /// called in the release configuration and returns AK_NotCompatible.
3646  AK_EXTERNAPIFUNC( AKRESULT, StopProfilerCapture )();
3647 
3648  //@}
3649 
3650  ////////////////////////////////////////////////////////////////////////
3651  /// @name Secondary Outputs
3652  //@{
3653 
3654  /// Adds an output to the sound engine. Use this to add controller-attached headphones, controller speakers, DVR output, etc.
3655  /// The in_Settings parameter contains an Audio Device shareset to specify the output plugin to use and a device ID to specify the instance, if necessary (e.g. which game controller).
3656  /// \sa AkOutputSettings for more details.
3657  /// \sa \ref integrating_secondary_outputs
3658  /// \sa \ref default_audio_devices
3659  /// \return
3660  /// - AK_NotImplemented: Feature not supported
3661  /// - AK_InvalidParameter: Out of range parameters or unsupported parameter combinations (see parameter list below).
3662  /// - AK_IDNotFound: The audioDeviceShareset on in_settings doesn't exist. Possibly, the Init bank isn't loaded yet or was not updated with latest changes.
3663  /// - AK_DeviceNotReady: The idDevice on in_settings doesn't match with a valid hardware device. Either the device doesn't exist or is disabled. Disconnected devices (headphones) are not considered "not ready" therefore won't cause this error.
3664  /// - AK_Success: Parameters are valid.
3665  AK_EXTERNAPIFUNC(AKRESULT, AddOutput)(
3666  const AkOutputSettings & in_Settings, ///< Creation parameters for this output. \ref AkOutputSettings
3667  AkOutputDeviceID *out_pDeviceID = NULL, ///< (Optional) Output ID to use with all other Output management functions. Leave to NULL if not required. \ref AK::SoundEngine::GetOutputID
3668  const AkGameObjectID* in_pListenerIDs = NULL, ///< Specific listener(s) to attach to this device.
3669  ///< If specified, only the sounds routed to game objects linked to those listeners will play in this device.
3670  ///< It is necessary to have separate listeners if multiple devices of the same type can coexist (e.g. controller speakers)
3671  ///< If not specified, sound routing simply obey the associations between Master Busses and Audio Devices setup in the Wwise Project.
3672  AkUInt32 in_uNumListeners = 0 ///< The number of elements in the in_pListenerIDs array.
3673  );
3674 
3675  /// Removes one output added through AK::SoundEngine::AddOutput
3676  /// If a listener was associated with the device, you should consider unregistering the listener prior to call RemoveOutput
3677  /// so that Game Object/Listener routing is properly updated according to your game scenario.
3678  /// \sa \ref integrating_secondary_outputs
3679  /// \sa AK::SoundEngine::AddOutput
3680  /// \return AK_Success: Parameters are valid.
3681  AK_EXTERNAPIFUNC(AKRESULT, RemoveOutput)(
3682  AkOutputDeviceID in_idOutput ///< ID of the output to remove. Use the returned ID from AddOutput, GetOutputID, or ReplaceOutput
3683  );
3684 
3685  /// Replaces an output device previously created during engine initialization or from AddOutput, with a new output device.
3686  /// In addition to simply removing one output device and adding a new one, the new output device will also be used on all of the master buses
3687  /// that the old output device was associated with, and preserve all listeners that were attached to the old output device.
3688  /// \sa AK::SoundEngine::AddOutput
3689  /// \return
3690  /// - AK_InvalidID: The audioDeviceShareset on in_settings was not valid.
3691  /// - AK_IDNotFound: The audioDeviceShareset on in_settings doesn't exist. Possibly, the Init bank isn't loaded yet or was not updated with latest changes.
3692  /// - AK_DeviceNotReady: The idDevice on in_settings doesn't match with a valid hardware device. Either the device doesn't exist or is disabled. Disconnected devices (headphones) are not considered "not ready" therefore won't cause this error.
3693  /// - AK_DeviceNotFound: The in_outputDeviceId provided does not match with any of the output devices that the sound engine is currently using.
3694  /// - AK_InvalidParameter: Out of range parameters or unsupported parameter combinations on in_settings
3695  /// - AK_Success: parameters were valid, and the remove and add will occur.
3696  AK_EXTERNAPIFUNC(AKRESULT, ReplaceOutput)(
3697  const AkOutputSettings & in_Settings, ///< Creation parameters for this output. \ref AkOutputSettings
3698  AkOutputDeviceID in_outputDeviceId, ///< AkOutputDeviceID of the output to replace. For example, use the AkOuptutDeviceID returned from AddOutput() or ReplaceOutput(), or generated by GetOutputID()
3699  AkOutputDeviceID *out_pOutputDeviceId = NULL ///< (Optional) Pointer into which the method writes the AkOutputDeviceID of the new output device. If the call fails, the value pointed to will not be modified.
3700  );
3701 
3702  /// Gets the compounded output ID from shareset and device id.
3703  /// Outputs are defined by their type (Audio Device shareset) and their specific system ID. A system ID could be reused for other device types on some OS or platforms, hence the compounded ID.
3704  /// \return The id of the output
3705  AK_EXTERNAPIFUNC(AkOutputDeviceID, GetOutputID)(
3706  AkUniqueID in_idShareset, ///< Audio Device ShareSet ID, as defined in the Wwise Project. If needed, use AK::SoundEngine::GetIDFromString() to convert from a string. Set to AK_INVALID_UNIQUE_ID to use the default.
3707  AkUInt32 in_idDevice ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
3708  ///< - PS4 Controller-Speakers: UserID as returned from sceUserServiceGetLoginUserIdList
3709  ///< - XBoxOne Controller-Headphones: Use the AK::GetDeviceID function to get the ID from an IMMDevice. Find the player's device with the WASAPI API (IMMDeviceEnumerator, see Microsoft documentation) or use AK::GetDeviceIDFromName.
3710  ///< - Windows: Use AK::GetDeviceID or AK::GetDeviceIDFromName to get the correct ID.
3711  ///< - All others output: use 0 to select the default device for that type.
3712  );
3713 
3714  AK_EXTERNAPIFUNC(AkOutputDeviceID, GetOutputID)(
3715  const char* in_szShareSet, ///< Audio Device ShareSet Name, as defined in the Wwise Project. If Null, will select the Default Output shareset (always available)
3716  AkUInt32 in_idDevice ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
3717  ///< - PS4 Controller-Speakers: UserID as returned from sceUserServiceGetLoginUserIdList
3718  ///< - XBoxOne Controller-Headphones: Use the AK::GetDeviceID function to get the ID from an IMMDevice. Find the player's device with the WASAPI API (IMMDeviceEnumerator, see Microsoft documentation) or use AK::GetDeviceIDFromName.
3719  ///< - Windows: Use AK::GetDeviceID or AK::GetDeviceIDFromName to get the correct ID.
3720  ///< - All others output: use 0 to select the default device for that type.
3721  );
3722 
3723  #ifdef AK_SUPPORT_WCHAR
3724  AK_EXTERNAPIFUNC(AkOutputDeviceID, GetOutputID)(
3725  const wchar_t* in_szShareSet, ///< Audio Device ShareSet Name, as defined in the Wwise Project. If Null, will select the Default Output shareset (always available)
3726  AkUInt32 in_idDevice ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
3727  ///< - PS4 Controller-Speakers: UserID as returned from sceUserServiceGetLoginUserIdList
3728  ///< - XBoxOne Controller-Headphones: Use the AK::GetDeviceID function to get the ID from an IMMDevice. Find the player's device with the WASAPI API (IMMDeviceEnumerator, see Microsoft documentation) or use AK::GetDeviceIDFromName.
3729  ///< - Windows: Use AK::GetDeviceID or AK::GetDeviceIDFromName to get the correct ID.
3730  ///< - All others output: use 0 to select the default device for that type.
3731  );
3732  #endif
3733 
3734  /// Sets the Audio Device to which a master bus outputs. This overrides the setting in the Wwise project.
3735  /// Can only be set on top-level busses. The Init bank should be successfully loaded prior to this call.
3736  /// SetBusDevice must be preceded by a call to AddOutput for the new device shareset to be registered as an output.
3737  /// \return
3738  /// AK_IDNotFound when either the Bus ID or the Device ID are not present in the Init bank or the bank was not loaded
3739  /// AK_InvalidParameter when the specified bus is not a Master Bus. This function can be called only on busses that have no parent bus.
3740  AK_EXTERNAPIFUNC(AKRESULT, SetBusDevice)(
3741  AkUniqueID in_idBus, ///< Id of the master bus
3742  AkUniqueID in_idNewDevice ///< New device shareset to replace with.
3743  );
3744 
3745  /// Sets the Audio Device to which a master bus outputs. This overrides the setting in the Wwise project.
3746  /// Can only be set on top-level busses. The Init bank should be successfully loaded prior to this call.
3747  /// SetBusDevice must be preceded by a call to AddOutput for the new device shareset to be registered as an output.
3748  /// \return
3749  /// AK_IDNotFound when either the Bus ID or the Device ID are not present in the Init bank or the bank was not loaded
3750  /// AK_InvalidParameter when the specified bus is not a Master Bus. This function can be called only on busses that have no parent bus.
3751  AK_EXTERNAPIFUNC(AKRESULT, SetBusDevice)(
3752  const char* in_BusName, ///< Name of the master bus
3753  const char* in_DeviceName ///< New device shareset to replace with.
3754  );
3755 
3756  #ifdef AK_SUPPORT_WCHAR
3757  /// Sets the Audio Device to which a master bus outputs. This overrides the setting in the Wwise project.
3758  /// Can only be set on top-level busses. The Init bank should be successfully loaded prior to this call.
3759  /// SetBusDevice must be preceded by a call to AddOutput for the new device shareset to be registered as an output.
3760  /// \return
3761  /// AK_IDNotFound when either the Bus ID or the Device ID are not present in the Init bank or the bank was not loaded
3762  /// AK_InvalidParameter when the specified bus is not a Master Bus. This function can be called only on busses that have no parent bus.
3763  AK_EXTERNAPIFUNC(AKRESULT, SetBusDevice)(
3764  const wchar_t* in_BusName, ///< Name of the master bus
3765  const wchar_t* in_DeviceName ///< New device shareset to replace with.
3766  );
3767  #endif
3768 
3769  /// Sets the volume of a output device.
3770  /// \return
3771  /// - AK_Success if successful
3772  /// - AK_InvalidFloatValue if the value specified was NaN or Inf
3773  AK_EXTERNAPIFUNC( AKRESULT, SetOutputVolume )(
3774  AkOutputDeviceID in_idOutput, ///< Output ID to set the volume on. As returned from AddOutput or GetOutputID
3775  AkReal32 in_fVolume ///< Volume (0.0 = Muted, 1.0 = Volume max)
3776  );
3777 
3778  /// Returns whether or not the audio device matching the device ID provided supports spatial audio (i.e. the functionality is enabled, and more than 0 dynamic objects are supported).
3779  /// If Spatial Audio is supported, then you can call Init, AddOutput, or ReplaceOutput with an Audio Device Shareset corresponding to the respective platform-specific plug-in that
3780  /// provides spatial audio, such as the Microsoft Spatial Sound Platform for Windows. Note that on Xbox One, you need to call EnableSpatialAudio() before the sound engine is
3781  /// initialized, or initialize the sound engine with AkPlatformInitSettings::bEnableSpatialAudio set to true if you want spatial audio support; otherwise this will always return AK_NotCompatible.
3782  /// \return
3783  /// AK_NotCompatible when the device ID provided does not support spatial audio, or the platform does not support spatial audio
3784  /// AK_Fail when there is some other miscellaneous failure, or the device ID provided does not match a device that the system knows about
3785  /// AK_Success when the device ID provided does support spatial audio
3786  AK_EXTERNAPIFUNC( AKRESULT, GetDeviceSpatialAudioSupport ) (
3787  AkUInt32 in_idDevice ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
3788  ///< - PS4 Controller-Speakers: UserID as returned from sceUserServiceGetLoginUserIdList
3789  ///< - XBoxOne Controller-Headphones: Use the AK::GetDeviceID function to get the ID from an IMMDevice. Find the player's device with the WASAPI API (IMMDeviceEnumerator, see Microsoft documentation) or use AK::GetDeviceIDFromName.
3790  ///< - Windows: Use AK::GetDeviceID or AK::GetDeviceIDFromName to get the correct ID.
3791  ///< - All others output: use 0 to select the default device for that type.
3792  );
3793 
3794 
3795  //@}
3796 
3797  /// This function should be called to put the sound engine in background mode, where audio isn't processed anymore. This needs to be called if the console has a background mode or some suspended state.
3798  /// Call \c WakeupFromSuspend when your application receives the message from the OS that the process is back in foreground.
3799  /// When suspended, the sound engine will process API messages (like PostEvent and SetSwitch) only when \ref RenderAudio() is called.
3800  /// It is recommended to match the <b>in_bRenderAnyway</b> parameter with the behavior of the rest of your game:
3801  /// if your game still runs in background and you must keep some kind of coherent state between the audio engine and game, then allow rendering.
3802  /// If you want to minimize CPU when in background, then don't allow rendering and never call RenderAudio from the game.
3803  ///
3804  /// - Android: Call for APP_CMD_PAUSE
3805  /// - iOS: Don't call. All audio interrupts are handled internally.
3806  /// - XBoxOne: Use when entering constrained mode or suspended mode (see ResourceAvailability in Xbox One documentation).
3807  /// \sa WakeupFromSuspend
3808  AK_EXTERNAPIFUNC( AKRESULT, Suspend )(
3809  bool in_bRenderAnyway = false /// If set to true, audio processing will still occur, but not outputted. When set to false, no audio will be processed at all, even upon reception of RenderAudio().
3810  );
3811 
3812  /// This function should be called to wake up the sound engine and start processing audio again. This needs to be called if the console has a background mode or some suspended state.
3813  /// - Android: Call for APP_CMD_RESUME
3814  /// - iOS: Don't call. All audio interrupts are handled internally.
3815  /// - XBoxOne: Use when the game is back to Full resources (see ResourceAvailability in Xbox One documentation).
3816  AK_EXTERNAPIFUNC( AKRESULT, WakeupFromSuspend )();
3817 
3818  /// Obtains the current audio output buffer tick. This corresponds to the number of buffers produced by
3819  /// the sound engine since initialization.
3820  /// \return Tick count.
3821  AK_EXTERNAPIFUNC(AkUInt32, GetBufferTick)();
3822  }
3823 }
3824 
3825 #endif // _AK_SOUNDENGINE_H_
AKRESULT __cdecl PostTrigger(AkTriggerID in_triggerID, AkGameObjectID in_gameObjectID)
AKRESULT __cdecl GetDeviceSpatialAudioSupport(AkUInt32 in_idDevice)
AKRESULT __cdecl RegisterAudioDeviceStatusCallback(AK::AkDeviceStatusCallbackFunc in_pCallback)
AKRESULT __cdecl SetScalingFactor(AkGameObjectID in_GameObjectID, AkReal32 in_fAttenuationScalingFactor)
AKRESULT __cdecl RenderAudio(bool in_bAllowSyncRender=true)
AKRESULT __cdecl Init(AkInitSettings *in_pSettings, AkPlatformInitSettings *in_pPlatformSettings)
AKRESULT __cdecl ReplaceOutput(const AkOutputSettings &in_Settings, AkOutputDeviceID in_outputDeviceId, AkOutputDeviceID *out_pOutputDeviceId=NULL)
AKRESULT __cdecl Suspend(bool in_bRenderAnyway=false)
AkUInt32 __cdecl GetIDFromString(const char *in_pszString)
AKRESULT __cdecl SetVolumeThreshold(AkReal32 in_fVolumeThresholdDB)
AKRESULT __cdecl RemoveListener(AkGameObjectID in_emitterGameObj, AkGameObjectID in_listenerGameObj)
void __cdecl StopPlayingID(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
ParallelForFunc fcnParallelFor
ParallelForFunc callback.
Definition: AkSoundEngine.h:196
AKRESULT __cdecl SetGameObjectAuxSendValues(AkGameObjectID in_gameObjectID, AkAuxSendValue *in_aAuxSendValues, AkUInt32 in_uNumSendValues)
AkOSChar * szPluginDLLPath
When using DLLs for plugins, specify their path. Leave NULL if DLLs are in the same folder as the gam...
Definition: AkSoundEngine.h:232
AKRESULT __cdecl GetSourceStreamBuffering(AkPlayingID in_PlayingID, AkTimeMs &out_buffering, bool &out_bIsBuffering)
AKRESULT __cdecl SendPluginCustomGameData(AkUniqueID in_busID, AkGameObjectID in_busObjectID, AkPluginType in_eType, AkUInt32 in_uCompanyID, AkUInt32 in_uPluginID, const void *in_pData, AkUInt32 in_uSizeInBytes)
AKRESULT __cdecl SeekOnEvent(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkTimeMs in_iPosition, bool in_bSeekToNearestMarker=false, AkPlayingID in_PlayingID=AK_INVALID_PLAYING_ID)
AkUniqueID mediaID
Media ID of playing item. (corresponds to 'ID' attribute of 'File' element in SoundBank metadata file...
Definition: AkSoundEngine.h:252
bool bUseLEngineThread
Use a separate thread for processing audio. If set to false, audio processing will occur in RenderAud...
Definition: AkSoundEngine.h:228
AKRESULT __cdecl SetRTPCValue(AkRtpcID in_rtpcID, AkRtpcValue in_value, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT, AkTimeMs in_uValueChangeDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear, bool in_bBypassInternalValueInterpolation=false)
bool __cdecl GetBackgroundMusicMute()
Positioning information for a sound, with specified subset of its channels.
Definition: AkTypes.h:438
AkFloorPlane eFloorPlane
Floor plane axis for 3D game object viewing.
Definition: AkSoundEngine.h:234
AKRESULT __cdecl SetDefaultListeners(const AkGameObjectID *in_pListenerObjs, AkUInt32 in_uNumListeners)
PrepareEvent() will unload required information to play the specified event.
Definition: AkSoundEngine.h:2249
AkReal32 fDefaultPoolRatioThreshold
0.0f to 1.0f value: The percentage of occupied memory where the sound engine should enter in Low memo...
Definition: AkSoundEngine.h:212
AKRESULT __cdecl SetMedia(AkSourceSettings *in_pSourceSettings, AkUInt32 in_uNumSourceSettings)
AKRESULT __cdecl UnsetMedia(AkSourceSettings *in_pSourceSettings, AkUInt32 in_uNumSourceSettings)
AKRESULT __cdecl SetListenerSpatialization(AkGameObjectID in_uListenerID, bool in_bSpatialized, AkChannelConfig in_channelConfig, AK::SpeakerVolumes::VectorPtr in_pVolumeOffsets=NULL)
AKRESULT __cdecl PrepareEvent(PreparationType in_PreparationType, const char **in_ppszString, AkUInt32 in_uNumEvent)
AKRESULT __cdecl SetMaxNumVoicesLimit(AkUInt16 in_maxNumberVoices)
AKRESULT __cdecl ResetListenersToDefault(AkGameObjectID in_emitterGameObj)
AkUniqueID audioDeviceShareset
Definition: AkSoundEngine.h:142
AKRESULT __cdecl ClearPreparedEvents()
Audiokinetic namespace.
void __cdecl CancelEventCallbackGameObject(AkGameObjectID in_gameObjectID)
AkOutputSettings settingsMainOutput
Main output device settings.
Definition: AkSoundEngine.h:224
void __cdecl SetRandomSeed(AkUInt32 in_uSeed)
PrepareEvent() will load required information to play the specified event.
Definition: AkSoundEngine.h:2248
AKRESULT __cdecl StopProfilerCapture()
AkMemPoolId uPrepareEventMemoryPoolID
Memory pool where data allocated by AK::SoundEngine::PrepareEvent() and AK::SoundEngine::PrepareGameS...
Definition: AkSoundEngine.h:214
AKRESULT __cdecl SetBusDevice(AkUniqueID in_idBus, AkUniqueID in_idNewDevice)
AkUInt32 uMediaSize
Size, in bytes, of the data to be set for the source.
Definition: AkSoundEngine.h:245
AKRESULT __cdecl AddOutput(const AkOutputSettings &in_Settings, AkOutputDeviceID *out_pDeviceID=NULL, const AkGameObjectID *in_pListenerIDs=NULL, AkUInt32 in_uNumListeners=0)
AKRESULT __cdecl SetBankLoadIOSettings(AkReal32 in_fThroughput, AkPriority in_priority)
AkUInt32 __cdecl GetBufferTick()
Global plugin context used for plugin registration/initialization. Games query this interface from th...
Definition: IAkPlugin.h:1116
void __cdecl CancelEventCallback(AkPlayingID in_playingID)
AKRESULT __cdecl UnpinEventInStreamCache(AkUniqueID in_eventID)
Description of the client task scheduler.
Definition: AkSoundEngine.h:183
AKRESULT __cdecl UnloadBank(const char *in_pszString, const void *in_pInMemoryBankPtr, AkMemPoolId *out_pMemPoolId=NULL)
AkUniqueID sourceID
Source ID (available in the SoundBank content files)
Definition: AkSoundEngine.h:243
Return values for GetSourcePlayPositions.
Definition: AkSoundEngine.h:249
AkAssertHook pfnAssertHook
External assertion handling function (optional)
Definition: AkSoundEngine.h:208
AKRESULT __cdecl PostMIDIOnEvent(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkMIDIPost *in_pPosts, AkUInt16 in_uNumPosts)
AkUInt32 uNumSamplesPerFrame
Number of samples per audio frame (256, 512, 1024, or 2048).
Definition: AkSoundEngine.h:219
Configured audio settings.
Definition: AkTypes.h:202
AKRESULT __cdecl UnregisterAudioDeviceStatusCallback()
Unregisters the callback for the Audio Device status changes, registered by RegisterAudioDeviceStatus...
AKRESULT __cdecl WakeupFromSuspend()
MultiPositionType
Definition: AkTypes.h:735
The execution context for a task.
Definition: AkSoundEngine.h:174
AkReal32 fDebugOutOfRangeLimit
Debug setting: Only used when bDebugOutOfRangeCheckEnabled is true. This defines the maximum values s...
Definition: AkSoundEngine.h:236
AKRESULT __cdecl SetActorMixerEffect(AkUniqueID in_audioNodeID, AkUInt32 in_uFXIndex, AkUniqueID in_shareSetID)
Auxiliary bus sends information per game object per given auxiliary bus.
Definition: AkTypes.h:565
void __cdecl GetDefaultPlatformInitSettings(AkPlatformInitSettings &out_platformSettings)
AkTaskSchedulerDesc taskSchedulerDesc
The defined client task scheduler that AkSoundEngine will use to schedule internal tasks.
Definition: AkSoundEngine.h:235
AKRESULT __cdecl StopOutputCapture()
AKRESULT __cdecl SetPanningRule(AkPanningRule in_ePanningRule, AkOutputDeviceID in_idOutput=0)
AKRESULT __cdecl AddDefaultListener(AkGameObjectID in_listenerGameObj)
AkUInt32 uDefaultPoolSize
Size of the default memory pool, in bytes.
Definition: AkSoundEngine.h:211
AKRESULT __cdecl PrepareGameSyncs(PreparationType in_PreparationType, AkGroupType in_eGameSyncType, const char *in_pszGroupName, const char **in_ppszGameSyncName, AkUInt32 in_uNumGameSyncs)
AkBackgroundMusicChangeCallbackFunc BGMCallback
Application-defined audio source change event callback function.
Definition: AkSoundEngine.h:230
AKRESULT __cdecl AddListener(AkGameObjectID in_emitterGameObj, AkGameObjectID in_listenerGameObj)
AKRESULT __cdecl SetSpeakerAngles(const AkReal32 *in_pfSpeakerAngles, AkUInt32 in_uNumAngles, AkReal32 in_fHeightAngle, AkOutputDeviceID in_idOutput=0)
AkUInt32 uMaxNumPaths
Maximum number of paths for positioning.
Definition: AkSoundEngine.h:210
AKRESULT __cdecl SetListeners(AkGameObjectID in_emitterGameObj, const AkGameObjectID *in_pListenerGameObjs, AkUInt32 in_uNumListeners)
AkUInt32 uContinuousPlaybackLookAhead
Default is 1 audio quantum, also known as an audio frame. Its size is equal to AkInitSettings::uNumSa...
Definition: AkSoundEngine.h:216
AKRESULT __cdecl UnregisterAllGameObj()
AkOutputDeviceID __cdecl GetOutputID(AkUniqueID in_idShareset, AkUInt32 in_idDevice)
AKRESULT __cdecl SetOutputVolume(AkOutputDeviceID in_idOutput, AkReal32 in_fVolume)
AkUInt32 uIdxThread
The current thread index [0, AkTaskSchedulerDesc::uNumSchedulerWorkerThreads[.
Definition: AkSoundEngine.h:176
AKRESULT __cdecl SetBusConfig(AkUniqueID in_audioNodeID, AkChannelConfig in_channelConfig)
AkTimeMs msTime
Position of the source (in ms) associated with that playing item.
Definition: AkSoundEngine.h:253
AKRESULT __cdecl RegisterPlugin(AkPluginType in_eType, AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkCreatePluginCallback in_pCreateFunc, AkCreateParamCallback in_pCreateParamFunc)
AKRESULT __cdecl SetObjectObstructionAndOcclusion(AkGameObjectID in_EmitterID, AkGameObjectID in_ListenerID, AkReal32 in_fObstructionLevel, AkReal32 in_fOcclusionLevel)
AKRESULT __cdecl SetMixer(AkUniqueID in_audioNodeID, AkUniqueID in_shareSetID)
AKRESULT __cdecl SetState(AkStateGroupID in_stateGroup, AkStateID in_state)
Platform-independent initialization settings of output devices.
Definition: AkSoundEngine.h:128
bool bEnableGameSyncPreparation
Sets to true to enable AK::SoundEngine::PrepareGameSync usage.
Definition: AkSoundEngine.h:215
void __cdecl StopAll(AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT)
Necessary settings for setting externally-loaded sources.
Definition: AkSoundEngine.h:241
AKRESULT __cdecl ExecuteActionOnEvent(AkUniqueID in_eventID, AkActionOnEventType in_ActionType, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear, AkPlayingID in_PlayingID=AK_INVALID_PLAYING_ID)
AKRESULT __cdecl StartProfilerCapture(const AkOSChar *in_CaptureFileName)
AKRESULT __cdecl RegisterBusVolumeCallback(AkUniqueID in_busID, AkBusCallbackFunc in_pfnCallback)
AKRESULT __cdecl SetGameObjectOutputBusVolume(AkGameObjectID in_emitterObjID, AkGameObjectID in_listenerObjID, AkReal32 in_fControlValue)
AkUInt32 uNumSchedulerWorkerThreads
The number of worker threads in the schduler.
Definition: AkSoundEngine.h:197
AkPlayingID __cdecl PostEvent(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, AkUInt32 in_cExternals=0, AkExternalSourceInfo *in_pExternalSources=NULL, AkPlayingID in_PlayingID=AK_INVALID_PLAYING_ID)
AKRESULT __cdecl SetSwitch(AkSwitchGroupID in_switchGroup, AkSwitchStateID in_switchState, AkGameObjectID in_gameObjectID)
void __cdecl Term()
Definition: AkMidiTypes.h:228
AKRESULT __cdecl GetAudioSettings(AkAudioSettings &out_audioSettings)
AKRESULT __cdecl GetPanningRule(AkPanningRule &out_ePanningRule, AkOutputDeviceID in_idOutput=0)
AKRESULT __cdecl SetBusEffect(AkUniqueID in_audioNodeID, AkUInt32 in_uFXIndex, AkUniqueID in_shareSetID)
AKRESULT __cdecl SetMultiplePositions(AkGameObjectID in_GameObjectID, const AkSoundPosition *in_pPositions, AkUInt16 in_NumPositions, MultiPositionType in_eMultiPositionType=MultiPositionType_MultiDirections)
AkUInt8 * pMediaMemory
Pointer to the data to be set for the source.
Definition: AkSoundEngine.h:244
AkPanningRule ePanningRule
Definition: AkSoundEngine.h:156
AkChannelConfig __cdecl GetSpeakerConfiguration(AkOutputDeviceID in_idOutput=0)
AKRESULT __cdecl UnregisterGameObj(AkGameObjectID in_gameObjectID)
AKRESULT __cdecl GetContainerHistory(AK::IWriteBytes *in_pBytes)
AKRESULT __cdecl GetSourcePlayPosition(AkPlayingID in_PlayingID, AkTimeMs *out_puPosition, bool in_bExtrapolate=true)
Obstruction/occlusion pair for a position.
Definition: AkTypes.h:431
AKRESULT __cdecl GetSpeakerAngles(AkReal32 *io_pfSpeakerAngles, AkUInt32 &io_uNumAngles, AkReal32 &out_fHeightAngle, AkOutputDeviceID in_idOutput=0)
void * BGMCallbackCookie
Application-defined user data for the audio source change event callback function.
Definition: AkSoundEngine.h:231
AKRESULT __cdecl SetContainerHistory(AK::IReadBytes *in_pBytes)
void __cdecl GetDefaultInitSettings(AkInitSettings &out_settings)
AkReal32 * VectorPtr
Volume vector. Access each element with the standard bracket [] operator.
Definition: AkSpeakerVolumes.h:49
AKRESULT __cdecl StopMIDIOnEvent(AkUniqueID in_eventID=AK_INVALID_UNIQUE_ID, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT)
AKRESULT __cdecl SetMultipleObstructionAndOcclusion(AkGameObjectID in_EmitterID, AkGameObjectID in_uListenerID, AkObstructionOcclusionValues *in_fObstructionOcclusionValues, AkUInt32 in_uNumOcclusionObstruction)
AkChannelConfig channelConfig
Definition: AkSoundEngine.h:160
Position and orientation of game objects.
Definition: AkTypes.h:305
AKRESULT __cdecl RegisterPluginDLL(const AkOSChar *in_DllName, const AkOSChar *in_DllPath=NULL)
AKRESULT __cdecl PrepareBank(AK::SoundEngine::PreparationType in_PreparationType, const char *in_pszString, AK::SoundEngine::AkBankContent in_uFlags=AkBankContent_All)
void __cdecl CancelBankCallbackCookie(void *in_pCookie)
AkUniqueID audioNodeID
Audio Node ID of playing item.
Definition: AkSoundEngine.h:251
AKRESULT __cdecl LoadBank(const char *in_pszString, AkMemPoolId in_memPoolId, AkBankID &out_bankID)
AKRESULT __cdecl UnregisterGlobalCallback(AkGlobalCallbackFunc in_pCallback, AkUInt32 in_eLocation=AkGlobalCallbackLocation_BeginRender)
AKRESULT __cdecl RegisterGameObj(AkGameObjectID in_gameObjectID)
Vorbis media is decoded when loading, and an uncompressed PCM version is used for playback.
Definition: AkSoundEngine.h:2250
AKRESULT __cdecl SetRTPCValueByPlayingID(AkRtpcID in_rtpcID, AkRtpcValue in_value, AkPlayingID in_playingID, AkTimeMs in_uValueChangeDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear, bool in_bBypassInternalValueInterpolation=false)
AKRESULT __cdecl StartOutputCapture(const AkOSChar *in_CaptureFileName)
AKRESULT __cdecl GetBufferStatusForPinnedEvent(AkUniqueID in_eventID, AkReal32 &out_fPercentBuffered, bool &out_bCachePinnedMemoryFull)
AKRESULT __cdecl ResetRTPCValue(AkRtpcID in_rtpcID, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT, AkTimeMs in_uValueChangeDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear, bool in_bBypassInternalValueInterpolation=false)
void(* AkDeviceStatusCallbackFunc)(AK::IAkGlobalPluginContext *in_pContext, AkUniqueID in_idAudioDeviceShareset, AkUInt32 in_idDeviceID, AkAudioDeviceEvent in_idEvent, AKRESULT in_AkResult)
Callback for Audio Device status changes.
Definition: AkCallback.h:342
void __cdecl ExecuteActionOnPlayingID(AkActionOnEventType in_ActionType, AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
AKRESULT __cdecl RegisterBusMeteringCallback(AkUniqueID in_busID, AkBusMeteringCallbackFunc in_pfnCallback, AkMeteringFlags in_eMeteringFlags)
AkUInt32 idDevice
Definition: AkSoundEngine.h:150
AkUInt32 uCommandQueueSize
Size of the command queue, in bytes.
Definition: AkSoundEngine.h:213
AkUInt32 uMaxHardwareTimeoutMs
Amount of time to wait for HW devices to trigger an audio interrupt. If there is no interrupt after t...
Definition: AkSoundEngine.h:225
bool __cdecl IsInitialized()
Use AkBankContent_StructureOnly to load only the structural content, including Events,...
Definition: AkSoundEngine.h:2261
AKRESULT __cdecl GetSourcePlayPositions(AkPlayingID in_PlayingID, AkSourcePosition *out_puPositions, AkUInt32 *io_pcPositions, bool in_bExtrapolate=true)
Use AkBankContent_All to load both the media and structural content.
Definition: AkSoundEngine.h:2262
bool bDebugOutOfRangeCheckEnabled
Debug setting: Enable checks for out-of-range (and NAN) floats in the processing code....
Definition: AkSoundEngine.h:237
AKRESULT __cdecl RegisterCodec(AkUInt32 in_ulCompanyID, AkUInt32 in_ulCodecID, AkCreateFileSourceCallback in_pFileCreateFunc, AkCreateBankSourceCallback in_pBankCreateFunc)
AKRESULT __cdecl AddOutputCaptureMarker(const char *in_MarkerText)
void(* ParallelForFunc)(void *in_pData, AkUInt32 in_uIdxBegin, AkUInt32 in_uIdxEnd, AkUInt32 in_uTileSize, AkParallelForFunc in_func, void *in_pUserData, const char *in_szDebugName)
Debug name for the workload.
Definition: AkSoundEngine.h:187
AKRESULT __cdecl SetPosition(AkGameObjectID in_GameObjectID, const AkSoundPosition &in_Position)
void __cdecl MuteBackgroundMusic(bool in_bMute)
AKRESULT __cdecl ClearBanks()
AK::IAkGlobalPluginContext *__cdecl GetGlobalPluginContext()
void __cdecl CancelEventCallbackCookie(void *in_pCookie)
AkUInt32 uMonitorQueuePoolSize
Size of the monitoring queue pool, in bytes. This parameter is not used in Release build.
Definition: AkSoundEngine.h:222
AKRESULT __cdecl RegisterGlobalCallback(AkGlobalCallbackFunc in_pCallback, AkUInt32 in_eLocation=AkGlobalCallbackLocation_BeginRender, void *in_pCookie=NULL, AkPluginType in_eType=AkPluginTypeNone, AkUInt32 in_ulCompanyID=0, AkUInt32 in_ulPluginID=0)
AKRESULT __cdecl RemoveOutput(AkOutputDeviceID in_idOutput)
AKRESULT __cdecl RemoveDefaultListener(AkGameObjectID in_listenerGameObj)
bool bUseSoundBankMgrThread
Use a separate thread for loading sound banks. Allows asynchronous operations.
Definition: AkSoundEngine.h:227
AKRESULT __cdecl DecodeBank(const void *in_pInMemoryBankPtr, AkUInt32 in_uInMemoryBankSize, AkMemPoolId in_uPoolForDecodedBank, void *&out_pDecodedBankPtr, AkUInt32 &out_uDecodedBankSize)
AkUInt32 uMonitorPoolSize
Size of the monitoring pool, in bytes. This parameter is not used in Release build.
Definition: AkSoundEngine.h:221
Simulate one sound coming from multiple directions. Useful for repositionning sounds based on wall op...
Definition: AkTypes.h:739
AKRESULT __cdecl PinEventInStreamCache(AkUniqueID in_eventID, AkPriority in_uActivePriority, AkPriority in_uInactivePriority)