Table of Contents

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