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