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

Was this page helpful?

Need Support?

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

Visit our Support page

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

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

Get started with Wwise