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