버전

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

이 페이지가 도움이 되었나요?

지원이 필요하신가요?

질문이 있으신가요? 문제를 겪고 계신가요? 더 많은 정보가 필요하신가요? 저희에게 문의해주시면 도와드리겠습니다!

지원 페이지를 방문해 주세요

작업하는 프로젝트에 대해 알려주세요. 언제든지 도와드릴 준비가 되어 있습니다.

프로젝트를 등록하세요. 아무런 조건이나 의무 사항 없이 빠른 시작을 도와드리겠습니다.

Wwise를 시작해 보세요