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

Was this page helpful?

Need Support?

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

Visit our Support page

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

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

Get started with Wwise