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