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

Was this page helpful?

Need Support?

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

Visit our Support page

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

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

Get started with Wwise