Table of Contents

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