Version

menu_open

include/AK/SoundEngine/Common/AkSoundEngine.h

Go to the documentation of this file.
00001 /*******************************************************************************
00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
00003 released in source code form as part of the SDK installer package.
00004 
00005 Commercial License Usage
00006 
00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
00008 may use this file in accordance with the end user license agreement provided 
00009 with the software or, alternatively, in accordance with the terms contained in a
00010 written agreement between you and Audiokinetic Inc.
00011 
00012 Apache License Usage
00013 
00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 
00015 "Apache License"); you may not use this file except in compliance with the 
00016 Apache License. You may obtain a copy of the Apache License at 
00017 http://www.apache.org/licenses/LICENSE-2.0.
00018 
00019 Unless required by applicable law or agreed to in writing, software distributed
00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
00022 the specific language governing permissions and limitations under the License.
00023 
00024   Version: <VERSION>  Build: <BUILDNUMBER>
00025   Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
00026 *******************************************************************************/
00027 
00028 // AkSoundEngine.h
00029 
00030 /// \file 
00031 /// The main sound engine interface.
00032 
00033 
00034 #ifndef _AK_SOUNDENGINE_H_
00035 #define _AK_SOUNDENGINE_H_
00036 
00037 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
00038 #include <AK/SoundEngine/Common/AkTypes.h>
00039 #include <AK/SoundEngine/Common/IAkPlugin.h>
00040 #include <AK/SoundEngine/Common/AkCallback.h>
00041 
00042 #ifdef AK_WIN
00043 #include <AK/SoundEngine/Platforms/Windows/AkWinSoundEngine.h>
00044 
00045 #elif defined (AK_MAC_OS_X)
00046 #include <AK/SoundEngine/Platforms/Mac/AkMacSoundEngine.h>
00047 
00048 #elif defined (AK_IOS)
00049 #include <AK/SoundEngine/Platforms/iOS/AkiOSSoundEngine.h>
00050 
00051 #elif defined (AK_XBOXONE)
00052 #include <AK/SoundEngine/Platforms/XboxOne/AkXboxOneSoundEngine.h>
00053 
00054 #elif defined (AK_VITA)
00055 #include <AK/SoundEngine/Platforms/Vita/AkVitaSoundEngine.h>
00056 
00057 #elif defined( AK_ANDROID )
00058 #include <AK/SoundEngine/Platforms/Android/AkAndroidSoundEngine.h>
00059 
00060 #elif defined (AK_PS4)
00061 #include <AK/SoundEngine/Platforms/PS4/AkPS4SoundEngine.h>
00062 
00063 #elif defined( AK_LINUX )
00064 #include <AK/SoundEngine/Platforms/Linux/AkLinuxSoundEngine.h>
00065 
00066 #elif defined( AK_EMSCRIPTEN )
00067 #include <AK/SoundEngine/Platforms/Emscripten/AkEmscriptenSoundEngine.h>
00068 
00069 #elif defined( AK_QNX  )
00070 #include <AK/SoundEngine/Platforms/QNX/AkQNXSoundEngine.h>
00071 
00072 #elif defined( AK_NX )
00073 #include <AK/SoundEngine/Platforms/NX/AkNXSoundEngine.h>
00074 
00075 #else
00076 #error AkSoundEngine.h: Undefined platform
00077 #endif
00078 
00079 #ifndef AK_ASSERT_HOOK
00080     /// Function called on assert handling, optional
00081     /// \sa 
00082     /// - AkInitSettings
00083     AK_CALLBACK( void, AkAssertHook)( 
00084         const char * in_pszExpression,  ///< Expression
00085         const char * in_pszFileName,    ///< File Name
00086         int in_lineNumber               ///< Line Number
00087         );
00088     #define AK_ASSERT_HOOK
00089 #endif
00090 
00091 /// Callback function prototype for User Music notifications
00092 /// It is useful for reacting to user music playback.
00093 ///
00094 /// \sa
00095 /// - \ref AkGlobalCallbackFunc
00096 /// - \ref AudioInterruptionCallbackFunc
00097 /// - \ref AkPlatformInitSettings
00098 /// - \ref background_music_and_dvr
00099 ///
00100 typedef AKRESULT ( * AkBackgroundMusicChangeCallbackFunc )(
00101     bool in_bBackgroundMusicMuted,  ///< Flag indicating whether the busses tagged as "background music" in the project are muted or not.
00102     void* in_pCookie ///< User-provided data, e.g. a user structure.
00103     );
00104 
00105 /// Platform-independent initialization settings of output devices.
00106 struct AkOutputSettings
00107 {
00108     AkPanningRule   ePanningRule;   ///< Rule for 3D panning of signals routed to a stereo bus. In AkPanningRule_Speakers mode, the angle of the front loudspeakers 
00109                                     ///< (uSpeakerAngles[0]) is used. In AkPanningRule_Headphones mode, the speaker angles are superseded with constant power panning
00110                                     ///< between two virtual microphones spaced 180 degrees apart.
00111 
00112     AkChannelConfig channelConfig;  ///< Channel configuration for this output. Call AkChannelConfig::Clear() to let the engine use the default output configuration.  
00113                                     ///< Hardware might not support the selected configuration.
00114 
00115     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.
00116                                     ///< Typically, custom audio devices are used for HRTF spatialization or unusual hardware.  If you want to output to the default system audio output,
00117                                     ///< leave this field to its default value (AK_INVALID_UNIQUE_ID).
00118                                     ///< Typical usage: AkInitSettings.eOutputSettings.audioDeviceShareset = AK::SoundEngine::GetIDFromString("InsertYourAudioDeviceSharesetNameHere");
00119                                     ///< \ref AK::SoundEngine::GetIDFromString()
00120                                     ///< \ref soundengine_plugins_audiodevices
00121 
00122     AkBusHierarchyFlags outputHierarchy; ///< Flags to enable or disable the output of the primary and secondary bus hierarchies for the output device.
00123 };
00124 
00125 /// Platform-independent initialization settings of the sound engine
00126 /// \sa 
00127 /// - AK::SoundEngine::Init()
00128 /// - AK::SoundEngine::GetDefaultInitSettings()
00129 /// - \ref soundengine_integration_init_advanced
00130 /// - \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
00131 struct AkInitSettings
00132 {
00133     AkAssertHook        pfnAssertHook;              ///< External assertion handling function (optional)
00134 
00135     AkUInt32            uMaxNumPaths;               ///< Maximum number of paths for positioning
00136     AkUInt32            uDefaultPoolSize;           ///< Size of the default memory pool, in bytes
00137     AkReal32            fDefaultPoolRatioThreshold; ///< 0.0f to 1.0f value: The percentage of occupied memory where the sound engine should enter in Low memory Mode. \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
00138     AkUInt32            uCommandQueueSize;          ///< Size of the command queue, in bytes
00139     AkMemPoolId         uPrepareEventMemoryPoolID;  ///< Memory pool where data allocated by AK::SoundEngine::PrepareEvent() and AK::SoundEngine::PrepareGameSyncs() will be done. 
00140     bool                bEnableGameSyncPreparation; ///< Set to true to enable AK::SoundEngine::PrepareGameSync usage.
00141     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. 
00142                                                     ///< 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. 
00143 
00144     AkUInt32            uNumSamplesPerFrame;        ///< Number of samples per audio frame (256, 512, 1024, or 2048).
00145 
00146     AkUInt32            uMonitorPoolSize;           ///< Size of the monitoring pool, in bytes. This parameter is not used in Release build.
00147     AkUInt32            uMonitorQueuePoolSize;      ///< Size of the monitoring queue pool, in bytes. This parameter is not used in Release build.
00148     
00149     AkOutputSettings    settingsMainOutput;         ///< Main output device settings.
00150     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)
00151 
00152     bool                bUseSoundBankMgrThread;     ///< Use a separate thread for loading sound banks. Allows asynchronous operations.
00153     bool                bUseLEngineThread;          ///< Use a separate thread for processing audio. If set to false, audio processing will occur in RenderAudio(). Ignored on Vita. \ref goingfurther_eventmgrthread
00154 
00155     AkBackgroundMusicChangeCallbackFunc BGMCallback; ///< Application-defined audio source change event callback function.
00156     void*               BGMCallbackCookie;          ///< Application-defined user data for the audio source change event callback function.
00157     AkOSChar *          szPluginDLLPath;            ///< When using DLLs for plugins, specify their path.  Leave NULL if DLLs are in the same folder as the game executable.
00158 };
00159 
00160 /// Necessary settings for setting externally-loaded sources
00161 struct AkSourceSettings
00162 {
00163     AkUniqueID  sourceID;                           ///< Source ID (available in the SoundBank content files)
00164     AkUInt8*    pMediaMemory;                       ///< Pointer to the data to be set for the source
00165     AkUInt32    uMediaSize;                         ///< Size, in bytes, of the data to be set for the source
00166 };
00167 
00168 /// Configured audio settings
00169 struct AkAudioSettings
00170 {
00171     AkUInt32            uNumSamplesPerFrame;        ///< Number of samples per audio frame (256, 512, 1024 or 2048).
00172     AkUInt32            uNumSamplesPerSecond;       ///< Number of samples per second.
00173 };
00174 
00175 /// Return values for GetSourcePlayPositions.
00176 struct AkSourcePosition
00177 {
00178     AkUniqueID  audioNodeID;                        ///< Audio Node ID of playing item
00179     AkUniqueID  mediaID;                            ///< Media ID of playing item. (corresponds to 'ID' attribute of 'File' element in SoundBank metadata file)
00180     AkTimeMs    msTime;                             ///< Position of the source (in ms) associated with that playing item
00181 };
00182 
00183 /// Audiokinetic namespace
00184 namespace AK
00185 {
00186     class IReadBytes;
00187     class IWriteBytes;
00188 
00189     /// Audiokinetic sound engine namespace
00190     /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
00191     namespace SoundEngine
00192     {
00193         ///////////////////////////////////////////////////////////////////////
00194         /// @name Initialization
00195         //@{
00196 
00197         /// Query whether or not the sound engine has been successfully initialized.
00198         /// \warning This function is not thread-safe. It should not be called at the same time as SoundEngine::Init() or SoundEngine::Term().
00199         /// \return True if the sound engine has been initialized, False otherwise
00200         /// \sa
00201         /// - \ref soundengine_integration_init_advanced
00202         /// - AK::SoundEngine::Init()
00203         /// - AK::SoundEngine::Term()
00204         AK_EXTERNAPIFUNC( bool, IsInitialized )();
00205 
00206         /// Initialize the sound engine.
00207         /// \warning This function is not thread-safe.
00208         /// \remark The initial settings should be initialized using AK::SoundEngine::GetDefaultInitSettings()
00209         ///         and AK::SoundEngine::GetDefaultPlatformInitSettings() to fill the structures with their 
00210         ///         default settings. This is not mandatory, but it helps avoid backward compatibility problems.
00211         ///     
00212         /// \return 
00213         /// - AK_Success if the initialization was successful
00214         /// - AK_MemManagerNotInitialized if the memory manager is not available or not properly initialized
00215         /// - AK_StreamMgrNotInitialized if the stream manager is not available or not properly initialized
00216         /// - AK_SSEInstructionsNotSupported if the machine does not support SSE instruction (only on the PC)
00217         /// - AK_InsufficientMemory or AK_Fail if there is not enough memory available to initialize the sound engine properly
00218         /// - AK_InvalidParameter if some parameters are invalid
00219         /// - AK_Fail if the sound engine is already initialized, or if the provided settings result in insufficient 
00220         /// resources for the initialization.
00221         /// \sa
00222         /// - \ref soundengine_integration_init_advanced
00223         /// - AK::SoundEngine::Term()
00224         /// - AK::SoundEngine::GetDefaultInitSettings()
00225         /// - AK::SoundEngine::GetDefaultPlatformInitSettings()
00226         AK_EXTERNAPIFUNC( AKRESULT, Init )(
00227             AkInitSettings *            in_pSettings,           ///< Initialization settings (can be NULL, to use the default values)
00228             AkPlatformInitSettings *    in_pPlatformSettings    ///< Platform-specific settings (can be NULL, to use the default values)
00229             );
00230 
00231         /// Get the default values of the platform-independent initialization settings.
00232         /// \warning This function is not thread-safe.
00233         /// \sa
00234         /// - \ref soundengine_integration_init_advanced
00235         /// - AK::SoundEngine::Init()
00236         /// - AK::SoundEngine::GetDefaultPlatformInitSettings()
00237         AK_EXTERNAPIFUNC( void, GetDefaultInitSettings )(
00238             AkInitSettings &            out_settings            ///< Returned default platform-independent sound engine settings
00239             );
00240 
00241         /// Get the default values of the platform-specific initialization settings.
00242         ///
00243         /// Windows Specific:
00244         ///     When initializing for Windows platform, the HWND value returned in the 
00245         ///     AkPlatformInitSettings structure is the foreground HWND at the moment of the 
00246         ///     initialization of the sound engine and may not be the correct one for your need.
00247         ///     Each game must specify the HWND that will be passed to DirectSound initialization.
00248         ///     It is required that each game provides the correct HWND to be used or it could cause
00249         ///     one of the following problem:
00250         ///             - Random Sound engine initialization failure.
00251         ///             - Audio focus to be located on the wrong window.
00252         ///
00253         /// \warning This function is not thread-safe.
00254         /// \sa 
00255         /// - \ref soundengine_integration_init_advanced
00256         /// - AK::SoundEngine::Init()
00257         /// - AK::SoundEngine::GetDefaultInitSettings()
00258         AK_EXTERNAPIFUNC( void, GetDefaultPlatformInitSettings )(
00259             AkPlatformInitSettings &    out_platformSettings    ///< Returned default platform-specific sound engine settings
00260             );
00261         
00262         /// Terminate the sound engine.
00263         /// If some sounds are still playing or events are still being processed when this function is 
00264         /// called, they will be stopped.
00265         /// \warning This function is not thread-safe.
00266         /// \warning Before calling Term, you must ensure that no other thread is accessing the sound engine.
00267         /// \sa 
00268         /// - \ref soundengine_integration_init_advanced
00269         /// - AK::SoundEngine::Init()
00270         AK_EXTERNAPIFUNC( void, Term )();
00271 
00272         /// Get the configured audio settings.
00273         /// Call this function to get the configured audio settings.
00274         /// 
00275         /// \warning This function is not thread-safe.
00276         /// \warning Call this function only after the sound engine has been properly initialized.
00277         AK_EXTERNAPIFUNC( AKRESULT, GetAudioSettings )(
00278             AkAudioSettings &   out_audioSettings   ///< Returned audio settings
00279             );
00280 
00281         /// Get the output speaker configuration of the specified output.
00282         /// Call this function to get the speaker configuration of the output (which may not correspond
00283         /// to the physical output format of the platform, in the case of downmixing provided by the platform itself). 
00284         /// You may initialize the sound engine with a user-specified configuration, but the resulting 
00285         /// configuration is determined by the sound engine, based on the platform, output type and
00286         /// platform settings (for e.g. system menu or control panel option). 
00287         /// 
00288         /// \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.
00289         /// \return The output configuration. An empty AkChannelConfig (!AkChannelConfig::IsValid()) if device does not exist.
00290         /// \sa 
00291         /// - AkSpeakerConfig.h
00292         /// - AkOutputSettings
00293         AK_EXTERNAPIFUNC( AkChannelConfig, GetSpeakerConfiguration )(
00294             AkAudioOutputType   in_eOutputType = AkOutput_Main, ///< Output sink type. Pass AkOutput_Main for main output.
00295             AkUInt32            in_iOutputID = 0            ///< Player number or device-unique identifier. Pass 0 for main.
00296             );
00297 
00298         /// Get the panning rule of the specified output.
00299         /// \warning Call this function only after the sound engine has been properly initialized.
00300         /// \return One of the supported configuration: 
00301         /// - AkPanningRule_Speakers
00302         /// - AkPanningRule_Headphone
00303         /// \sa 
00304         /// - AkSpeakerConfig.h
00305         AK_EXTERNAPIFUNC( AKRESULT, GetPanningRule )(
00306             AkPanningRule &     out_ePanningRule,           ///< Returned panning rule (AkPanningRule_Speakers or AkPanningRule_Headphone) for given output.
00307             AkAudioOutputType   in_eOutputType = AkOutput_Main, ///< Output sink type. Pass AkOutput_Main for main output.
00308             AkUInt32            in_iOutputID = 0            ///< Player number or device-unique identifier. Pass 0 for main.
00309             );
00310 
00311         /// Set the panning rule of the specified output.
00312         /// This may be changed anytime once the sound engine is initialized.
00313         /// \warning This function posts a message through the sound engine's internal message queue, whereas GetPanningRule() queries the current panning rule directly.
00314         AK_EXTERNAPIFUNC( AKRESULT, SetPanningRule )( 
00315             AkPanningRule       in_ePanningRule,            ///< Panning rule.
00316             AkAudioOutputType   in_eOutputType = AkOutput_Main, ///< Output sink type. Pass AkOutput_Main for main output.
00317             AkUInt32            in_iOutputID = 0            ///< Player number or device-unique identifier. Pass 0 for main.
00318             );
00319 
00320         /// Get speaker angles of the specified device. Speaker angles are used for 3D positioning of sounds over standard configurations.
00321         /// Note that the current version of Wwise only supports positioning on the plane.
00322         /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180].
00323         /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles.
00324         /// Angles must be set in ascending order. 
00325         /// You may call this function with io_pfSpeakerAngles set to NULL to get the expected number of angle values in io_uNumAngles, 
00326         /// in order to allocate your array correctly. You may also obtain this number by calling
00327         /// AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ).
00328         /// If io_pfSpeakerAngles is not NULL, the array is filled with up to io_uNumAngles.
00329         /// Typical usage:
00330         /// - AkUInt32 uNumAngles;
00331         /// - GetSpeakerAngles( NULL, uNumAngles, AkOutput_Main );
00332         /// - AkReal32 * pfSpeakerAngles = AkAlloca( uNumAngles * sizeof(AkReal32) );
00333         /// - GetSpeakerAngles( pfSpeakerAngles, uNumAngles, AkOutput_Main );
00334         /// \aknote 
00335         /// On most platforms, the angle set on the plane consists of 3 angles, to account for 7.1. 
00336         /// - When panning to stereo (speaker mode, see AK::SoundEngine::SetPanningRule()), only angle[0] is used, and 3D sounds in the back of the listener are mirrored to the front. 
00337         /// - When panning to 5.1, the front speakers use angle[0], and the surround speakers use (angle[2] - angle[1]) / 2.
00338         /// \endaknote
00339         /// \warning Call this function only after the sound engine has been properly initialized.
00340         /// \return AK_Success if device exists.
00341         /// \sa SetSpeakerAngles()
00342         AK_EXTERNAPIFUNC( AKRESULT, GetSpeakerAngles )(
00343             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.
00344             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.
00345             AkReal32 &          out_fHeightAngle,           ///< Elevation of the height layer, in degrees relative to the plane [-90,90].
00346             AkAudioOutputType   in_eOutputType = AkOutput_Main, ///< Output sink type. Pass AkOutput_Main for main output.
00347             AkUInt32            in_iOutputID = 0            ///< Player number or device-unique identifier. Pass 0 for main.
00348             );
00349         
00350         /// Set speaker angles of the specified device. Speaker angles are used for 3D positioning of sounds over standard configurations.
00351         /// Note that the current version of Wwise only supports positioning on the plane.
00352         /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180].
00353         /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles.
00354         /// Angles must be set in ascending order. 
00355         /// Typical usage: 
00356         /// - Initialize the sound engine and/or add secondary output(s).
00357         /// - Get number of speaker angles and their value into an array using GetSpeakerAngles().
00358         /// - Modify the angles and call SetSpeakerAngles().
00359         /// 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().
00360         /// \warning This function only applies to configurations (or subset of these configurations) that are standard and whose speakers are on the plane (2D).
00361         /// \return AK_NotCompatible if the channel configuration of the device is not standard (AK_ChannelConfigType_Standard), 
00362         /// AK_Success if successful (device exists and angles are valid), AK_Fail otherwise.
00363         /// \sa GetSpeakerAngles()
00364         AK_EXTERNAPIFUNC( AKRESULT, SetSpeakerAngles )(
00365             AkReal32 *          in_pfSpeakerAngles,         ///< Array of loudspeaker pair angles, in degrees relative to azimuth [0,180].
00366             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()).
00367             AkReal32            in_fHeightAngle,            ///< Elevation of the height layer, in degrees relative to the plane  [-90,90].
00368             AkAudioOutputType   in_eOutputType = AkOutput_Main, ///< Output sink type. Pass AkOutput_Main for main output.
00369             AkUInt32            in_iOutputID = 0            ///< Player number or device-unique identifier. Pass 0 for main.
00370             );
00371 
00372         /// Allows the game to set the volume threshold to be used by the sound engine to determine if a voice must go virtual.
00373         /// This may be changed anytime once the sound engine was initialized.
00374         /// If this function is not called, the used value will be the value specified in the platform specific project settings.
00375         /// \return 
00376         /// - AK_InvalidParameter if the threshold was not between 0 and -96.3 dB.
00377         /// - AK_Success if successful
00378         AK_EXTERNAPIFUNC( AKRESULT, SetVolumeThreshold )( 
00379             AkReal32 in_fVolumeThresholdDB ///< Volume Threshold, must be a value between 0 and -96.3 dB
00380             );
00381 
00382         /// Allows the game to set the maximum number of non virtual voices to be played simultaneously.
00383         /// This may be changed anytime once the sound engine was initialized.
00384         /// If this function is not called, the used value will be the value specified in the platform specific project settings.
00385         /// \return 
00386         /// - AK_InvalidParameter if the threshold was not between 1 and MaxUInt16.
00387         /// - AK_Success if successful
00388         AK_EXTERNAPIFUNC( AKRESULT, SetMaxNumVoicesLimit )( 
00389             AkUInt16 in_maxNumberVoices ///< Maximum number of non-virtual voices.
00390             );
00391                 
00392         //@}
00393 
00394         ////////////////////////////////////////////////////////////////////////
00395         /// @name Rendering Audio
00396         //@{
00397 
00398         /// Process all commands in the sound engine's command queue.
00399         /// This method has to be called periodically (usually once per game frame).
00400         /// \sa 
00401         /// - \ref concept_events
00402         /// - \ref soundengine_events
00403         /// - AK::SoundEngine::PostEvent()
00404         /// \return Always returns AK_Success
00405         AK_EXTERNAPIFUNC( AKRESULT, RenderAudio )( 
00406             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.
00407             );
00408 
00409         //@}
00410 
00411         ////////////////////////////////////////////////////////////////////////
00412         /// @name Component Registration
00413         //@{
00414 
00415         /// Query interface to global plugin context used for plugin registration/initialization.
00416         /// \return Global plugin context.
00417         AK_EXTERNAPIFUNC(AK::IAkGlobalPluginContext *, GetGlobalPluginContext)();
00418 
00419         /// Register a plug-in with the sound engine and set the callback functions to create the 
00420         /// plug-in and its parameter node.  
00421         /// \aknote 
00422         /// This function is deprecated.  Registration is now automatic if you link plugins statically. If plug-ins are dynamic libraries (such as DLLs or SOs), use RegisterPluginDLL.
00423         /// \endaknote
00424         /// \sa
00425         /// - \ref register_effects
00426         /// - \ref plugin_xml
00427         /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided or Ak_Fail otherwise. Possible reasons for an AK_Fail result are:
00428         /// - Insufficient memory to register the plug-in
00429         /// - Plug-in ID already registered
00430         /// \remarks
00431         /// Codecs and plug-ins must be registered before loading banks that use them.\n
00432         /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
00433         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
00434         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
00435         /// posting the event will fail.
00436         AK_EXTERNAPIFUNC( AKRESULT, RegisterPlugin )( 
00437             AkPluginType in_eType,                      ///< Plug-in type (for example, source or effect)
00438             AkUInt32 in_ulCompanyID,                    ///< Company identifier (as declared in the plug-in description XML file)
00439             AkUInt32 in_ulPluginID,                     ///< Plug-in identifier (as declared in the plug-in description XML file)
00440             AkCreatePluginCallback in_pCreateFunc,      ///< Pointer to the plug-in's creation function
00441             AkCreateParamCallback in_pCreateParamFunc   ///< Pointer to the plug-in's parameter node creation function
00442             );
00443 
00444         /// Loads a plugin dynamic library and registers it with the sound engine.  
00445         /// With dynamic linking, all plugins are automatically registered.
00446         /// The plugin DLL must be in the OS-specific library path or in the same location as the executable. If not, set AkInitSettings.szPluginDLLPath.
00447         /// \return 
00448         /// - Ak_Success if successful.  
00449         /// - AK_FileNotFound if the DLL is not found in the OS path or if it has extraneous dependencies not found.  
00450         /// - AK_InvalidFile if the symbol g_pAKPluginList is not exported by the dynamic library
00451         AK_EXTERNAPIFUNC( AKRESULT, RegisterPluginDLL ) (
00452             const AkOSChar* in_DllName                  ///< Name of the DLL to load, without "lib" prefix or extension.  
00453             );
00454         
00455         /// Register a codec type with the sound engine and set the callback functions to create the 
00456         /// codec's file source and bank source nodes.
00457         /// \aknote 
00458         /// 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.
00459         /// \endaknote      
00460         /// \sa 
00461         /// - \ref register_effects
00462         /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided, or Ak_Fail otherwise. Possible reasons for an AK_Fail result are:
00463         /// - Insufficient memory to register the codec
00464         /// - Codec ID already registered
00465         /// \remarks
00466         /// Codecs and plug-ins must be registered before loading banks that use them.\n
00467         /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
00468         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
00469         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
00470         /// posting the event will fail.
00471         AK_EXTERNAPIFUNC( AKRESULT, RegisterCodec )( 
00472             AkUInt32 in_ulCompanyID,                        ///< Company identifier (as declared in the plug-in description XML file)
00473             AkUInt32 in_ulCodecID,                          ///< Codec identifier (as declared in the plug-in description XML file)
00474             AkCreateFileSourceCallback in_pFileCreateFunc,  ///< Pointer to the codec's file source node creation function
00475             AkCreateBankSourceCallback in_pBankCreateFunc   ///< Pointer to the codec's bank source node creation function
00476             );
00477 
00478         /// Register a global callback function. This function will be called from the audio rendering thread, at the
00479         /// location specified by in_eLocation. This function will also be called from the thread calling           
00480         /// AK::SoundEngine::Term with in_eLocation set to AkGlobalCallbackLocation_Term.
00481         /// For example, in order to be called at every audio rendering pass, and once during teardown for releasing resources, you would call 
00482         /// RegisterGlobalCallback(myCallback, AkGlobalCallbackLocation_BeginRender | AkGlobalCallbackLocation_Term, myCookie);  
00483         /// \remarks
00484         /// It is illegal to call this function while already inside of a global callback.
00485         /// This function might stall for several milliseconds before returning.
00486         /// \sa 
00487         /// - AK::SoundEngine::UnregisterGlobalCallback()
00488         /// - AkGlobalCallbackFunc
00489         /// - AkGlobalCallbackLocation
00490         AK_EXTERNAPIFUNC(AKRESULT, RegisterGlobalCallback)(
00491             AkGlobalCallbackFunc in_pCallback,              ///< Function to register as a global callback.
00492             AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender, ///< Callback location defined in AkGlobalCallbackLocation. Bitwise OR multiple locations if needed.
00493             void * in_pCookie = NULL                        ///< User cookie.
00494             );
00495 
00496         /// Unregister a global callback function, previously registered using RegisterGlobalCallback.
00497         /// \remarks
00498         /// It is legal to call this function while already inside of a global callback, If it is unregistering itself and not
00499         /// another callback.
00500         /// This function might stall for several milliseconds before returning.
00501         /// \sa 
00502         /// - AK::SoundEngine::RegisterGlobalCallback()
00503         /// - AkGlobalCallbackFunc
00504         /// - AkGlobalCallbackLocation
00505         AK_EXTERNAPIFUNC(AKRESULT, UnregisterGlobalCallback)(
00506             AkGlobalCallbackFunc in_pCallback,              ///< Function to unregister as a global callback.
00507             AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender ///< Must match in_eLocation as passed to RegisterGlobalCallback for this callback.
00508             );
00509 
00510         //@}
00511 
00512 #ifdef AK_SUPPORT_WCHAR
00513         ////////////////////////////////////////////////////////////////////////
00514         /// @name Getting ID from strings
00515         //@{
00516 
00517         /// Universal converter from Unicode string to ID for the sound engine.
00518         /// This function will hash the name based on a algorithm ( provided at : /AK/Tools/Common/AkFNVHash.h )
00519         /// Note:
00520         ///     This function does return a AkUInt32, which is totally compatible with:
00521         ///     AkUniqueID, AkStateGroupID, AkStateID, AkSwitchGroupID, AkSwitchStateID, AkRtpcID, and so on...
00522         /// \sa
00523         /// - AK::SoundEngine::PostEvent
00524         /// - AK::SoundEngine::SetRTPCValue
00525         /// - AK::SoundEngine::SetSwitch
00526         /// - AK::SoundEngine::SetState
00527         /// - AK::SoundEngine::PostTrigger
00528         /// - AK::SoundEngine::SetGameObjectAuxSendValues
00529         /// - AK::SoundEngine::LoadBank
00530         /// - AK::SoundEngine::UnloadBank
00531         /// - AK::SoundEngine::PrepareEvent
00532         /// - AK::SoundEngine::PrepareGameSyncs
00533         AK_EXTERNAPIFUNC( AkUInt32, GetIDFromString )( const wchar_t* in_pszString );
00534 #endif //AK_SUPPORT_WCHAR
00535 
00536         /// Universal converter from string to ID for the sound engine.
00537         /// This function will hash the name based on a algorithm ( provided at : /AK/Tools/Common/AkFNVHash.h )
00538         /// Note:
00539         ///     This function does return a AkUInt32, which is totally compatible with:
00540         ///     AkUniqueID, AkStateGroupID, AkStateID, AkSwitchGroupID, AkSwitchStateID, AkRtpcID, and so on...
00541         /// \sa
00542         /// - AK::SoundEngine::PostEvent
00543         /// - AK::SoundEngine::SetRTPCValue
00544         /// - AK::SoundEngine::SetSwitch
00545         /// - AK::SoundEngine::SetState
00546         /// - AK::SoundEngine::PostTrigger
00547         /// - AK::SoundEngine::SetGameObjectAuxSendValues
00548         /// - AK::SoundEngine::LoadBank
00549         /// - AK::SoundEngine::UnloadBank
00550         /// - AK::SoundEngine::PrepareEvent
00551         /// - AK::SoundEngine::PrepareGameSyncs
00552         AK_EXTERNAPIFUNC( AkUInt32, GetIDFromString )( const char* in_pszString );
00553 
00554         //@}
00555 
00556         ////////////////////////////////////////////////////////////////////////
00557         /// @name Event Management
00558         //@{
00559 
00560         /// Asynchronously post an event to the sound engine (by event ID).
00561         /// The callback function can be used to be noticed when markers are reached or when the event is finished.
00562         /// An array of wave file sources can be provided to resolve External Sources triggered by the event. 
00563         /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed
00564         /// \remarks
00565         /// If used, the array of external sources should contain the information for each external source triggered by the
00566         /// event.  When triggering an event with multiple external sources, you need to differentiate each source 
00567         /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
00568         /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project 
00569         /// (therefore have a unique cookie) in order to tell them apart when filling the AkExternalSourceInfo structures.
00570         /// \endaknote
00571         /// \sa 
00572         /// - \ref concept_events
00573         /// - \ref integrating_external_sources
00574         /// - AK::SoundEngine::RenderAudio()
00575         /// - AK::SoundEngine::GetIDFromString()
00576         /// - AK::SoundEngine::GetSourcePlayPosition()
00577         AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
00578             AkUniqueID in_eventID,                          ///< Unique ID of the event
00579             AkGameObjectID in_gameObjectID,                 ///< Associated game object ID
00580             AkUInt32 in_uFlags = 0,                         ///< Bitmask: see \ref AkCallbackType
00581             AkCallbackFunc in_pfnCallback = NULL,           ///< Callback function
00582             void * in_pCookie = NULL,                       ///< Callback cookie that will be sent to the callback function along with additional information
00583             AkUInt32 in_cExternals = 0,                     ///< Optional count of external source structures
00584             AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
00585             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.
00586             );
00587 
00588 #ifdef AK_SUPPORT_WCHAR
00589         /// Post an event to the sound engine (by event name), using callbacks.
00590         /// The callback function can be used to be noticed when markers are reached or when the event is finished.
00591         /// An array of wave file sources can be provided to resolve External Sources triggered by the event. 
00592         /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed
00593         /// \remarks
00594         /// If used, the array of external sources should contain the information for each external source triggered by the
00595         /// event.  When triggering an event with multiple external sources, you need to differentiate each source 
00596         /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
00597         /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project 
00598         /// (therefore have a unique cookie) in order to tell them appart when filling the AkExternalSourceInfo structures.
00599         /// \endaknote
00600         /// \sa 
00601         /// - \ref concept_events
00602         /// - \ref integrating_external_sources
00603         /// - AK::SoundEngine::RenderAudio()
00604         /// - AK::SoundEngine::GetIDFromString()
00605         /// - AK::SoundEngine::GetSourcePlayPosition()
00606         AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
00607             const wchar_t* in_pszEventName,                 ///< Name of the event
00608             AkGameObjectID in_gameObjectID,                 ///< Associated game object ID
00609             AkUInt32 in_uFlags = 0,                         ///< Bitmask: see \ref AkCallbackType
00610             AkCallbackFunc in_pfnCallback = NULL,           ///< Callback function
00611             void * in_pCookie = NULL,                       ///< Callback cookie that will be sent to the callback function along with additional information.
00612             AkUInt32 in_cExternals = 0,                     ///< Optional count of external source structures
00613             AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
00614             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.
00615             );
00616 #endif //AK_SUPPORT_WCHAR
00617 
00618         /// Post an event to the sound engine (by event name), using callbacks.
00619         /// The callback function can be used to be noticed when markers are reached or when the event is finished.
00620         /// An array of wave file sources can be provided to resolve External Sources triggered by the event.  P
00621         /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed
00622         /// \remarks
00623         /// If used, the array of external sources should contain the information for each external source triggered by the
00624         /// event.  When triggering an event with multiple external sources, you need to differentiate each source 
00625         /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
00626         /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project 
00627         /// (therefore have a unique cookie) in order to tell them appart when filling the AkExternalSourceInfo structures.
00628         /// \endaknote
00629         /// \sa 
00630         /// - \ref concept_events
00631         /// - \ref integrating_external_sources
00632         /// - AK::SoundEngine::RenderAudio()
00633         /// - AK::SoundEngine::GetIDFromString()
00634         /// - AK::SoundEngine::GetSourcePlayPosition()
00635         AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
00636             const char* in_pszEventName,                    ///< Name of the event
00637             AkGameObjectID in_gameObjectID,                 ///< Associated game object ID
00638             AkUInt32 in_uFlags = 0,                         ///< Bitmask: see \ref AkCallbackType
00639             AkCallbackFunc in_pfnCallback = NULL,           ///< Callback function
00640             void * in_pCookie = NULL,                       ///< Callback cookie that will be sent to the callback function along with additional information.
00641             AkUInt32 in_cExternals = 0,                     ///< Optional count of external source structures
00642             AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
00643             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.
00644             );
00645 
00646         // If you modify AkActionOnEventType, don't forget to modify WAAPI validation schema accordingly.
00647 
00648         /// AkActionOnEventType
00649         /// \sa
00650         /// - AK::SoundEngine::ExecuteActionOnEvent()
00651         enum AkActionOnEventType
00652         {
00653             AkActionOnEventType_Stop    = 0,            ///< Stop
00654             AkActionOnEventType_Pause   = 1,            ///< Pause
00655             AkActionOnEventType_Resume  = 2,            ///< Resume
00656             AkActionOnEventType_Break   = 3,            ///< Break
00657             AkActionOnEventType_ReleaseEnvelope = 4     ///< Release envelope
00658         };
00659 
00660         /// Executes an action on all nodes that are referenced in the specified event in an action of type play.
00661         /// \sa
00662         /// - AK::SoundEngine::AkActionOnEventType
00663         AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
00664             AkUniqueID in_eventID,                                              ///< Unique ID of the event
00665             AkActionOnEventType in_ActionType,                                  ///< Action to execute on all the elements that were played using the specified event.
00666             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,            ///< Associated game object ID
00667             AkTimeMs in_uTransitionDuration = 0,                                ///< Fade duration
00668             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the transition
00669             AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID                    ///< Associated PlayingID
00670             );
00671 
00672 #ifdef AK_SUPPORT_WCHAR
00673         /// Executes an action on all nodes that are referenced in the specified event in an action of type play.
00674         /// \sa
00675         /// - AK::SoundEngine::AkActionOnEventType
00676         AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
00677             const wchar_t* in_pszEventName,                                     ///< Name of the event
00678             AkActionOnEventType in_ActionType,                                  ///< Action to execute on all the elements that were played using the specified event.
00679             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,            ///< Associated game object ID
00680             AkTimeMs in_uTransitionDuration = 0,                                ///< Fade duration
00681             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the transition
00682             AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID                    ///< Associated PlayingID
00683             );
00684 #endif //AK_SUPPORT_WCHAR
00685 
00686         /// Executes an action on all nodes that are referenced in the specified event in an action of type play.
00687         /// \sa
00688         /// - AK::SoundEngine::AkActionOnEventType
00689         AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
00690             const char* in_pszEventName,                                        ///< Name of the event
00691             AkActionOnEventType in_ActionType,                                  ///< Action to execute on all the elements that were played using the specified event.
00692             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,            ///< Associated game object ID
00693             AkTimeMs in_uTransitionDuration = 0,                                ///< Fade duration
00694             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the transition
00695             AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID                    ///< Associated PlayingID
00696             );
00697 
00698 
00699         /// Executes a number of MIDI events on all nodes that are referenced in the specified event in an action of type play.
00700         /// Each MIDI event will be posted in AkMIDIPost::uOffset samples from the start of the current frame.  The duration of
00701         /// a sample can be determined from the sound engine's audio settings, via a call to AK::SoundEngine::GetAudioSettings.
00702         /// \sa
00703         /// - AK::SoundEngine::GetAudioSettings
00704         /// - AK::SoundEngine::StopMIDIOnEvent
00705         AK_EXTERNAPIFUNC( AKRESULT, PostMIDIOnEvent )(
00706             AkUniqueID in_eventID,                                          ///< Unique ID of the event
00707             AkGameObjectID in_gameObjectID,                                 ///< Associated game object ID
00708             AkMIDIPost* in_pPosts,                                          ///< MIDI events to post
00709             AkUInt16 in_uNumPosts                                           ///< Number of MIDI events to post
00710             );
00711 
00712         /// Stops MIDI notes on all nodes that are referenced in the specified event in an action of type play,
00713         /// with the specified Game Object.  Invalid parameters are interpreted as wildcards.  For example, calling
00714         /// this function with in_eventID set to AK_INVALID_UNIQUE_ID will stop all MIDI notes for Game Object
00715         /// in_gameObjectID.
00716         /// \sa
00717         /// - AK::SoundEngine::PostMIDIOnEvent
00718         AK_EXTERNAPIFUNC( AKRESULT, StopMIDIOnEvent )(
00719             AkUniqueID in_eventID = AK_INVALID_UNIQUE_ID,                   ///< Unique ID of the event
00720             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT         ///< Associated game object ID
00721             );
00722 
00723 
00724         /// Start 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 
00725         /// 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 
00726         /// uMaxCachePinnedBytes is exceeded.  
00727         /// \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.  
00728         /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO.  For more information see AK::StreamMgr::IAkFileLocationResolver::Open() and AkFileSystemFlags.
00729         /// \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 
00730         /// 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.
00731         /// \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
00732         /// will get cached with active priority, while all other files will get cached with inactive priority.
00733         /// \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
00734         /// 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.
00735         /// \sa
00736         /// - AK::SoundEngine::GetBufferStatusForPinnedEvent
00737         /// - AK::SoundEngine::UnpinEventInStreamCache
00738         /// - AK::StreamMgr::IAkFileLocationResolver::Open
00739         /// - AkFileSystemFlags
00740         AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
00741             AkUniqueID in_eventID,                                          ///< Unique ID of the event
00742             AkPriority in_uActivePriority,                                  ///< Priority of active stream caching I/O
00743             AkPriority in_uInactivePriority                                 ///< Priority of inactive stream caching I/O
00744             );
00745 
00746 #ifdef AK_SUPPORT_WCHAR
00747         /// Start 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 
00748         /// 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 
00749         /// uMaxCachePinnedBytes is exceeded.  
00750         /// \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.  
00751         /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO.  For more information see AK::StreamMgr::IAkFileLocationResolver::Open() and AkFileSystemFlags.
00752         /// \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 
00753         /// 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.
00754         /// \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
00755         /// will get cached with active priority, while all other files will get cached with inactive priority.
00756         /// \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
00757         /// 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.
00758         /// \sa
00759         /// - AK::SoundEngine::GetBufferStatusForPinnedEvent
00760         /// - AK::SoundEngine::UnpinEventInStreamCache
00761         /// - AK::StreamMgr::IAkFileLocationResolver::Open
00762         /// - AkFileSystemFlags
00763         AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
00764             const wchar_t* in_pszEventName,                                 ///< Name of the event
00765             AkPriority in_uActivePriority,                                  ///< Priority of active stream caching I/O
00766             AkPriority in_uInactivePriority                                 ///< Priority of inactive stream caching I/O
00767             );
00768 #endif //AK_SUPPORT_WCHAR
00769 
00770         /// Start 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 
00771         /// 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 
00772         /// uMaxCachePinnedBytes is exceeded.  
00773         /// \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.  
00774         /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO.  For more information see AK::StreamMgr::IAkFileLocationResolver::Open() and AkFileSystemFlags.
00775         /// \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 
00776         /// 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.
00777         /// \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
00778         /// will get cached with active priority, while all other files will get cached with inactive priority.
00779         /// \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
00780         /// 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.
00781         /// \sa
00782         /// - AK::SoundEngine::GetBufferStatusForPinnedEvent
00783         /// - AK::SoundEngine::UnpinEventInStreamCache
00784         /// - AK::StreamMgr::IAkFileLocationResolver::Open
00785         /// - AkFileSystemFlags
00786         AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
00787             const char* in_pszEventName,                                    ///< Name of the event
00788             AkPriority in_uActivePriority,                                  ///< Priority of active stream caching I/O
00789             AkPriority in_uInactivePriority                                 ///< Priority of inactive stream caching I/O
00790             );
00791 
00792         /// Release the set of files that were previously requested to be pinned into cache via AK::SoundEngine::PinEventInStreamCache().  The file may still remain in stream cache
00793         /// after AK::SoundEngine::UnpinEventInStreamCache() is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
00794         /// \sa
00795         /// - AK::SoundEngine::PinEventInStreamCache
00796         /// - AK::SoundEngine::GetBufferStatusForPinnedEvent
00797         AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
00798             AkUniqueID in_eventID                                           ///< Unique ID of the event
00799             );  
00800 
00801 #ifdef AK_SUPPORT_WCHAR
00802         /// Release the set of files that were previously requested to be pinned into cache via AK::SoundEngine::PinEventInStreamCache().  The file may still remain in stream cache
00803         /// after AK::SoundEngine::UnpinEventInStreamCache() is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
00804         /// \sa
00805         /// - AK::SoundEngine::PinEventInStreamCache
00806         /// - AK::SoundEngine::GetBufferStatusForPinnedEvent
00807         AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
00808             const wchar_t* in_pszEventName                                  ///< Name of the event
00809             );
00810 #endif //AK_SUPPORT_WCHAR
00811 
00812         /// Release the set of files that were previously requested to be pinned into cache via AK::SoundEngine::PinEventInStreamCache().  The file may still remain in stream cache
00813         /// after AK::SoundEngine::UnpinEventInStreamCache() is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
00814         /// \sa
00815         /// - AK::SoundEngine::PinEventInStreamCache
00816         /// - AK::SoundEngine::GetBufferStatusForPinnedEvent
00817         AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
00818             const char* in_pszEventName                                     ///< Name of the event
00819             );
00820 
00821         /// Return information about an event that was requested to be pinned into cache via AK::SoundEngine::PinEventInStreamCache().
00822         /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether 
00823         /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
00824         /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see AkDeviceSettings 
00825         /// \sa
00826         /// - AK::SoundEngine::PinEventInStreamCache
00827         /// - AK::SoundEngine::UnpinEventInStreamCache
00828         /// - AkDeviceSettings
00829         AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
00830             AkUniqueID in_eventID,                                          ///< Unique ID of the event
00831             AkReal32& out_fPercentBuffered,                                 ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
00832             bool& out_bCachePinnedMemoryFull                                ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
00833             );
00834 
00835         /// Return information about an event that was requested to be pinned into cache via AK::SoundEngine::PinEventInStreamCache().
00836         /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether 
00837         /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
00838         /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see AkDeviceSettings 
00839         /// \sa
00840         /// - AK::SoundEngine::PinEventInStreamCache
00841         /// - AK::SoundEngine::UnpinEventInStreamCache
00842         /// - AkDeviceSettings
00843         AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
00844             const char* in_pszEventName,                                    ///< Name of the event
00845             AkReal32& out_fPercentBuffered,                                 ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
00846             bool& out_bCachePinnedMemoryFull                                ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
00847             );
00848 
00849 #ifdef AK_SUPPORT_WCHAR
00850         /// Return information about an event that was requested to be pinned into cache via AK::SoundEngine::PinEventInStreamCache().
00851         /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether 
00852         /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
00853         /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see AkDeviceSettings 
00854         /// \sa
00855         /// - AK::SoundEngine::PinEventInStreamCache
00856         /// - AK::SoundEngine::UnpinEventInStreamCache
00857         /// - AkDeviceSettings
00858         AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
00859             const wchar_t* in_pszEventName,                                 ///< Name of the event
00860             AkReal32& out_fPercentBuffered,                                 ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
00861             bool& out_bCachePinnedMemoryFull                                ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
00862             );
00863 #endif
00864 
00865         /// Seek inside all playing objects that are referenced in play actions of the specified event.
00866         ///
00867         /// Notes:
00868         ///     - This works with all objects of the actor-mixer hierarchy, and also with music segments and music switch containers. 
00869         ///     - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored 
00870         ///         if one of their ancestors is a continuous (random or sequence) container with crossfade or 
00871         ///         trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
00872         ///         the sound that is currently playing is the first sound of the sequence.
00873         ///     - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior. 
00874         ///     - Sounds/segments are stopped if in_iPosition is greater than their duration.
00875         ///     - in_iPosition is clamped internally to the beginning of the sound/segment.
00876         ///     - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
00877         ///         With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
00878         ///         Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the 
00879         ///         conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
00880         ///         to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
00881         ///         seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
00882         ///     - This method posts a command in the sound engine queue, thus seeking will not occur before 
00883         ///         the audio thread consumes it (after a call to RenderAudio()). 
00884         ///
00885         /// Notes specific to music segments:
00886         ///     - With music segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
00887         ///         value to seek within the Pre-Entry.
00888         ///     - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification 
00889         ///         in order to restart them if required.
00890         ///     - In order to restart at the correct location, with all their tracks synchronized, music segments 
00891         ///         take the "look-ahead time" property of their streamed tracks into account for seeking. 
00892         ///         Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the 
00893         ///         value that was passed to the method. Use AK::MusicEngine::GetPlayingSegmentInfo() to query 
00894         ///         the exact position of a segment. Also, the segment will be silent during that time
00895         ///         (so that it restarts precisely at the position that you specified). AK::MusicEngine::GetPlayingSegmentInfo() 
00896         ///         also informs you about the remaining look-ahead time.  
00897         ///
00898         /// Notes specific to music switch containers:
00899         ///     - Seeking triggers a music transition towards the current (or target) segment.
00900         ///         This transition is subject to the container's transition rule that matches the current and defined in the container,
00901         ///         so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position 
00902         ///         in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
00903         ///     - If the specified time is greater than the destination segment's length, the modulo is taken.
00904         ///
00905         /// \sa
00906         /// - AK::SoundEngine::RenderAudio()
00907         /// - AK::SoundEngine::PostEvent()
00908         /// - AK::SoundEngine::GetSourcePlayPosition()
00909         /// - AK::MusicEngine::GetPlayingSegmentInfo()
00910         AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )( 
00911             AkUniqueID in_eventID,                                      ///< Unique ID of the event
00912             AkGameObjectID in_gameObjectID,                             ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
00913             AkTimeMs in_iPosition,                                      ///< Desired position where playback should restart, in milliseconds
00914             bool in_bSeekToNearestMarker = false,                       ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
00915             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.
00916             );
00917 
00918 #ifdef AK_SUPPORT_WCHAR
00919         /// Seek inside all playing objects that are referenced in play actions of the specified event.
00920         ///
00921         /// Notes:
00922         ///     - This works with all objects of the actor-mixer hierarchy, and also with music segments and music switch containers. 
00923         ///     - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored 
00924         ///         if one of their ancestors is a continuous (random or sequence) container with crossfade or 
00925         ///         trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
00926         ///         the sound that is currently playing is the first sound of the sequence.
00927         ///     - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior. 
00928         ///     - With music segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
00929         ///         value to seek within the Pre-Entry.
00930         ///     - Sounds/segments are stopped if in_iPosition is greater than their duration.
00931         ///     - in_iPosition is clamped internally to the beginning of the sound/segment.
00932         ///     - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
00933         ///         With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
00934         ///         Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the 
00935         ///         conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
00936         ///         to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
00937         ///         seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
00938         ///     - This method posts a command in the sound engine queue, thus seeking will not occur before 
00939         ///         the audio thread consumes it (after a call to RenderAudio()). 
00940         ///
00941         /// Notes specific to music segments:
00942         ///     - With music segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
00943         ///         value to seek within the Pre-Entry.
00944         ///     - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification 
00945         ///         in order to restart them if required.
00946         ///     - In order to restart at the correct location, with all their tracks synchronized, music segments 
00947         ///         take the "look-ahead time" property of their streamed tracks into account for seeking. 
00948         ///         Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the 
00949         ///         value that was passed to the method. Use AK::MusicEngine::GetPlayingSegmentInfo() to query 
00950         ///         the exact position of a segment. Also, the segment will be silent during that time
00951         ///         (so that it restarts precisely at the position that you specified). AK::MusicEngine::GetPlayingSegmentInfo() 
00952         ///         also informs you about the remaining look-ahead time. 
00953         ///
00954         /// Notes specific to music switch containers:
00955         ///     - Seeking triggers a music transition towards the current (or target) segment.
00956         ///         This transition is subject to the container's transition rule that matches the current and defined in the container,
00957         ///         so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position 
00958         ///         in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
00959         ///     - If the specified time is greater than the destination segment's length, the modulo is taken.
00960         ///
00961         /// \sa
00962         /// - AK::SoundEngine::RenderAudio()
00963         /// - AK::SoundEngine::PostEvent()
00964         /// - AK::SoundEngine::GetSourcePlayPosition()
00965         /// - AK::MusicEngine::GetPlayingSegmentInfo()
00966         AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )( 
00967             const wchar_t* in_pszEventName,                             ///< Name of the event
00968             AkGameObjectID in_gameObjectID,                             ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
00969             AkTimeMs in_iPosition,                                      ///< Desired position where playback should restart, in milliseconds
00970             bool in_bSeekToNearestMarker = false,                       ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
00971             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.   
00972             );
00973 #endif //AK_SUPPORT_WCHAR
00974 
00975         /// Seek inside all playing objects that are referenced in play actions of the specified event.
00976         ///
00977         /// Notes:
00978         ///     - This works with all objects of the actor-mixer hierarchy, and also with music segments and music switch containers. 
00979         ///     - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored 
00980         ///         if one of their ancestors is a continuous (random or sequence) container with crossfade or 
00981         ///         trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
00982         ///         the sound that is currently playing is the first sound of the sequence.
00983         ///     - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior. 
00984         ///     - With music segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
00985         ///         value to seek within the Pre-Entry.
00986         ///     - Sounds/segments are stopped if in_iPosition is greater than their duration.
00987         ///     - in_iPosition is clamped internally to the beginning of the sound/segment.
00988         ///     - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
00989         ///         With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
00990         ///         Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the 
00991         ///         conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
00992         ///         to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
00993         ///         seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
00994         ///     - This method posts a command in the sound engine queue, thus seeking will not occur before 
00995         ///         the audio thread consumes it (after a call to RenderAudio()). 
00996         ///
00997         /// Notes specific to music segments:
00998         ///     - With music segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
00999         ///         value to seek within the Pre-Entry.
01000         ///     - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification 
01001         ///         in order to restart them if required.
01002         ///     - In order to restart at the correct location, with all their tracks synchronized, music segments 
01003         ///         take the "look-ahead time" property of their streamed tracks into account for seeking. 
01004         ///         Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the 
01005         ///         value that was passed to the method. Use AK::MusicEngine::GetPlayingSegmentInfo() to query 
01006         ///         the exact position of a segment. Also, the segment will be silent during that time
01007         ///         (so that it restarts precisely at the position that you specified). AK::MusicEngine::GetPlayingSegmentInfo() 
01008         ///         also informs you about the remaining look-ahead time. 
01009         ///
01010         /// Notes specific to music switch containers:
01011         ///     - Seeking triggers a music transition towards the current (or target) segment.
01012         ///         This transition is subject to the container's transition rule that matches the current and defined in the container,
01013         ///         so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position 
01014         ///         in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
01015         ///     - If the specified time is greater than the destination segment's length, the modulo is taken.
01016         ///
01017         /// \sa
01018         /// - AK::SoundEngine::RenderAudio()
01019         /// - AK::SoundEngine::PostEvent()
01020         /// - AK::SoundEngine::GetSourcePlayPosition()
01021         /// - AK::MusicEngine::GetPlayingSegmentInfo()
01022         AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )( 
01023             const char* in_pszEventName,                                ///< Name of the event
01024             AkGameObjectID in_gameObjectID,                             ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
01025             AkTimeMs in_iPosition,                                      ///< Desired position where playback should restart, in milliseconds
01026             bool in_bSeekToNearestMarker = false,                       ///< If true, the final seeking position will be made equal to the nearest marker (see note above)  
01027             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.   
01028             );
01029 
01030         /// Seek inside all playing objects that are referenced in play actions of the specified event.
01031         /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account. 
01032         ///
01033         /// Notes:
01034         ///     - This works with all objects of the actor-mixer hierarchy, and also with music segments and music switch containers. 
01035         ///     - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored 
01036         ///         if one of their ancestors is a continuous (random or sequence) container with crossfade or 
01037         ///         trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
01038         ///         the sound that is currently playing is the first sound of the sequence.
01039         ///     - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior. 
01040         ///     - in_iPosition is clamped internally to the beginning of the sound/segment.
01041         ///     - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
01042         ///         With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
01043         ///         Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the 
01044         ///         conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
01045         ///         to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
01046         ///         seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
01047         ///     - This method posts a command in the sound engine queue, thus seeking will not occur before 
01048         ///         the audio thread consumes it (after a call to RenderAudio()). 
01049         ///
01050         /// Notes specific to music segments:
01051         ///     - With music segments, in_fPercent is relative to the Entry Cue, and the segment's duration is the 
01052         ///         duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
01053         ///         post-exit of a segment using this method. Use absolute values instead.
01054         ///     - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification 
01055         ///         in order to restart them if required.
01056         ///     - In order to restart at the correct location, with all their tracks synchronized, music segments 
01057         ///         take the "look-ahead time" property of their streamed tracks into account for seeking. 
01058         ///         Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the 
01059         ///         value that was passed to the method. Use AK::MusicEngine::GetPlayingSegmentInfo() to query 
01060         ///         the exact position of a segment. Also, the segment will be silent during the time that period
01061         ///         (so that it restarts precisely at the position that you specified). AK::MusicEngine::GetPlayingSegmentInfo() 
01062         ///         also informs you about the remaining look-ahead time. 
01063         ///
01064         /// Notes specific to music switch containers:
01065         ///     - Seeking triggers a music transition towards the current (or target) segment.
01066         ///         This transition is subject to the container's transition rule that matches the current and defined in the container,
01067         ///         so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position 
01068         ///         in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
01069         ///     - If the specified time is greater than the destination segment's length, the modulo is taken.
01070         ///
01071         /// \sa
01072         /// - AK::SoundEngine::RenderAudio()
01073         /// - AK::SoundEngine::PostEvent()
01074         /// - AK::SoundEngine::GetSourcePlayPosition()
01075         /// - AK::MusicEngine::GetPlayingSegmentInfo()
01076         AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )( 
01077             AkUniqueID in_eventID,                                      ///< Unique ID of the event
01078             AkGameObjectID in_gameObjectID ,                            ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
01079             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)
01080             bool in_bSeekToNearestMarker = false,                       ///< If true, the final seeking position will be made equal to the nearest marker (see note above)  
01081             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.   
01082             );
01083 
01084 #ifdef AK_SUPPORT_WCHAR
01085         /// Seek inside all playing objects that are referenced in play actions of the specified event.
01086         /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account. 
01087         ///
01088         /// Notes:
01089         ///     - This works with all objects of the actor-mixer hierarchy, and also with music segments and music switch containers. 
01090         ///     - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored 
01091         ///         if one of their ancestors is a continuous (random or sequence) container with crossfade or 
01092         ///         trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
01093         ///         the sound that is currently playing is the first sound of the sequence.
01094         ///     - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior. 
01095         ///     - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
01096         ///         With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
01097         ///         Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the 
01098         ///         conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
01099         ///         to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
01100         ///         seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
01101         ///     - This method posts a command in the sound engine queue, thus seeking will not occur before 
01102         ///         the audio thread consumes it (after a call to RenderAudio()). 
01103         ///
01104         /// Notes specific to music segments:
01105         ///     - With music segments, in_fPercent is relative to the Entry Cue, and the segment's duration is the 
01106         ///         duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
01107         ///         post-exit of a segment using this method. Use absolute values instead.
01108         ///     - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification 
01109         ///         in order to restart them if required.
01110         ///     - In order to restart at the correct location, with all their tracks synchronized, music segments 
01111         ///         take the "look-ahead time" property of their streamed tracks into account for seeking. 
01112         ///         Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the 
01113         ///         value that was passed to the method. Use AK::MusicEngine::GetPlayingSegmentInfo() to query 
01114         ///         the exact position of a segment. Also, the segment will be silent during the time that period
01115         ///         (so that it restarts precisely at the position that you specified). AK::MusicEngine::GetPlayingSegmentInfo() 
01116         ///         also informs you about the remaining look-ahead time. 
01117         ///
01118         /// Notes specific to music switch containers:
01119         ///     - Seeking triggers a music transition towards the current (or target) segment.
01120         ///         This transition is subject to the container's transition rule that matches the current and defined in the container,
01121         ///         so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position 
01122         ///         in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
01123         ///     - If the specified time is greater than the destination segment's length, the modulo is taken.
01124         ///
01125         /// \sa
01126         /// - AK::SoundEngine::RenderAudio()
01127         /// - AK::SoundEngine::PostEvent()
01128         /// - AK::SoundEngine::GetSourcePlayPosition()
01129         /// - AK::MusicEngine::GetPlayingSegmentInfo()
01130         AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )( 
01131             const wchar_t* in_pszEventName,                             ///< Name of the event
01132             AkGameObjectID in_gameObjectID ,                            ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
01133             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)
01134             bool in_bSeekToNearestMarker = false,                       ///< If true, the final seeking position will be made equal to the nearest marker (see note above)  
01135             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.   
01136             );
01137 #endif //AK_SUPPORT_WCHAR
01138 
01139         /// Seek inside all playing objects that are referenced in play actions of the specified event.
01140         /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account. 
01141         ///
01142         /// Notes:
01143         ///     - This works with all objects of the actor-mixer hierarchy, and also with music segments and music switch containers. 
01144         ///     - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored 
01145         ///         if one of their ancestors is a continuous (random or sequence) container with crossfade or 
01146         ///         trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
01147         ///         the sound that is currently playing is the first sound of the sequence.
01148         ///     - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior. 
01149         ///     - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
01150         ///         With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
01151         ///         Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the 
01152         ///         conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
01153         ///         to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
01154         ///         seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
01155         ///     - This method posts a command in the sound engine queue, thus seeking will not occur before 
01156         ///         the audio thread consumes it (after a call to RenderAudio()). 
01157         ///
01158         /// Notes specific to music segments:
01159         ///     - With music segments, in_fPercent is relative to the Entry Cue, and the segment's duration is the 
01160         ///         duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
01161         ///         post-exit of a segment using this method. Use absolute values instead.
01162         ///     - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification 
01163         ///         in order to restart them if required.
01164         ///     - In order to restart at the correct location, with all their tracks synchronized, music segments 
01165         ///         take the "look-ahead time" property of their streamed tracks into account for seeking. 
01166         ///         Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the 
01167         ///         value that was passed to the method. Use AK::MusicEngine::GetPlayingSegmentInfo() to query 
01168         ///         the exact position of a segment. Also, the segment will be silent during the time that period
01169         ///         (so that it restarts precisely at the position that you specified). AK::MusicEngine::GetPlayingSegmentInfo() 
01170         ///         also informs you about the remaining look-ahead time. 
01171         ///
01172         /// Notes specific to music switch containers:
01173         ///     - Seeking triggers a music transition towards the current (or target) segment.
01174         ///         This transition is subject to the container's transition rule that matches the current and defined in the container,
01175         ///         so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position 
01176         ///         in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
01177         ///     - If the specified time is greater than the destination segment's length, the modulo is taken.
01178         ///
01179         /// \sa
01180         /// - AK::SoundEngine::RenderAudio()
01181         /// - AK::SoundEngine::PostEvent()
01182         /// - AK::SoundEngine::GetSourcePlayPosition()
01183         /// - AK::MusicEngine::GetPlayingSegmentInfo()
01184         AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )( 
01185             const char* in_pszEventName,                                ///< Name of the event
01186             AkGameObjectID in_gameObjectID,                             ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
01187             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)
01188             bool in_bSeekToNearestMarker = false,                       ///< If true, the final seeking position will be made equal to the nearest marker (see notes above).    
01189             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.   
01190             );
01191 
01192         /// Cancel all event callbacks associated with a specific callback cookie.\n
01193         /// \sa 
01194         /// - AK::SoundEngine::PostEvent()
01195         AK_EXTERNAPIFUNC( void, CancelEventCallbackCookie )( 
01196             void * in_pCookie                           ///< Callback cookie to be cancelled
01197             );
01198 
01199         /// Cancel all event callbacks associated with a specific game object.\n
01200         /// \sa 
01201         /// - AK::SoundEngine::PostEvent()
01202         AK_EXTERNAPIFUNC( void, CancelEventCallbackGameObject )(
01203             AkGameObjectID in_gameObjectID              ///< ID of the game object to be cancelled
01204             );
01205 
01206         /// Cancel all event callbacks for a specific playing ID.
01207         /// \sa 
01208         /// - AK::SoundEngine::PostEvent()
01209         AK_EXTERNAPIFUNC( void, CancelEventCallback )( 
01210             AkPlayingID in_playingID                    ///< Playing ID of the event that must not use callbacks
01211             );
01212 
01213         /// Get the current position of the source associated with this playing ID, obtained from PostEvent(). If more than one source is playing,
01214         /// the first to play is returned.
01215         /// Notes:
01216         /// - You need to pass AK_EnableGetSourcePlayPosition to PostEvent() in order to use this function, otherwise
01217         ///     it returns AK_Fail, even if the playing ID is valid.
01218         /// - The source's position is updated at every audio frame, and the time at which this occurs is stored. 
01219         ///     When you call this function from your thread, you therefore query the position that was updated in the previous audio frame.
01220         ///     If in_bExtrapolate is true (default), the returned position is extrapolated using the elapsed time since last 
01221         ///     sound engine update and the source's playback rate.
01222         /// \return AK_Success if successful.
01223         ///         It returns AK_InvalidParameter if the provided pointer is not valid.
01224         ///         It returns AK_Fail if the playing ID is invalid (not playing yet, or finished playing).
01225         /// \sa 
01226         /// - \ref soundengine_query_pos
01227         /// - \ref concept_events
01228         AK_EXTERNAPIFUNC( AKRESULT, GetSourcePlayPosition )(
01229             AkPlayingID     in_PlayingID,               ///< Playing ID returned by AK::SoundEngine::PostEvent()
01230             AkTimeMs*       out_puPosition,             ///< Position of the source (in ms) associated with the specified playing ID
01231             bool            in_bExtrapolate = true      ///< Position is extrapolated based on time elapsed since last sound engine update.
01232             );
01233 
01234         /// Get the current position of the sources associated with this playing ID, obtained from PostEvent().
01235         /// Notes:
01236         /// - You need to pass AK_EnableGetSourcePlayPosition to PostEvent() in order to use this function, otherwise
01237         ///     it returns AK_Fail, even if the playing ID is valid.
01238         /// - The source's position is updated at every audio frame, and the time at which this occurs is stored. 
01239         ///     When you call this function from your thread, you therefore query the position that was updated in the previous audio frame.
01240         ///     If in_bExtrapolate is true (default), the returned position is extrapolated using the elapsed time since last 
01241         ///     sound engine update and the source's playback rate.
01242         /// - If 0 is passed in for the number of entries (*in_pcPositions == 0) then only the number of positions will be returned and the
01243         ///     position array (out_puPositions) will not be updated.
01244         /// - The io_pcPositions pointer must be non-NULL.
01245         ///     out_puPositions may be NULL if *io_pcPositions == 0, otherwise it must be non-NULL.
01246         /// \return AK_Success if successful.
01247         ///         It returns AK_InvalidParameter if the provided pointers are not valid.
01248         ///         It returns AK_Fail if the playing ID is invalid (not playing yet, or finished playing).
01249         /// \sa 
01250         /// - \ref soundengine_query_pos
01251         /// - \ref concept_events
01252         AK_EXTERNAPIFUNC(AKRESULT, GetSourcePlayPositions)(
01253             AkPlayingID     in_PlayingID,               ///< Playing ID returned by AK::SoundEngine::PostEvent()
01254             AkSourcePosition* out_puPositions,          ///< Audio Node IDs and positions of sources associated with the specified playing ID
01255             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
01256             bool            in_bExtrapolate = true      ///< Position is extrapolated based on time elapsed since last sound engine update
01257             );
01258 
01259         /// Get the stream buffering of the sources associated with this playing ID, obtained from PostEvent().
01260         /// Notes:
01261         /// - You need to pass AK_EnableGetSourceStreamBuffering to PostEvent() in order to use this function, otherwise
01262         ///     it returns AK_Fail, even if the playing ID is valid.
01263         /// - The sources stream buffering is updated at every audio frame. If there are multiple sources associated with this playing ID,
01264         ///     the value returned corresponds to the least buffered source. 
01265         /// - The returned buffering status out_bIsBuffering will be true If any of the sources associated with the playing ID are actively being buffered.
01266         ///     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.
01267         /// - Purely in-memory sources are excluded from this database. If all sources are in-memory, GetSourceStreamBuffering() will return AK_Fail.
01268         /// - 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.
01269         ///     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.
01270         /// \return 
01271         /// - AK_Success if successful.
01272         /// - AK_Fail if the source data associated with this playing ID is not found, for example if PostEvent() was not called with AK_EnableGetSourceStreamBuffering, or if the header was not parsed.
01273         /// \sa 
01274         /// - \ref concept_events
01275         AK_EXTERNAPIFUNC( AKRESULT, GetSourceStreamBuffering )(
01276             AkPlayingID     in_PlayingID,               ///< Playing ID returned by AK::SoundEngine::PostEvent()
01277             AkTimeMs &      out_buffering,              ///< Returned amount of buffering (in ms) of the source (or one of the sources) associated with that playing ID
01278             bool &          out_bIsBuffering            ///< Returned buffering status of the source(s) associated with that playing ID
01279             );
01280 
01281         /// Stop the current content playing associated to the specified game object ID.
01282         /// If no game object is specified, all sounds will be stopped.
01283         AK_EXTERNAPIFUNC( void, StopAll )( 
01284             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< (Optional)Specify a game object to stop only playback associated to the provided game object ID.
01285             );
01286 
01287         /// Stop the current content playing associated to the specified playing ID.
01288         AK_EXTERNAPIFUNC( void, StopPlayingID )( 
01289             AkPlayingID in_playingID,                                           ///< Playing ID to be stopped.
01290             AkTimeMs in_uTransitionDuration = 0,                                ///< Fade duration
01291             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear    ///< Curve type to be used for the transition
01292             );
01293 
01294         /// Set the random seed value. Can be used to synchronize randomness
01295         /// across instances of the Sound Engine.
01296         /// \remark This seeds the number generator used for all container randomizations;
01297         ///         since it acts globally, this should be called right before any PostEvent
01298         ///         call where randomness synchronization is required, and cannot guarantee
01299         ///         similar results for continuous containers.
01300         AK_EXTERNAPIFUNC( void, SetRandomSeed )( 
01301             AkUInt32 in_uSeed                                                   ///< Random seed.
01302             );
01303 
01304         /// Mute/Unmute the busses tagged as background music.  
01305         /// This is automatically called for platforms that have user-music support.
01306         /// This function is provided to give the same behavior on platforms that don't have user-music support.
01307         AK_EXTERNAPIFUNC( void, MuteBackgroundMusic ) (
01308             bool in_bMute ///< Set true to mute, false to unmute.
01309             );
01310         //@}
01311 
01312         /// Gets the state of the Background Music busses.  This state is either set directly 
01313         /// with AK::SoundEngine::MuteBackgroundMusic or by the OS, if it has User Music services.
01314         /// \return true if the background music busses are muted, false if not.
01315         AK_EXTERNAPIFUNC(bool, GetBackgroundMusicMute) ();
01316         //@}
01317 
01318 
01319         /// Send custom game data to a plugin that resides on a bus (insert effect or mixer plugin).
01320         /// Data will be copied and stored into a separate list.
01321         /// Previous entry is deleted when a new one is sent.
01322         /// Set the data pointer to NULL to clear item from the list.
01323         /// \aknote The plugin type and ID is passed and matched with plugins set on the desired bus. 
01324         /// This means that you cannot send different data to various instances of the plugin on a same bus.\endaknote
01325         /// \return AK_Success if data was sent successfully.
01326         AK_EXTERNAPIFUNC( AKRESULT, SendPluginCustomGameData ) (
01327             AkUniqueID in_busID,            ///< Bus ID
01328             AkGameObjectID in_busObjectID,  ///< Bus Object ID. Pass AK_INVALID_GAME_OBJECT to send custom data on global scope. Game object scope supersedes global scope, as with RTPCs. 
01329             AkPluginType in_eType,          ///< Plug-in type (for example, source or effect)
01330             AkUInt32 in_uCompanyID,     ///< Company identifier (as declared in the plug-in description XML file)
01331             AkUInt32 in_uPluginID,          ///< Plug-in identifier (as declared in the plug-in description XML file)
01332             const void* in_pData,           ///< The data blob
01333             AkUInt32 in_uSizeInBytes        ///< Size of data
01334             );
01335         //@}
01336 
01337         ////////////////////////////////////////////////////////////////////////
01338         /// @name Game Objects
01339         //@{
01340         
01341         /// Register a game object.
01342         /// \return
01343         /// - AK_Success if successful
01344         /// - AK_Fail if the specified AkGameObjectID is invalid (0 and -1 are invalid)
01345         /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no 
01346         ///         matter how many times it has been registered.
01347         /// \sa 
01348         /// - AK::SoundEngine::UnregisterGameObj()
01349         /// - AK::SoundEngine::UnregisterAllGameObj()
01350         /// - \ref concept_gameobjects
01351         AK_EXTERNAPIFUNC(AKRESULT, RegisterGameObj)(
01352             AkGameObjectID in_gameObjectID                              ///< ID of the game object to be registered         
01353             );
01354 
01355         /// Register a game object.
01356         /// \return
01357         /// - AK_Success if successful
01358         /// - AK_Fail if the specified AkGameObjectID is invalid (0 and -1 are invalid)
01359         /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no 
01360         ///         matter how many times it has been registered.
01361         /// \sa 
01362         /// - AK::SoundEngine::UnregisterGameObj()
01363         /// - AK::SoundEngine::UnregisterAllGameObj()
01364         /// - \ref concept_gameobjects
01365         AK_EXTERNAPIFUNC( AKRESULT, RegisterGameObj )(
01366             AkGameObjectID in_gameObjectID,                         ///< ID of the game object to be registered
01367             const char * in_pszObjName                              ///< Name of the game object (for monitoring purpose)
01368             );
01369 
01370         /// Unregister a game object.
01371         /// \return 
01372         /// - AK_Success if successful
01373         /// - AK_Fail if the specified AkGameObjectID is invalid (0 is an invalid ID)
01374         /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no 
01375         ///         matter how many times it has been registered. Unregistering a game object while it is 
01376         ///         in use is allowed, but the control over the parameters of this game object is lost.
01377         ///         For example, say a sound associated with this game object is a 3D moving sound. This sound will 
01378         ///         stop moving when the game object is unregistered, and there will be no way to regain control over the game object.
01379         /// \sa 
01380         /// - AK::SoundEngine::RegisterGameObj()
01381         /// - AK::SoundEngine::UnregisterAllGameObj()
01382         /// - \ref concept_gameobjects
01383         AK_EXTERNAPIFUNC( AKRESULT, UnregisterGameObj )(
01384             AkGameObjectID in_gameObjectID              ///< ID of the game object to be unregistered. Use 
01385                                                         /// AK_INVALID_GAME_OBJECT to unregister all game objects.
01386             );
01387 
01388     /// Unregister all game objects, or all game objects with a particular matching set of property flags.
01389     /// This function to can be used to unregister all game objects.  
01390     /// \return
01391     /// - AK_Success if successful
01392     /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no 
01393     ///         matter how many times it has been registered. Unregistering a game object while it is 
01394     ///         in use is allowed, but the control over the parameters of this game object is lost.
01395     ///         For example, if a sound associated with this game object is a 3D moving sound, it will 
01396     ///         stop moving once the game object is unregistered, and there will be no way to recover 
01397     ///         the control over this game object.
01398     /// \sa 
01399     /// - AK::SoundEngine::RegisterGameObj()
01400     /// - AK::SoundEngine::UnregisterGameObj()
01401     /// - \ref concept_gameobjects
01402     AK_EXTERNAPIFUNC( AKRESULT, UnregisterAllGameObj )(
01403         );
01404 
01405         /// Set the position of a game object.
01406         /// \warning The object's orientation vector (in_Position.Orientation) must be normalized.
01407         /// \return 
01408         /// - AK_Success when successful
01409         /// - AK_InvalidParameter if parameters are not valid.
01410         /// \sa 
01411         /// - \ref soundengine_3dpositions
01412         AK_EXTERNAPIFUNC( AKRESULT, SetPosition )( 
01413             AkGameObjectID in_GameObjectID,     ///< Game Object identifier
01414             const AkSoundPosition & in_Position ///< Position to set; in_Position.Orientation must be normalized.
01415             );
01416 
01417         /// Set multiple positions to a single game object.
01418         /// Setting multiple positions on a single game object is a way to simulate multiple emission sources while using the resources of only one voice.
01419         /// This can be used to simulate wall openings, area sounds, or multiple objects emitting the same sound in the same area.
01420         /// \aknote Calling AK::SoundEngine::SetMultiplePositions() with only one position is the same as calling AK::SoundEngine::SetPosition() \endaknote
01421         /// \return 
01422         /// - AK_Success when successful
01423         /// - AK_InvalidParameter if parameters are not valid.
01424         /// \sa 
01425         /// - \ref soundengine_3dpositions
01426         /// - \ref soundengine_3dpositions_multiplepos
01427         /// - \ref AK::SoundEngine::MultiPositionType
01428         AK_EXTERNAPIFUNC( AKRESULT, SetMultiplePositions )( 
01429             AkGameObjectID in_GameObjectID,                     ///< Game Object identifier.
01430             const AkSoundPosition * in_pPositions,              ///< Array of positions to apply.
01431             AkUInt16 in_NumPositions,                           ///< Number of positions specified in the provided array.
01432             MultiPositionType in_eMultiPositionType = MultiPositionType_MultiDirections ///< \ref AK::SoundEngine::MultiPositionType
01433             );
01434 
01435         /// Set multiple positions to a single game object, with flexible assignment of input channels.
01436         /// Setting multiple positions on a single game object is a way to simulate multiple emission sources while using the resources of only one voice.
01437         /// This can be used to simulate wall openings, area sounds, or multiple objects emitting the same sound in the same area.
01438         /// \aknote Calling AK::SoundEngine::SetMultiplePositions() with only one position is the same as calling AK::SoundEngine::SetPosition() \endaknote
01439         /// \return 
01440         /// - AK_Success when successful
01441         /// - AK_InvalidParameter if parameters are not valid.
01442         /// \sa 
01443         /// - \ref soundengine_3dpositions
01444         /// - \ref soundengine_3dpositions_multiplepos
01445         /// - \ref AK::SoundEngine::MultiPositionType
01446         AK_EXTERNAPIFUNC( AKRESULT, SetMultiplePositions )( 
01447             AkGameObjectID in_GameObjectID,                     ///< Game Object identifier.
01448             const AkChannelEmitter * in_pPositions,         ///< Array of positions to apply.
01449             AkUInt16 in_NumPositions,                           ///< Number of positions specified in the provided array.
01450             MultiPositionType in_eMultiPositionType = MultiPositionType_MultiDirections ///< \ref AK::SoundEngine::MultiPositionType
01451             );
01452 
01453         /// Set the scaling factor of a Game Object.
01454         /// Modify the attenuation computations on this Game Object to simulate sounds with a larger or smaller area of effect.
01455         /// \return 
01456         /// - AK_Success when successful
01457         /// - AK_InvalidParameter if the scaling factor specified was 0 or negative.
01458         AK_EXTERNAPIFUNC( AKRESULT, SetScalingFactor )(
01459             AkGameObjectID in_GameObjectID,             ///< Game object identifier
01460             AkReal32 in_fAttenuationScalingFactor       ///< Scaling Factor, 1 means 100%, 0.5 means 50%, 2 means 200%, and so on.
01461             );
01462 
01463         //@}
01464 
01465         ////////////////////////////////////////////////////////////////////////
01466         /// @name Bank Management
01467         //@{
01468 
01469         /// Unload all currently loaded banks.
01470         /// It also internally calls ClearPreparedEvents() since at least one bank must have been loaded to allow preparing events.
01471         /// \return 
01472         /// - AK_Success if successful
01473         /// - AK_Fail if the sound engine was not correctly initialized or if there is not enough memory to handle the command
01474         /// \sa 
01475         /// - AK::SoundEngine::UnloadBank()
01476         /// - AK::SoundEngine::LoadBank()
01477         /// - \ref soundengine_banks
01478         AK_EXTERNAPIFUNC( AKRESULT, ClearBanks )();
01479 
01480         /// Set the I/O settings of the bank load and prepare event processes.
01481         /// The sound engine uses default values unless explicitly set by calling this method.
01482         /// \warning This function must be called before loading banks.
01483         /// \return 
01484         /// - AK_Success if successful
01485         /// - AK_Fail if the sound engine was not correctly initialized
01486         /// - AK_InvalidParameter if some parameters are invalid
01487         /// \sa 
01488         /// - \ref soundengine_banks
01489         /// - \ref streamingdevicemanager
01490         AK_EXTERNAPIFUNC( AKRESULT, SetBankLoadIOSettings )(
01491             AkReal32            in_fThroughput,         ///< Average throughput of bank data streaming (bytes/ms) (the default value is AK_DEFAULT_BANK_THROUGHPUT)
01492             AkPriority          in_priority             ///< Priority of bank streaming (the default value is AK_DEFAULT_PRIORITY)
01493             );
01494 
01495 #ifdef AK_SUPPORT_WCHAR
01496         /// Load a bank synchronously (by Unicode string).\n
01497         /// The bank name is passed to the Stream Manager.
01498         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
01499         /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
01500         /// A bank load request will be posted, and consumed by the Bank Manager thread.
01501         /// The function returns when the request has been completely processed.
01502         /// \return 
01503         /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()). 
01504         /// You may use this ID with UnloadBank().
01505         /// - AK_Success: Load or unload successful.
01506         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
01507         /// - AK_BankReadError: I/O error.
01508         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
01509         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
01510         /// - AK_InvalidFile: File specified could not be opened.
01511         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
01512         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
01513         /// \remarks
01514         /// - The initialization bank must be loaded first.
01515         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01516         ///   initialization bank. If you need to load SoundBanks from a different project, you
01517         ///   must first unload ALL banks, including the initialization bank, then load the
01518         ///   initialization bank from the other project, and finally load banks from that project.
01519         /// - Codecs and plug-ins must be registered before loading banks that use them.
01520         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01521         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01522         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01523         /// posting the event will fail.
01524         /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
01525         /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
01526         /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in 
01527         /// your implementation of the Stream Manager, or in the Low-Level I/O module if you use the default Stream Manager's implementation.
01528         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01529         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01530         /// of the UnloadBank() function.
01531         /// \sa 
01532         /// - AK::SoundEngine::UnloadBank()
01533         /// - AK::SoundEngine::ClearBanks()
01534         /// - AK::SoundEngine::GetIDFromString
01535         /// - AK::MemoryMgr::CreatePool()
01536         /// - \ref soundengine_banks
01537         /// - \ref integrating_elements_plugins
01538         /// - \ref streamingdevicemanager
01539         /// - \ref streamingmanager_lowlevel
01540         /// - \ref sdk_bank_training
01541         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01542             const wchar_t*      in_pszString,           ///< Name of the bank to load
01543             AkMemPoolId         in_memPoolId,           ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
01544             AkBankID &          out_bankID              ///< Returned bank ID
01545             );
01546 #endif //AK_SUPPORT_WCHAR
01547 
01548         /// Load a bank synchronously.\n
01549         /// The bank name is passed to the Stream Manager.
01550         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
01551         /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
01552         /// A bank load request will be posted, and consumed by the Bank Manager thread.
01553         /// The function returns when the request has been completely processed.
01554         /// \return 
01555         /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()). 
01556         /// You may use this ID with UnloadBank().
01557         /// - AK_Success: Load or unload successful.
01558         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
01559         /// - AK_BankReadError: I/O error.
01560         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
01561         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
01562         /// - AK_InvalidFile: File specified could not be opened.
01563         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
01564         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
01565         /// \remarks
01566         /// - The initialization bank must be loaded first.
01567         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01568         ///   initialization bank. If you need to load SoundBanks from a different project, you
01569         ///   must first unload ALL banks, including the initialization bank, then load the
01570         ///   initialization bank from the other project, and finally load banks from that project.
01571         /// - Codecs and plug-ins must be registered before loading banks that use them.
01572         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01573         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01574         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01575         /// posting the event will fail.
01576         /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
01577         /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
01578         /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in 
01579         /// your implementation of the Stream Manager, or in the Low-Level I/O module if you use the default Stream Manager's implementation.
01580         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01581         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01582         /// of the UnloadBank() function.
01583         /// \sa 
01584         /// - AK::SoundEngine::UnloadBank()
01585         /// - AK::SoundEngine::ClearBanks()
01586         /// - AK::SoundEngine::GetIDFromString
01587         /// - AK::MemoryMgr::CreatePool()
01588         /// - \ref soundengine_banks
01589         /// - \ref integrating_elements_plugins
01590         /// - \ref streamingdevicemanager
01591         /// - \ref streamingmanager_lowlevel
01592         /// - \ref sdk_bank_training
01593         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01594             const char*         in_pszString,           ///< Name of the bank to load
01595             AkMemPoolId         in_memPoolId,           ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
01596             AkBankID &          out_bankID              ///< Returned bank ID
01597             );
01598 
01599         /// Load a bank synchronously (by ID).\n
01600         /// \aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
01601         /// The bank ID is passed to the Stream Manager.
01602         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
01603         /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
01604         /// A bank load request will be posted, and consumed by the Bank Manager thread.
01605         /// The function returns when the request has been completely processed.
01606         /// \return 
01607         /// - AK_Success: Load or unload successful.
01608         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
01609         /// - AK_BankReadError: I/O error.
01610         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
01611         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
01612         /// - AK_InvalidFile: File specified could not be opened.
01613         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
01614         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
01615         /// \remarks
01616         /// - The initialization bank must be loaded first.
01617         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01618         ///   initialization bank. If you need to load SoundBanks from a different project, you
01619         ///   must first unload ALL banks, including the initialization bank, then load the
01620         ///   initialization bank from the other project, and finally load banks from that project.
01621         /// - Codecs and plug-ins must be registered before loading banks that use them.
01622         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01623         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01624         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01625         /// posting the event will fail.
01626         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01627         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01628         /// of the UnloadBank function.
01629         /// \sa 
01630         /// - AK::SoundEngine::UnloadBank()
01631         /// - AK::SoundEngine::ClearBanks()
01632         /// - AK::MemoryMgr::CreatePool()
01633         /// - \ref soundengine_banks
01634         /// - \ref integrating_elements_plugins
01635         /// - \ref sdk_bank_training
01636         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01637             AkBankID            in_bankID,              ///< Bank ID of the bank to load
01638             AkMemPoolId         in_memPoolId            ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
01639             );
01640 
01641         /// Load a bank synchronously (from in-memory data, in-place).\n
01642         ///
01643         /// IMPORTANT: Banks loaded from memory with in-place data MUST be unloaded using the UnloadBank function
01644         /// providing the same memory pointer. Make sure you are using the correct UnloadBank(...) overload
01645         ///
01646         /// Use this overload when you want to manage I/O on your side. Load the bank file
01647         /// in a buffer and pass its address to the sound engine.
01648         /// In-memory loading is in-place: *** the memory must be valid until the bank is unloaded. ***
01649         /// A bank load request will be posted, and consumed by the Bank Manager thread.
01650         /// The function returns when the request has been completely processed.
01651         /// \return 
01652         /// The bank ID, which is stored in the first few bytes of the bank file. You may use this 
01653         /// ID with UnloadBank().
01654         /// - AK_Success: Load or unload successful.
01655         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
01656         /// - AK_BankReadError: I/O error.
01657         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
01658         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
01659         /// - AK_InvalidFile: File specified could not be opened.
01660         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
01661         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
01662         /// \remarks
01663         /// - The initialization bank must be loaded first.
01664         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01665         ///   initialization bank. If you need to load SoundBanks from a different project, you
01666         ///   must first unload ALL banks, including the initialization bank, then load the
01667         ///   initialization bank from the other project, and finally load banks from that project.
01668         /// - Codecs and plug-ins must be registered before loading banks that use them.
01669         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01670         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01671         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01672         /// posting the event will fail.
01673         /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
01674         /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Physical memory allocator.
01675         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01676         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01677         /// of the UnloadBank function.
01678         /// - Avoid using this function for banks containing a lot of events or structure data.  
01679         ///   This data will be loaded in the Default Pool anyway thus duplicating memory (one copy in the Default Pool 
01680         ///   and one in the block you provided).  For event/structure-only banks, prefer the other versions of LoadBank().
01681         /// \sa 
01682         /// - AK::SoundEngine::UnloadBank()
01683         /// - AK::SoundEngine::ClearBanks()
01684         /// - \ref soundengine_banks
01685         /// - \ref integrating_elements_plugins
01686         /// - \ref sdk_bank_training
01687         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01688             const void *        in_pInMemoryBankPtr,    ///< Pointer to the in-memory bank to load (pointer is stored in sound engine, memory must remain valid)
01689             AkUInt32            in_uInMemoryBankSize,   ///< Size of the in-memory bank to load
01690             AkBankID &          out_bankID              ///< Returned bank ID
01691             );
01692 
01693         /// Load a bank synchronously (from in-memory data, out-of-place).\n
01694         ///
01695         /// NOTE: Banks loaded from in-memory with out-of-place data must be unloaded using the standard UnloadBank function
01696         /// (with no memory pointer). Make sure you are using the correct UnloadBank(...) overload
01697         ///
01698         /// Use this overload when you want to manage I/O on your side. Load the bank file
01699         /// in a buffer and pass its address to the sound engine, the media section of the bank will be copied into the 
01700         /// specified memory pool.  
01701         /// In-memory loading is out-of-place: the buffer can be release as soon as the function returns. The advantage of using this
01702         /// over the in-place version is that there is no duplication of bank structures.
01703         /// A bank load request will be posted, and consumed by the Bank Manager thread.
01704         /// The function returns when the request has been completely processed.
01705         /// \return 
01706         /// The bank ID, which is stored in the first few bytes of the bank file. You may use this 
01707         /// ID with UnloadBank().
01708         /// - AK_Success: Load or unload successful.
01709         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
01710         /// - AK_BankReadError: I/O error.
01711         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
01712         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
01713         /// - AK_InvalidFile: File specified could not be opened.
01714         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
01715         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
01716         /// \remarks
01717         /// - The initialization bank must be loaded first.
01718         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01719         ///   initialization bank. If you need to load SoundBanks from a different project, you
01720         ///   must first unload ALL banks, including the initialization bank, then load the
01721         ///   initialization bank from the other project, and finally load banks from that project.
01722         /// - Codecs and plug-ins must be registered before loading banks that use them.
01723         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01724         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01725         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01726         /// posting the event will fail.
01727         /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
01728         /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Physical memory allocator.
01729         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01730         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01731         /// of the UnloadBank function.
01732         /// - Avoid using this function for banks containing a lot of events or structure data.  
01733         ///   This data will be loaded in the Default Pool anyway thus duplicating memory (one copy in the Default Pool 
01734         ///   and one in the block you provided).  For event/structure-only banks, prefer the other versions of LoadBank().
01735         /// \sa 
01736         /// - AK::SoundEngine::UnloadBank()
01737         /// - AK::SoundEngine::ClearBanks()
01738         /// - \ref soundengine_banks
01739         /// - \ref integrating_elements_plugins
01740         /// - \ref sdk_bank_training
01741         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01742             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)
01743             AkUInt32            in_uInMemoryBankSize,   ///< Size of the in-memory bank to load
01744             AkMemPoolId         in_uPoolForBankMedia,   ///< Memory pool to copy the media section of the bank to (the pool is created if AK_DEFAULT_POOL_ID is passed).
01745             AkBankID &          out_bankID              ///< Returned bank ID
01746             );
01747 
01748         /// Synchronously decode Vorbis-encoded media in a SoundBank.
01749         AK_EXTERNAPIFUNC( AKRESULT, DecodeBank )(
01750             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)
01751             AkUInt32            in_uInMemoryBankSize,   ///< Size of the in-memory bank to decode
01752             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.
01753             void * &            out_pDecodedBankPtr,    ///< Decoded bank memory location.
01754             AkUInt32 &          out_uDecodedBankSize    ///< Decoded bank memory size.
01755             );
01756 
01757 #ifdef AK_SUPPORT_WCHAR
01758         /// Load a bank asynchronously (by Unicode string).\n
01759         /// The bank name is passed to the Stream Manager.
01760         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
01761         /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
01762         /// A bank load request will be posted to the Bank Manager consumer thread.
01763         /// The function returns immediately.
01764         /// \return 
01765         /// AK_Success if the scheduling was successful, AK_Fail otherwise.
01766         /// Use a callback to be notified when completed, and get the status of the request.
01767         /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()). 
01768         /// You may use this ID with UnloadBank().
01769         /// \remarks
01770         /// - The initialization bank must be loaded first.
01771         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01772         ///   initialization bank. If you need to load SoundBanks from a different project, you
01773         ///   must first unload ALL banks, including the initialization bank, then load the
01774         ///   initialization bank from the other project, and finally load banks from that project.
01775         /// - Codecs and plug-ins must be registered before loading banks that use them.
01776         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01777         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01778         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01779         /// posting the event will fail.
01780         /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
01781         /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
01782         /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in 
01783         /// your implementation of the Stream Manager (AK::IAkStreamMgr::CreateStd()), or in the Low-Level I/O module 
01784         /// (AK::StreamMgr::IAkFileLocationResolver::Open()) if you use the default Stream Manager's implementation.
01785         /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in AK::StreamMgr::IAkFileLocationResolver::Open() 
01786         // as AkFileSystemFlags::pCustomParam.
01787         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01788         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01789         /// of the UnloadBank function.
01790         /// \sa 
01791         /// - AK::SoundEngine::UnloadBank()
01792         /// - AK::SoundEngine::ClearBanks()
01793         /// - AK::MemoryMgr::CreatePool()
01794         /// - AkBankCallbackFunc
01795         /// - \ref soundengine_banks
01796         /// - \ref integrating_elements_plugins
01797         /// - \ref streamingdevicemanager
01798         /// - \ref streamingmanager_lowlevel
01799         /// - \ref sdk_bank_training
01800         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01801             const wchar_t*      in_pszString,           ///< Name/path of the bank to load
01802             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
01803             void *              in_pCookie,             ///< Callback cookie (reserved to user, passed to the callback function, and also to  AK::StreamMgr::IAkFileLocationResolver::Open() as AkFileSystemFlags::pCustomParam)
01804             AkMemPoolId         in_memPoolId,           ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
01805             AkBankID &          out_bankID              ///< Returned bank ID
01806             );
01807 #endif //AK_SUPPORT_WCHAR
01808 
01809         /// Load a bank asynchronously.\n
01810         /// The bank name is passed to the Stream Manager.
01811         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
01812         /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
01813         /// A bank load request will be posted to the Bank Manager consumer thread.
01814         /// The function returns immediately.
01815         /// \return 
01816         /// AK_Success if the scheduling was successful, AK_Fail otherwise.
01817         /// Use a callback to be notified when completed, and get the status of the request.
01818         /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()). 
01819         /// You may use this ID with UnloadBank().
01820         /// \remarks
01821         /// - The initialization bank must be loaded first.
01822         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01823         ///   initialization bank. If you need to load SoundBanks from a different project, you
01824         ///   must first unload ALL banks, including the initialization bank, then load the
01825         ///   initialization bank from the other project, and finally load banks from that project.
01826         /// - Codecs and plug-ins must be registered before loading banks that use them.
01827         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01828         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01829         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01830         /// posting the event will fail.
01831         /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
01832         /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
01833         /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in 
01834         /// your implementation of the Stream Manager (AK::IAkStreamMgr::CreateStd()), or in the Low-Level I/O module 
01835         /// (AK::StreamMgr::IAkFileLocationResolver::Open()) if you use the default Stream Manager's implementation.
01836         /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in AK::StreamMgr::IAkFileLocationResolver::Open() 
01837         // as AkFileSystemFlags::pCustomParam.
01838         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01839         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01840         /// of the UnloadBank function.
01841         /// \sa 
01842         /// - AK::SoundEngine::UnloadBank()
01843         /// - AK::SoundEngine::ClearBanks()
01844         /// - AK::MemoryMgr::CreatePool()
01845         /// - AkBankCallbackFunc
01846         /// - \ref soundengine_banks
01847         /// - \ref integrating_elements_plugins
01848         /// - \ref streamingdevicemanager
01849         /// - \ref streamingmanager_lowlevel
01850         /// - \ref sdk_bank_training
01851         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01852             const char*         in_pszString,           ///< Name/path of the bank to load
01853             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
01854             void *              in_pCookie,             ///< Callback cookie (reserved to user, passed to the callback function, and also to  AK::StreamMgr::IAkFileLocationResolver::Open() as AkFileSystemFlags::pCustomParam)
01855             AkMemPoolId         in_memPoolId,           ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
01856             AkBankID &          out_bankID              ///< Returned bank ID
01857             );
01858 
01859         /// Load a bank asynchronously (by ID).\n
01860         /// \aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
01861         /// The bank ID is passed to the Stream Manager.
01862         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
01863         /// You can specify a custom pool for storage of media, the engine will create a new pool if AK_DEFAULT_POOL_ID is passed.
01864         /// A bank load request will be posted to the Bank Manager consumer thread.
01865         /// The function returns immediately.
01866         /// \return 
01867         /// AK_Success if the scheduling was successful, AK_Fail otherwise.
01868         /// Use a callback to be notified when completed, and get the status of the request.
01869         /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()). 
01870         /// You may use this ID with UnloadBank().
01871         /// \remarks
01872         /// - The initialization bank must be loaded first.
01873         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01874         ///   initialization bank. If you need to load SoundBanks from a different project, you
01875         ///   must first unload ALL banks, including the initialization bank, then load the
01876         ///   initialization bank from the other project, and finally load banks from that project.
01877         /// - Codecs and plug-ins must be registered before loading banks that use them.
01878         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01879         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01880         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01881         /// posting the event will fail.
01882         /// - The file path should be resolved in your implementation of the Stream Manager, or in the Low-Level I/O module if 
01883         /// you use the default Stream Manager's implementation. The ID overload of AK::IAkStreamMgr::CreateStd() and AK::StreamMgr::IAkFileLocationResolver::Open() are called.
01884         /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in AK::StreamMgr::IAkFileLocationResolver::Open() 
01885         // as AkFileSystemFlags::pCustomParam.
01886         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01887         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01888         /// of the UnloadBank function.
01889         /// \sa 
01890         /// - AK::SoundEngine::UnloadBank()
01891         /// - AK::SoundEngine::ClearBanks()
01892         /// - AK::MemoryMgr::CreatePool()
01893         /// - AkBankCallbackFunc
01894         /// - \ref soundengine_banks
01895         /// - \ref integrating_elements_plugins
01896         /// - \ref sdk_bank_training
01897         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01898             AkBankID            in_bankID,              ///< Bank ID of the bank to load
01899             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
01900             void *              in_pCookie,             ///< Callback cookie (reserved to user, passed to the callback function, and also to  AK::StreamMgr::IAkFileLocationResolver::Open() as AkFileSystemFlags::pCustomParam)
01901             AkMemPoolId         in_memPoolId            ///< Memory pool ID (the pool is created if AK_DEFAULT_POOL_ID is passed)
01902             );
01903 
01904         /// Load a bank asynchronously (from in-memory data, in-place).\n
01905         ///
01906         /// IMPORTANT: Banks loaded from memory with in-place data MUST be unloaded using the UnloadBank function
01907         /// providing the same memory pointer. Make sure you are using the correct UnloadBank(...) overload
01908         ///
01909         /// Use this overload when you want to manage I/O on your side. Load the bank file
01910         /// in a buffer and pass its address to the sound engine.
01911         /// In-memory loading is in-place: *** the memory must be valid until the bank is unloaded. ***
01912         /// A bank load request will be posted to the Bank Manager consumer thread.
01913         /// The function returns immediately.
01914         /// \return 
01915         /// AK_Success if the scheduling was successful, AK_Fail otherwise, or AK_InvalidParameter if memory alignment is not correct.
01916         /// Use a callback to be notified when completed, and get the status of the request.
01917         /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()). 
01918         /// You may use this ID with UnloadBank().
01919         /// \remarks
01920         /// - The initialization bank must be loaded first.
01921         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01922         ///   initialization bank. If you need to load SoundBanks from a different project, you
01923         ///   must first unload ALL banks, including the initialization bank, then load the
01924         ///   initialization bank from the other project, and finally load banks from that project.
01925         /// - Codecs and plug-ins must be registered before loading banks that use them.
01926         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01927         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01928         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01929         /// posting the event will fail.
01930         /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
01931         /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Physical memory allocator.
01932         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01933         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01934         /// of the UnloadBank function.
01935         /// \sa 
01936         /// - AK::SoundEngine::UnloadBank()
01937         /// - AK::SoundEngine::ClearBanks()
01938         /// - AkBankCallbackFunc
01939         /// - \ref soundengine_banks
01940         /// - \ref integrating_elements_plugins
01941         /// - \ref sdk_bank_training
01942         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01943             const void *        in_pInMemoryBankPtr,    ///< Pointer to the in-memory bank to load (pointer is stored in sound engine, memory must remain valid)
01944             AkUInt32            in_uInMemoryBankSize,   ///< Size of the in-memory bank to load
01945             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
01946             void *              in_pCookie,             ///< Callback cookie
01947             AkBankID &          out_bankID              ///< Returned bank ID
01948             );
01949 
01950         /// Load a bank asynchronously (from in-memory data, out-of-place).\n
01951         ///
01952         /// NOTE: Banks loaded from in-memory with out-of-place data must be unloaded using the standard UnloadBank function
01953         /// (with no memory pointer). Make sure you are using the correct UnloadBank(...) overload
01954         ///
01955         /// Use this overload when you want to manage I/O on your side. Load the bank file
01956         /// in a buffer and pass its address to the sound engine, the media section of the bank will be copied into the 
01957         /// specified memory pool.  
01958         /// In-memory loading is out-of-place: the buffer can be released after the callback function is called. The advantage of using this
01959         /// over the in-place version is that there is no duplication of bank structures.
01960         /// A bank load request will be posted to the Bank Manager consumer thread.
01961         /// The function returns immediately.
01962         /// \return 
01963         /// AK_Success if the scheduling was successful, AK_Fail otherwise, or AK_InvalidParameter if memory alignment is not correct.
01964         /// Use a callback to be notified when completed, and get the status of the request.
01965         /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()). 
01966         /// You may use this ID with UnloadBank().
01967         /// \remarks
01968         /// - The initialization bank must be loaded first.
01969         /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
01970         ///   initialization bank. If you need to load SoundBanks from a different project, you
01971         ///   must first unload ALL banks, including the initialization bank, then load the
01972         ///   initialization bank from the other project, and finally load banks from that project.
01973         /// - Codecs and plug-ins must be registered before loading banks that use them.
01974         /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01975         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 
01976         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 
01977         /// posting the event will fail.
01978         /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
01979         /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Physical memory allocator.
01980         /// - Requesting to load a bank in a different memory pool than where the bank was previously loaded must be done only
01981         /// after receiving confirmation by the callback that the bank was completely unloaded or by using synchronous versions
01982         /// of the UnloadBank function.
01983         /// \sa 
01984         /// - AK::SoundEngine::UnloadBank()
01985         /// - AK::SoundEngine::ClearBanks()
01986         /// - AkBankCallbackFunc
01987         /// - \ref soundengine_banks
01988         /// - \ref integrating_elements_plugins
01989         /// - \ref sdk_bank_training
01990         AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
01991             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)
01992             AkUInt32            in_uInMemoryBankSize,   ///< Size of the in-memory bank to load
01993             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
01994             void *              in_pCookie,             ///< Callback cookie
01995             AkMemPoolId         in_uPoolForBankMedia,   ///< Memory pool to copy the media section of the bank to (the pool is created if AK_DEFAULT_POOL_ID is passed).
01996             AkBankID &          out_bankID              ///< Returned bank ID
01997             );
01998 
01999 #ifdef AK_SUPPORT_WCHAR
02000         /// Unload a bank synchronously (by Unicode string).\n
02001         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
02002         /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
02003         /// \remarks
02004         /// - If you provided a pool memory ID when loading this bank, it is returned as well. 
02005         /// Otherwise, the function returns AK_DEFAULT_POOL_ID.
02006         /// - The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID, 
02007         /// then it calls the synchronous version of UnloadBank() by ID.
02008         /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
02009         /// not the name of the file (if you changed it), nor the full path of the file. 
02010         /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped. 
02011         /// This means that streamed sounds or generated sounds will not be stopped.
02012         /// \sa 
02013         /// - AK::SoundEngine::LoadBank()
02014         /// - AK::SoundEngine::ClearBanks()
02015         /// - \ref soundengine_banks
02016         AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
02017             const wchar_t*      in_pszString,           ///< Name of the bank to unload
02018             const void *        in_pInMemoryBankPtr,    ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
02019             AkMemPoolId *       out_pMemPoolId = NULL   ///< Returned memory pool ID used with LoadBank() (can pass NULL)
02020             );
02021 #endif //AK_SUPPORT_WCHAR
02022 
02023         /// Unload a bank synchronously.\n
02024         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
02025         /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
02026         /// \remarks
02027         /// - If you provided a pool memory ID when loading this bank, it is returned as well. 
02028         /// Otherwise, the function returns AK_DEFAULT_POOL_ID.
02029         /// - The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID, 
02030         /// then it calls the synchronous version of UnloadBank() by ID.
02031         /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
02032         /// not the name of the file (if you changed it), nor the full path of the file. 
02033         /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped. 
02034         /// This means that streamed sounds or generated sounds will not be stopped.
02035         /// \sa 
02036         /// - AK::SoundEngine::LoadBank()
02037         /// - AK::SoundEngine::ClearBanks()
02038         /// - \ref soundengine_banks
02039         AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
02040             const char*         in_pszString,           ///< Name of the bank to unload
02041             const void *        in_pInMemoryBankPtr,    ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
02042             AkMemPoolId *       out_pMemPoolId = NULL   ///< Returned memory pool ID used with LoadBank() (can pass NULL)
02043             );
02044 
02045         /// Unload a bank synchronously (by ID and memory pointer).\n
02046         /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
02047         /// \remarks
02048         /// If you provided a pool memory ID when loading this bank, it is returned as well. 
02049         /// Otherwise, the function returns AK_DEFAULT_POOL_ID.
02050         /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped. 
02051         /// This means that streamed sounds or generated sounds will not be stopped.
02052         /// \sa 
02053         /// - AK::SoundEngine::LoadBank()
02054         /// - AK::SoundEngine::ClearBanks()
02055         /// - \ref soundengine_banks
02056         AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
02057             AkBankID            in_bankID,              ///< ID of the bank to unload
02058             const void *        in_pInMemoryBankPtr,    ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
02059             AkMemPoolId *       out_pMemPoolId = NULL   ///< Returned memory pool ID used with LoadBank() (can pass NULL)
02060             );
02061 
02062 #ifdef AK_SUPPORT_WCHAR
02063         /// Unload a bank asynchronously (by Unicode string).\n
02064         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
02065         /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
02066         /// \remarks
02067         /// The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID, 
02068         /// then it calls the synchronous version of UnloadBank() by ID.
02069         /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
02070         /// not the name of the file (if you changed it), nor the full path of the file. 
02071         /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped. 
02072         /// This means that streamed sounds or generated sounds will not be stopped.
02073         /// \sa 
02074         /// - AK::SoundEngine::LoadBank()
02075         /// - AK::SoundEngine::ClearBanks()
02076         /// - AkBankCallbackFunc
02077         /// - \ref soundengine_banks
02078         AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
02079             const wchar_t*      in_pszString,           ///< Name of the bank to unload
02080             const void *        in_pInMemoryBankPtr,    ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
02081             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02082             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02083             );
02084 #endif //AK_SUPPORT_WCHAR
02085 
02086         /// Unload a bank asynchronously.\n
02087         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
02088         /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
02089         /// \remarks
02090         /// The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID, 
02091         /// then it calls the synchronous version of UnloadBank() by ID.
02092         /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
02093         /// not the name of the file (if you changed it), nor the full path of the file. 
02094         /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped. 
02095         /// This means that streamed sounds or generated sounds will not be stopped.
02096         /// \sa 
02097         /// - AK::SoundEngine::LoadBank()
02098         /// - AK::SoundEngine::ClearBanks()
02099         /// - AkBankCallbackFunc
02100         /// - \ref soundengine_banks
02101         AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
02102             const char*         in_pszString,           ///< Name of the bank to unload
02103             const void *        in_pInMemoryBankPtr,    ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
02104             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02105             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02106             );
02107 
02108         /// Unload a bank asynchronously (by ID and memory pointer).\n
02109         /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
02110         /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
02111         /// \remarks
02112         /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped. 
02113         /// This means that streamed sounds or generated sounds will not be stopped.
02114         /// \sa 
02115         /// - AK::SoundEngine::LoadBank()
02116         /// - AK::SoundEngine::ClearBanks()
02117         /// - AkBankCallbackFunc
02118         /// - \ref soundengine_banks
02119         AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
02120             AkBankID            in_bankID,              ///< ID of the bank to unload
02121             const void *        in_pInMemoryBankPtr,    ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL only if NULL was passed when loading the bank.
02122             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02123             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02124             );
02125 
02126         /// Cancel all event callbacks associated with a specific callback cookie specified while loading Banks of preparing events.\n
02127         /// \sa 
02128         /// - AK::SoundEngine::LoadBank()
02129         /// - AK::SoundEngine::PrepareEvent()
02130         /// - AK::SoundEngine::UnloadBank()
02131         /// - AK::SoundEngine::ClearBanks()
02132         /// - AkBankCallbackFunc
02133         AK_EXTERNAPIFUNC( void, CancelBankCallbackCookie )( 
02134             void * in_pCookie                           ///< Callback cookie to be canceled
02135             );
02136 
02137         /// Preparation type.
02138         /// \sa
02139         /// - AK::SoundEngine::PrepareEvent()
02140         /// - AK::SoundEngine::PrepareGameSyncs()
02141         /// - AK::SoundEngine::PrepareBank()
02142         enum PreparationType
02143         {
02144             Preparation_Load,   ///< \c PrepareEvent() will load required information to play the specified event.
02145             Preparation_Unload, ///< \c PrepareEvent() will unload required information to play the specified event.
02146             Preparation_LoadAndDecode ///< Vorbis media is decoded when loading, and an uncompressed PCM version is used for playback.
02147         };
02148 
02149         /// Parameter to be passed to AK::SoundEngine::PrepareBank().
02150         /// Use AkBankContent_All to load both the media and structural content from the bank. 
02151         /// 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.
02152         /// \sa 
02153         /// - AK::SoundEngine::PrepareBank()
02154         /// - \ref soundengine_banks_preparingbanks
02155         enum AkBankContent
02156         {
02157             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.
02158             AkBankContent_All               ///< Use AkBankContent_All to load both the media and structural content.
02159         };
02160 
02161 #ifdef AK_SUPPORT_WCHAR
02162         /// 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 
02163         /// 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(), 
02164         /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
02165         /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank, 
02166         /// allowing using PrepareEvent() to load media on demand.  
02167         /// \sa 
02168         /// - \ref soundengine_banks_preparingbanks
02169         /// - AK::SoundEngine::LoadBank()
02170         /// - AK::SoundEngine::PreparationType
02171         /// \remarks
02172         /// 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 
02173         ///     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;
02174         /// 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.
02175         AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
02176             AK::SoundEngine::PreparationType    in_PreparationType,         ///< Preparation type ( Preparation_Load or Preparation_Unload )
02177             const wchar_t*        in_pszString,                             ///< Name of the bank to Prepare/Unprepare.
02178             AK::SoundEngine::AkBankContent  in_uFlags = AkBankContent_All   ///< Structures only (including events) or all content.
02179             );
02180 #endif //AK_SUPPORT_WCHAR
02181 
02182         /// 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 
02183         /// 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(), 
02184         /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
02185         /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank, 
02186         /// allowing using PrepareEvent() to load media on demand.  
02187         /// \sa 
02188         /// - \ref soundengine_banks_preparingbanks
02189         /// - AK::SoundEngine::LoadBank()
02190         /// - AK::SoundEngine::PreparationType
02191         /// \remarks
02192         /// 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 
02193         ///     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;
02194         ///     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.
02195         AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
02196             AK::SoundEngine::PreparationType    in_PreparationType,         ///< Preparation type ( Preparation_Load or Preparation_Unload )
02197             const char*           in_pszString,                             ///< Name of the bank to Prepare/Unprepare.
02198             AK::SoundEngine::AkBankContent  in_uFlags = AkBankContent_All   ///< Structures only (including events) or all content.
02199             );
02200 
02201         /// \n\aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
02202         /// 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 
02203         /// 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(), 
02204         /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
02205         /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank, 
02206         /// allowing using PrepareEvent() to load media on demand.  
02207         /// \sa 
02208         /// - \ref soundengine_banks_preparingbanks
02209         /// - AK::SoundEngine::LoadBank()
02210         /// - AK::SoundEngine::PreparationType
02211         /// \remarks
02212         /// 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 
02213         ///     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;
02214         ///     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.
02215         AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
02216             AK::SoundEngine::PreparationType    in_PreparationType,         ///< Preparation type ( Preparation_Load or Preparation_Unload )
02217             AkBankID            in_bankID,                                  ///< ID of the bank to Prepare/Unprepare.
02218             AK::SoundEngine::AkBankContent  in_uFlags = AkBankContent_All   ///< Structures only (including events) or all content.
02219             );
02220 
02221 #ifdef AK_SUPPORT_WCHAR
02222         /// 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 
02223         /// 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(), 
02224         /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
02225         /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank, 
02226         /// allowing using PrepareEvent() to load media on demand.  
02227         /// \sa 
02228         /// - \ref soundengine_banks_preparingbanks
02229         /// - AK::SoundEngine::LoadBank()
02230         /// - AK::SoundEngine::PreparationType
02231         /// \remarks
02232         /// 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 
02233         ///     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;
02234         ///     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.
02235         AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
02236             AK::SoundEngine::PreparationType    in_PreparationType,         ///< Preparation type ( Preparation_Load or Preparation_Unload )
02237             const wchar_t*      in_pszString,                               ///< Name of the bank to Prepare/Unprepare.
02238             AkBankCallbackFunc  in_pfnBankCallback,                         ///< Callback function
02239             void *              in_pCookie,                                 ///< Callback cookie (reserved to user, passed to the callback function)
02240             AK::SoundEngine::AkBankContent  in_uFlags = AkBankContent_All   ///< Structures only (including events) or all content.
02241             );
02242 #endif //AK_SUPPORT_WCHAR
02243 
02244         /// 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 
02245         /// 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(), 
02246         /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
02247         /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank, 
02248         /// allowing using PrepareEvent() to load media on demand.  
02249         /// \sa 
02250         /// - \ref soundengine_banks_preparingbanks
02251         /// - AK::SoundEngine::LoadBank()
02252         /// - AK::SoundEngine::PreparationType
02253         /// \remarks
02254         /// 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 
02255         ///     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;
02256         ///     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.
02257         AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
02258             AK::SoundEngine::PreparationType    in_PreparationType,         ///< Preparation type ( Preparation_Load or Preparation_Unload )
02259             const char*         in_pszString,                               ///< Name of the bank to Prepare/Unprepare.
02260             AkBankCallbackFunc  in_pfnBankCallback,                         ///< Callback function
02261             void *              in_pCookie,                                 ///< Callback cookie (reserved to user, passed to the callback function)
02262             AK::SoundEngine::AkBankContent  in_uFlags = AkBankContent_All   ///< Structures only (including events) or all content.
02263             );
02264 
02265         /// \n\aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
02266         /// 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 
02267         /// 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(), 
02268         /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
02269         /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank, 
02270         /// allowing using PrepareEvent() to load media on demand.  
02271         /// \sa 
02272         /// - \ref soundengine_banks_preparingbanks
02273         /// - AK::SoundEngine::LoadBank()
02274         /// - AK::SoundEngine::PreparationType
02275         /// \remarks
02276         /// 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 
02277         ///     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;
02278         ///     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.
02279         AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
02280             AK::SoundEngine::PreparationType        in_PreparationType,             ///< Preparation type ( Preparation_Load or Preparation_Unload )
02281             AkBankID            in_bankID,                      ///< ID of the bank to Prepare/Unprepare.
02282             AkBankCallbackFunc  in_pfnBankCallback,             ///< Callback function
02283             void *              in_pCookie,                     ///< Callback cookie (reserved to user, passed to the callback function)
02284             AK::SoundEngine::AkBankContent      in_uFlags = AkBankContent_All   ///< Structures only (including events) or all content.
02285             );
02286         
02287         /// Clear all previously prepared events.\n
02288         /// \return
02289         /// - AK_Success if successful.
02290         /// - AK_Fail if the sound engine was not correctly initialized or if there is not enough memory to handle the command.
02291         /// \remarks
02292         /// The function ClearBanks() also clears all prepared events.
02293         /// \sa
02294         /// - AK::SoundEngine::PrepareEvent()
02295         /// - AK::SoundEngine::ClearBanks()
02296         AK_EXTERNAPIFUNC( AKRESULT, ClearPreparedEvents )();
02297 
02298 #ifdef AK_SUPPORT_WCHAR
02299         /// Prepare or un-prepare events synchronously (by Unicode string).\n
02300         /// The Events are identified by strings, and converted to IDs internally
02301         /// (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02302         /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s) 
02303         /// that contain the Events and structures. When a request is posted to the
02304         /// Bank Manager consumer thread, it will resolve all dependencies needed to 
02305         /// successfully post the specified Events and load the required loose media files. 
02306         /// \aknote Before version 2015.1, the required media files could be included
02307         /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
02308         /// however, PrepareEvent() now only looks for loose media files.
02309         /// \endaknote
02310         /// The function returns when the request is completely processed.
02311         /// \return 
02312         /// - AK_Success: Prepare/un-prepare successful.
02313         /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
02314         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
02315         /// - AK_BankReadError: I/O error.
02316         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
02317         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
02318         /// - AK_InvalidFile: File specified could not be opened.
02319         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
02320         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
02321         /// \remarks
02322         /// Whenever at least one event fails to be resolved, the actions performed for all 
02323         /// other events are cancelled.
02324         /// \sa
02325         /// - AK::SoundEngine::PrepareEvent()
02326         /// - AK::SoundEngine::ClearPreparedEvents()
02327         /// - AK::SoundEngine::GetIDFromString()
02328         /// - AK::SoundEngine::LoadBank()
02329         /// - \ref soundengine_banks
02330         /// - \ref sdk_bank_training
02331         AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )( 
02332             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02333             const wchar_t**     in_ppszString,          ///< Array of event names
02334             AkUInt32            in_uNumEvent            ///< Number of events in the array
02335             );
02336 #endif //AK_SUPPORT_WCHAR
02337 
02338         /// Prepare or un-prepare events synchronously.\n
02339         /// The Events are identified by strings and converted to IDs internally
02340         /// (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02341         /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s) 
02342         /// that contain the Events and structures. When a request is posted to the
02343         /// Bank Manager consumer thread, it will resolve all dependencies needed to 
02344         /// successfully post the specified Events and load the required loose media files. 
02345         /// \aknote Before version 2015.1, the required media files could be included
02346         /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
02347         /// however, PrepareEvent() now only looks for loose media files.
02348         /// \endaknote
02349         /// The function returns when the request is completely processed.
02350         /// \return 
02351         /// - AK_Success: Prepare/un-prepare successful.
02352         /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
02353         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
02354         /// - AK_BankReadError: I/O error.
02355         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
02356         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
02357         /// - AK_InvalidFile: File specified could not be opened.
02358         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
02359         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
02360         /// \remarks
02361         /// Whenever at least one event fails to be resolved, the actions performed for all 
02362         /// other events are cancelled.
02363         /// \sa
02364         /// - AK::SoundEngine::PrepareEvent()
02365         /// - AK::SoundEngine::ClearPreparedEvents()
02366         /// - AK::SoundEngine::GetIDFromString()
02367         /// - AK::SoundEngine::LoadBank()
02368         /// - \ref soundengine_banks
02369         /// - \ref sdk_bank_training
02370         AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )( 
02371             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02372             const char**        in_ppszString,          ///< Array of event names
02373             AkUInt32            in_uNumEvent            ///< Number of events in the array
02374             );
02375 
02376         /// Prepare or un-prepare events synchronously (by ID).
02377         /// The Events are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02378         /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s) 
02379         /// that contain the Events and structures. When a request is posted to the
02380         /// Bank Manager consumer thread, it will resolve all dependencies needed to 
02381         /// successfully post the specified Events and load the required loose media files. 
02382         /// \aknote Before version 2015.1, the required media files could be included
02383         /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
02384         /// however, PrepareEvent() now only looks for loose media files.
02385         /// \endaknote
02386         /// The function returns when the request is completely processed.
02387         /// \return 
02388         /// - AK_Success: Prepare/un-prepare successful.
02389         /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
02390         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
02391         /// - AK_BankReadError: I/O error.
02392         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
02393         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
02394         /// - AK_InvalidFile: File specified could not be opened.
02395         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
02396         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
02397         /// \remarks
02398         /// Whenever at least one event fails to be resolved, the actions performed for all 
02399         /// other events are cancelled.
02400         /// \sa
02401         /// - AK::SoundEngine::PrepareEvent()
02402         /// - AK::SoundEngine::ClearPreparedEvents()
02403         /// - AK::SoundEngine::GetIDFromString()
02404         /// - AK::SoundEngine::LoadBank()
02405         /// - \ref soundengine_banks
02406         /// - \ref sdk_bank_training
02407         AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )( 
02408             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02409             AkUniqueID*         in_pEventID,            ///< Array of event IDs
02410             AkUInt32            in_uNumEvent            ///< Number of event IDs in the array
02411             );
02412 
02413 #ifdef AK_SUPPORT_WCHAR
02414         /// Prepare or un-prepare an event asynchronously (by Unicode string).
02415         /// The Events are identified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02416         /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s) 
02417         /// that contain the Events and structures. When a request is posted to the
02418         /// Bank Manager consumer thread, it will resolve all dependencies needed to 
02419         /// successfully post the specified Events and load the required loose media files. 
02420         /// \aknote Before version 2015.1, the required media files could be included
02421         /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
02422         /// however, PrepareEvent() now only looks for loose media files.
02423         /// \endaknote
02424         /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
02425         /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
02426         /// \remarks
02427         /// Whenever at least one event fails to be resolved, the actions performed for all 
02428         /// other events are cancelled.
02429         /// \sa
02430         /// - AK::SoundEngine::PrepareEvent()
02431         /// - AK::SoundEngine::ClearPreparedEvents()
02432         /// - AK::SoundEngine::GetIDFromString()
02433         /// - AK::SoundEngine::LoadBank()
02434         /// - AkBankCallbackFunc
02435         /// - \ref soundengine_banks
02436         /// - \ref sdk_bank_training
02437         AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )( 
02438             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02439             const wchar_t**     in_ppszString,          ///< Array of event names
02440             AkUInt32            in_uNumEvent,           ///< Number of events in the array
02441             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02442             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02443             );
02444 #endif //AK_SUPPORT_WCHAR
02445 
02446         /// Prepare or un-prepare an event asynchronously.
02447         /// The Events are identified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02448         /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s) 
02449         /// that contain the Events and structures. When a request is posted to the
02450         /// Bank Manager consumer thread, it will resolve all dependencies needed to 
02451         /// successfully post the specified Events and load the required loose media files. 
02452         /// \aknote Before version 2015.1, the required media files could be included
02453         /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
02454         /// however, PrepareEvent() now only looks for loose media files.
02455         /// \endaknote
02456         /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
02457         /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
02458         /// \remarks
02459         /// Whenever at least one event fails to be resolved, the actions performed for all 
02460         /// other events are cancelled.
02461         /// \sa
02462         /// - AK::SoundEngine::PrepareEvent()
02463         /// - AK::SoundEngine::ClearPreparedEvents()
02464         /// - AK::SoundEngine::GetIDFromString()
02465         /// - AK::SoundEngine::LoadBank()
02466         /// - AkBankCallbackFunc
02467         /// - \ref soundengine_banks
02468         /// - \ref sdk_bank_training
02469         AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )( 
02470             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02471             const char**        in_ppszString,          ///< Array of event names 
02472             AkUInt32            in_uNumEvent,           ///< Number of events in the array
02473             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02474             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02475             );
02476 
02477         /// Prepare or un-prepare events asynchronously (by ID).\n
02478         /// The Events are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02479         /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s) 
02480         /// that contain the Events and structures. When a request is posted to the
02481         /// Bank Manager consumer thread, it will resolve all dependencies needed to 
02482         /// successfully post the specified Events and load the required loose media files. 
02483         /// \aknote Before version 2015.1, the required media files could be included
02484         /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
02485         /// however, PrepareEvent() now only looks for loose media files.
02486         /// \endaknote
02487         /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
02488         /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
02489         /// \remarks
02490         /// Whenever at least one event fails to be resolved, the actions performed for all 
02491         /// other events are cancelled.
02492         /// \sa
02493         /// - AK::SoundEngine::PrepareEvent()
02494         /// - AK::SoundEngine::ClearPreparedEvents()
02495         /// - AK::SoundEngine::GetIDFromString()
02496         /// - AK::SoundEngine::LoadBank()
02497         /// - AkBankCallbackFunc
02498         /// - \ref soundengine_banks
02499         /// - \ref sdk_bank_training
02500         AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )( 
02501             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02502             AkUniqueID*         in_pEventID,            ///< Array of event IDs
02503             AkUInt32            in_uNumEvent,           ///< Number of event IDs in the array
02504             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02505             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02506             );
02507 
02508         /// Indicate the location of a specific Media ID in memory
02509         /// The sources are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02510         /// \return AK_Success if operation was successful, AK_InvalidParameter if in_pSourceSettings is invalid, and AK_Fail otherwise.
02511         AK_EXTERNAPIFUNC( AKRESULT, SetMedia )( 
02512             AkSourceSettings *  in_pSourceSettings,     ///< Array of Source Settings
02513             AkUInt32            in_uNumSourceSettings   ///< Number of Source Settings in the array
02514             );
02515 
02516         /// Remove the specified source from the list of loaded media.
02517         /// The sources are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02518         /// \return AK_Success if operation was successful, AK_InvalidParameter if in_pSourceSettings is invalid, and AK_Fail otherwise.
02519         AK_EXTERNAPIFUNC( AKRESULT, UnsetMedia )( 
02520             AkSourceSettings *  in_pSourceSettings,     ///< Array of Source Settings
02521             AkUInt32            in_uNumSourceSettings   ///< Number of Source Settings in the array
02522             );
02523 
02524 #ifdef AK_SUPPORT_WCHAR
02525         /// Prepare or un-prepare game syncs synchronously (by Unicode string).\n
02526         /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02527         /// The game syncs definitions must already exist in the sound engine by having
02528         /// explicitly loaded the bank(s) that contain them (with LoadBank()).
02529         /// A request is posted to the Bank Manager consumer thread. It will resolve all 
02530         /// dependencies needed to successfully set this game sync group to one of the
02531         /// game sync values specified, and load the required banks, if applicable. 
02532         /// The function returns when the request has been completely processed. 
02533         /// \return 
02534         /// - AK_Success: Prepare/un-prepare successful.
02535         /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
02536         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
02537         /// - AK_BankReadError: I/O error.
02538         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
02539         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
02540         /// - AK_InvalidFile: File specified could not be opened.
02541         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
02542         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
02543         /// \remarks
02544         /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation 
02545         /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
02546         /// so you never need to call this function.
02547         /// \sa 
02548         /// - AK::SoundEngine::GetIDFromString()
02549         /// - AK::SoundEngine::PrepareEvent()
02550         /// - AK::SoundEngine::LoadBank()
02551         /// - AkInitSettings
02552         /// - \ref soundengine_banks
02553         /// - \ref sdk_bank_training
02554         AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
02555             PreparationType in_PreparationType,         ///< Preparation type ( Preparation_Load or Preparation_Unload )
02556             AkGroupType     in_eGameSyncType,           ///< The type of game sync.
02557             const wchar_t*  in_pszGroupName,            ///< The state group Name or the Switch Group Name.
02558             const wchar_t** in_ppszGameSyncName,        ///< The specific ID of the state to either support or not support.
02559             AkUInt32        in_uNumGameSyncs            ///< The number of game sync in the string array.
02560             );
02561 #endif //AK_SUPPORT_WCHAR
02562 
02563         /// Prepare or un-prepare game syncs synchronously.\n
02564         /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02565         /// The game syncs definitions must already exist in the sound engine by having
02566         /// explicitly loaded the bank(s) that contain them (with LoadBank()).
02567         /// A request is posted to the Bank Manager consumer thread. It will resolve all 
02568         /// dependencies needed to successfully set this game sync group to one of the
02569         /// game sync values specified, and load the required banks, if applicable. 
02570         /// The function returns when the request has been completely processed. 
02571         /// \return 
02572         /// - AK_Success: Prepare/un-prepare successful.
02573         /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
02574         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
02575         /// - AK_BankReadError: I/O error.
02576         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
02577         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
02578         /// - AK_InvalidFile: File specified could not be opened.
02579         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
02580         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
02581         /// \remarks
02582         /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation 
02583         /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
02584         /// so you never need to call this function.
02585         /// \sa 
02586         /// - AK::SoundEngine::GetIDFromString()
02587         /// - AK::SoundEngine::PrepareEvent()
02588         /// - AK::SoundEngine::LoadBank()
02589         /// - AkInitSettings
02590         /// - \ref soundengine_banks
02591         /// - \ref sdk_bank_training
02592         AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
02593             PreparationType in_PreparationType,         ///< Preparation type ( Preparation_Load or Preparation_Unload )
02594             AkGroupType     in_eGameSyncType,           ///< The type of game sync.
02595             const char*     in_pszGroupName,            ///< The state group Name or the Switch Group Name.
02596             const char**    in_ppszGameSyncName,        ///< The specific ID of the state to either support or not support.
02597             AkUInt32        in_uNumGameSyncs            ///< The number of game sync in the string array.
02598             );
02599 
02600         /// Prepare or un-prepare game syncs synchronously (by ID).\n
02601         /// The group and game syncs are specified by ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02602         /// The game syncs definitions must already exist in the sound engine by having
02603         /// explicitly loaded the bank(s) that contain them (with LoadBank()).
02604         /// A request is posted to the Bank Manager consumer thread. It will resolve all 
02605         /// dependencies needed to successfully set this game sync group to one of the
02606         /// game sync values specified, and load the required banks, if applicable. 
02607         /// The function returns when the request has been completely processed. 
02608         /// \return 
02609         /// - AK_Success: Prepare/un-prepare successful.
02610         /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
02611         /// - AK_InsufficientMemory: Insufficient memory to store bank data.
02612         /// - AK_BankReadError: I/O error.
02613         /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 
02614         /// you used to generate the SoundBanks matches that of the SDK you are currently using.
02615         /// - AK_InvalidFile: File specified could not be opened.
02616         /// - AK_InvalidParameter: Invalid parameter, invalid memory alignment.     
02617         /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
02618         /// \remarks
02619         /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation 
02620         /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
02621         /// so you never need to call this function.
02622         /// \sa 
02623         /// - AK::SoundEngine::GetIDFromString()
02624         /// - AK::SoundEngine::PrepareEvent()
02625         /// - AK::SoundEngine::LoadBank()
02626         /// - AkInitSettings
02627         /// - \ref soundengine_banks
02628         /// - \ref sdk_bank_training
02629         AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
02630             PreparationType in_PreparationType,         ///< Preparation type ( Preparation_Load or Preparation_Unload )
02631             AkGroupType     in_eGameSyncType,           ///< The type of game sync.
02632             AkUInt32        in_GroupID,                 ///< The state group ID or the Switch Group ID.
02633             AkUInt32*       in_paGameSyncID,            ///< Array of ID of the game syncs to either support or not support.
02634             AkUInt32        in_uNumGameSyncs            ///< The number of game sync ID in the array.
02635             );
02636 
02637 #ifdef AK_SUPPORT_WCHAR
02638         /// Prepare or un-prepare game syncs asynchronously (by Unicode string).\n
02639         /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02640         /// The game syncs definitions must already exist in the sound engine by having
02641         /// explicitly loaded the bank(s) that contain them (with LoadBank()).
02642         /// A request is posted to the Bank Manager consumer thread. It will resolve all 
02643         /// dependencies needed to successfully set this game sync group to one of the
02644         /// game sync values specified, and load the required banks, if applicable. 
02645         /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
02646         /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
02647         /// \remarks
02648         /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation 
02649         /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
02650         /// so you never need to call this function.
02651         /// \sa 
02652         /// - AK::SoundEngine::GetIDFromString()
02653         /// - AK::SoundEngine::PrepareEvent()
02654         /// - AK::SoundEngine::LoadBank()
02655         /// - AkInitSettings
02656         /// - AkBankCallbackFunc
02657         /// - \ref soundengine_banks
02658         /// - \ref sdk_bank_training
02659         AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
02660             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02661             AkGroupType         in_eGameSyncType,       ///< The type of game sync.
02662             const wchar_t*      in_pszGroupName,        ///< The state group Name or the Switch Group Name.
02663             const wchar_t**     in_ppszGameSyncName,    ///< The specific ID of the state to either support or not support.
02664             AkUInt32            in_uNumGameSyncs,       ///< The number of game sync in the string array.
02665             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02666             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02667             );
02668 #endif //AK_SUPPORT_WCHAR
02669 
02670         /// Prepare or un-prepare game syncs asynchronously.\n
02671         /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02672         /// The game syncs definitions must already exist in the sound engine by having
02673         /// explicitly loaded the bank(s) that contain them (with LoadBank()).
02674         /// A request is posted to the Bank Manager consumer thread. It will resolve all 
02675         /// dependencies needed to successfully set this game sync group to one of the
02676         /// game sync values specified, and load the required banks, if applicable. 
02677         /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
02678         /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
02679         /// \remarks
02680         /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation 
02681         /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
02682         /// so you never need to call this function.
02683         /// \sa 
02684         /// - AK::SoundEngine::GetIDFromString()
02685         /// - AK::SoundEngine::PrepareEvent()
02686         /// - AK::SoundEngine::LoadBank()
02687         /// - AkInitSettings
02688         /// - AkBankCallbackFunc
02689         /// - \ref soundengine_banks
02690         /// - \ref sdk_bank_training
02691         AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
02692             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02693             AkGroupType         in_eGameSyncType,       ///< The type of game sync.
02694             const char*         in_pszGroupName,        ///< The state group Name or the Switch Group Name.
02695             const char**        in_ppszGameSyncName,    ///< The specific ID of the state to either support or not support.
02696             AkUInt32            in_uNumGameSyncs,       ///< The number of game sync in the string array.
02697             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02698             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02699             );
02700 
02701         /// Prepare or un-prepare game syncs asynchronously (by ID).\n
02702         /// The group and game syncs are specified by ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
02703         /// The game syncs definitions must already exist in the sound engine by having
02704         /// explicitly loaded the bank(s) that contain them (with LoadBank()).
02705         /// A request is posted to the Bank Manager consumer thread. It will resolve all 
02706         /// dependencies needed to successfully set this game sync group to one of the
02707         /// game sync values specified, and load the required banks, if applicable. 
02708         /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
02709         /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
02710         /// \remarks
02711         /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation 
02712         /// set to true. When set to false, the sound engine automatically prepares all Game Syncs when preparing Events,
02713         /// so you never need to call this function.
02714         /// \sa 
02715         /// - AK::SoundEngine::GetIDFromString()
02716         /// - AK::SoundEngine::PrepareEvent()
02717         /// - AK::SoundEngine::LoadBank()
02718         /// - AkInitSettings
02719         /// - AkBankCallbackFunc
02720         /// - \ref soundengine_banks
02721         /// - \ref sdk_bank_training
02722         AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
02723             PreparationType     in_PreparationType,     ///< Preparation type ( Preparation_Load or Preparation_Unload )
02724             AkGroupType         in_eGameSyncType,       ///< The type of game sync.
02725             AkUInt32            in_GroupID,             ///< The state group ID or the Switch Group ID.
02726             AkUInt32*           in_paGameSyncID,        ///< Array of ID of the Game Syncs to either support or not support.
02727             AkUInt32            in_uNumGameSyncs,       ///< The number of game sync ID in the array.
02728             AkBankCallbackFunc  in_pfnBankCallback,     ///< Callback function
02729             void *              in_pCookie              ///< Callback cookie (reserved to user, passed to the callback function)
02730             );
02731 
02732         //@}
02733 
02734 
02735         ////////////////////////////////////////////////////////////////////////
02736         /// @name Listeners
02737         //@{
02738 
02739         /// Set a single game object's active listeners.
02740         /// By default, all new game objects have no active listeners, but this behavior can be overridden with \c SetDefaultListeners(). Inactive listeners are not computed.
02741         /// \return Always returns AK_Success
02742         /// \sa 
02743         /// - AK::SoundEngine::SetDefaultListeners
02744         /// - \ref soundengine_listeners
02745         AK_EXTERNAPIFUNC( AKRESULT, SetListeners )(
02746             AkGameObjectID in_emitterGameObj,           ///< Emitter game object.
02747             const AkGameObjectID* in_pListenerGameObjs, ///< Array of listener game object IDs that will be activated for in_GameObj.  Game objects must have been previously registered.
02748             AkUInt32 in_uNumListeners                   ///< Length of array
02749             );
02750 
02751         /// Set the default active listeners for all subsequent game objects that are registered.
02752         /// \return Always returns AK_Success
02753         /// \sa 
02754         /// - \ref soundengine_listeners
02755         AK_EXTERNAPIFUNC(AKRESULT, SetDefaultListeners)(
02756             const AkGameObjectID* in_pListenerObjs, ///< Array of listener game object IDs that will be activated for subsequent registrations.  Game objects must have been previously registered.
02757             AkUInt32 in_uNumListeners               ///< Length of array
02758             );
02759 
02760         /// Reset 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>.
02761         /// \return Always returns AK_Success
02762         /// \sa 
02763         /// - AK::SoundEngine::SetListeners
02764         /// - AK::SoundEngine::SetDefaultListeners
02765         /// - AK::SoundEngine::SetGameObjectOutputBusVolume
02766         /// - \ref soundengine_listeners
02767         AK_EXTERNAPIFUNC(AKRESULT, ResetListenersToDefault)(
02768             AkGameObjectID in_emitterGameObj    ///< Emitter game object.
02769             );
02770 
02771         /// Set a listener's spatialization parameters. This let you define listener-specific 
02772         /// volume offsets for each audio channel.
02773         /// If \c in_bSpatialized is false, only \c in_pVolumeOffsets is used for this listener (3D positions 
02774         /// have no effect on the speaker distribution). Otherwise, \c in_pVolumeOffsets is added to the speaker
02775         /// distribution computed for this listener.
02776         /// Use helper functions of \c AK::SpeakerVolumes to manipulate the vector of volume offsets in_pVolumeOffsets.
02777         /// 
02778         /// If a sound is mixed into a bus that has a different speaker configuration than in_channelConfig,
02779         /// standard up/downmix rules apply.
02780         /// \return \c AK_Success if message was successfully posted to sound engine queue, \c AK_Fail otherwise.
02781         /// \sa 
02782         /// - \ref soundengine_listeners_spatial
02783         AK_EXTERNAPIFUNC( AKRESULT, SetListenerSpatialization )(
02784             AkGameObjectID in_uListenerID,              ///< Listener game object ID
02785             bool in_bSpatialized,                       ///< Spatialization toggle (True : enable spatialization, False : disable spatialization)
02786             AkChannelConfig in_channelConfig,           ///< Channel configuration associated with volumes in_pVolumeOffsets. Ignored if in_pVolumeOffsets is NULL.
02787             AK::SpeakerVolumes::VectorPtr in_pVolumeOffsets = NULL  ///< Per-speaker volume offset, in dB. See AkSpeakerVolumes.h for how to manipulate this vector.
02788             );
02789 
02790         /// Set a listener's ability to listen to audio and motion events.
02791         /// By default, all listeners are enabled for audio and disabled for motion.  
02792         /// \aknote If your game doesn't use Motion, you should NOT need to use this function. 
02793         /// This function isn't a global "activate" switch on the listeners.  Use SetListeners properly to
02794         /// control which listeners are used in your game. \endaknote
02795         /// \return Always returns AK_Success
02796         /// \sa 
02797         /// - \ref motion_player_management
02798         /// - AK::SoundEngine::SetListeners
02799         AK_EXTERNAPIFUNC( AKRESULT, SetListenerPipeline )(
02800             AkGameObjectID in_uListenerID,          ///< Listener game object ID
02801             bool in_bAudio,                         ///< True=Listens to audio events (by default it is true)
02802             bool in_bMotion                         ///< True=Listens to motion events (by default it is false)
02803             );
02804 
02805 
02806         //@}
02807 
02808 
02809         ////////////////////////////////////////////////////////////////////////
02810         /// @name Game Syncs
02811         //@{
02812 
02813         /// Set the value of a real-time parameter control (by ID).
02814         /// With this function, you may set a game parameter value on global scope or on game object scope. 
02815         /// Game object scope supersedes global scope. Game parameter values set on global scope are applied to all 
02816         /// game objects that not yet registered, or already registered but not overridden with a value on game object scope.
02817         /// To set a game parameter value on global scope, pass AK_INVALID_GAME_OBJECT as the game object. 
02818         /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero 
02819         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
02820         /// according to the interpolation curve. If you call SetRTPCValue() with in_uValueChangeDuration = 0 in the 
02821         /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this 
02822         /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
02823         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
02824         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
02825         /// \return Always AK_Success
02826         /// \sa 
02827         /// - \ref soundengine_rtpc
02828         /// - AK::SoundEngine::GetIDFromString()
02829         AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )( 
02830             AkRtpcID in_rtpcID,                                     ///< ID of the game parameter
02831             AkRtpcValue in_value,                                   ///< Value to set
02832             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
02833             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards in_value
02834             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
02835             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.
02836             );
02837 
02838 #ifdef AK_SUPPORT_WCHAR
02839         /// Set the value of a real-time parameter control (by Unicode string name).
02840         /// With this function, you may set a game parameter value on global scope or on game object scope. 
02841         /// Game object scope supersedes global scope. Game parameter values set on global scope are applied to all 
02842         /// game objects that not yet registered, or already registered but not overridden with a value on game object scope.
02843         /// To set a game parameter value on global scope, pass AK_INVALID_GAME_OBJECT as the game object. 
02844         /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero 
02845         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
02846         /// according to the interpolation curve. If you call SetRTPCValue() with in_uValueChangeDuration = 0 in the 
02847         /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this 
02848         /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
02849         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
02850         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
02851         /// \return 
02852         /// - AK_Success if successful
02853         /// - AK_IDNotFound if in_pszRtpcName is NULL.
02854         /// \aknote Strings are case-insensitive. \endaknote
02855         /// \sa 
02856         /// - \ref soundengine_rtpc
02857         AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )( 
02858             const wchar_t* in_pszRtpcName,                          ///< Name of the game parameter
02859             AkRtpcValue in_value,                                   ///< Value to set
02860             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
02861             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards in_value
02862             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
02863             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.
02864             );
02865 #endif //AK_SUPPORT_WCHAR
02866 
02867         /// Set the value of a real-time parameter control.
02868         /// With this function, you may set a game parameter value on global scope or on game object scope. 
02869         /// Game object scope supersedes global scope. Game parameter values set on global scope are applied to all 
02870         /// game objects that not yet registered, or already registered but not overridden with a value on game object scope.
02871         /// To set a game parameter value on global scope, pass AK_INVALID_GAME_OBJECT as the game object. 
02872         /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero 
02873         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
02874         /// according to the interpolation curve. If you call SetRTPCValue() with in_uValueChangeDuration = 0 in the 
02875         /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this 
02876         /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
02877         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
02878         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
02879         /// \return 
02880         /// - AK_Success if successful
02881         /// - AK_IDNotFound if in_pszRtpcName is NULL.
02882         /// \aknote Strings are case-insensitive. \endaknote
02883         /// \sa 
02884         /// - \ref soundengine_rtpc
02885         AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )( 
02886             const char* in_pszRtpcName,                             ///< Name of the game parameter
02887             AkRtpcValue in_value,                                   ///< Value to set
02888             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
02889             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards in_value
02890             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
02891             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.
02892             );
02893 
02894         /// Set the value of a real-time parameter control (by ID).
02895         /// With this function, you may set a game parameter value on playing id scope. 
02896         /// Playing id scope supersedes both game object scope and global scope. 
02897         /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero 
02898         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
02899         /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the 
02900         /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this 
02901         /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
02902         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
02903         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
02904         /// \return Always AK_Success
02905         /// \sa 
02906         /// - \ref soundengine_rtpc
02907         /// - AK::SoundEngine::GetIDFromString()
02908         AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )( 
02909             AkRtpcID in_rtpcID,                                     ///< ID of the game parameter
02910             AkRtpcValue in_value,                                   ///< Value to set
02911             AkPlayingID in_playingID,                               ///< Associated playing ID
02912             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards in_value
02913             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
02914             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.
02915             );
02916 
02917 #ifdef AK_SUPPORT_WCHAR
02918         /// Set the value of a real-time parameter control (by Unicode string name).
02919         /// With this function, you may set a game parameter value on playing id scope. 
02920         /// Playing id scope supersedes both game object scope and global scope. 
02921         /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero 
02922         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
02923         /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the 
02924         /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this 
02925         /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
02926         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
02927         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
02928         /// \return Always AK_Success
02929         /// \sa 
02930         /// - \ref soundengine_rtpc
02931         /// - AK::SoundEngine::GetIDFromString()
02932         AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )( 
02933             const wchar_t* in_pszRtpcName,                          ///< Name of the game parameter
02934             AkRtpcValue in_value,                                   ///< Value to set
02935             AkPlayingID in_playingID,                               ///< Associated playing ID
02936             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards in_value
02937             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
02938             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.
02939             );
02940 #endif //AK_SUPPORT_WCHAR
02941         
02942         /// Set the value of a real-time parameter control (by string name).
02943         /// With this function, you may set a game parameter value on playing id scope. 
02944         /// Playing id scope supersedes both game object scope and global scope. 
02945         /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero 
02946         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
02947         /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the 
02948         /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this 
02949         /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
02950         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
02951         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
02952         /// \return Always AK_Success
02953         /// \sa 
02954         /// - \ref soundengine_rtpc
02955         /// - AK::SoundEngine::GetIDFromString()
02956         AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )( 
02957             const char* in_pszRtpcName,                             ///< Name of the game parameter
02958             AkRtpcValue in_value,                                   ///< Value to set
02959             AkPlayingID in_playingID,                               ///< Associated playing ID
02960             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards in_value
02961             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
02962             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.
02963             );
02964 
02965         /// Reset the value of the game parameter to its default value, as specified in the Wwise project.
02966         /// With this function, you may reset a game parameter to its default value on global scope or on game object scope. 
02967         /// Game object scope supersedes global scope. Game parameter values reset on global scope are applied to all 
02968         /// game objects that were not overridden with a value on game object scope.
02969         /// To reset a game parameter value on global scope, pass AK_INVALID_GAME_OBJECT as the game object. 
02970         /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero 
02971         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
02972         /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the 
02973         /// middle of an interpolation, the interpolation stops and the new value is set directly. 
02974         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
02975         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
02976         /// \return Always AK_Success
02977         /// \sa 
02978         /// - \ref soundengine_rtpc
02979         /// - AK::SoundEngine::GetIDFromString()
02980         /// - AK::SoundEngine::SetRTPCValue()
02981         AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
02982             AkRtpcID in_rtpcID,                                     ///< ID of the game parameter
02983             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
02984             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards its default value
02985             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
02986             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.
02987             );
02988 
02989 #ifdef AK_SUPPORT_WCHAR
02990         /// Reset the value of the game parameter to its default value, as specified in the Wwise project.
02991         /// With this function, you may reset a game parameter to its default value on global scope or on game object scope. 
02992         /// Game object scope supersedes global scope. Game parameter values reset on global scope are applied to all 
02993         /// game objects that were not overridden with a value on game object scope.
02994         /// To reset a game parameter value on global scope, pass AK_INVALID_GAME_OBJECT as the game object. 
02995         /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero 
02996         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
02997         /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the 
02998         /// middle of an interpolation, the interpolation stops and the new value is set directly. 
02999         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
03000         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
03001         /// \return 
03002         /// - AK_Success if successful
03003         /// - AK_IDNotFound if in_pszParamName is NULL.
03004         /// \aknote Strings are case-insensitive. \endaknote
03005         /// \sa 
03006         /// - \ref soundengine_rtpc
03007         /// - AK::SoundEngine::SetRTPCValue()
03008         AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
03009             const wchar_t* in_pszRtpcName,                          ///< Name of the game parameter
03010             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
03011             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards its default value
03012             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
03013             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.
03014             );
03015 #endif //AK_SUPPORT_WCHAR
03016 
03017         /// Reset the value of the game parameter to its default value, as specified in the Wwise project.
03018         /// With this function, you may reset a game parameter to its default value on global scope or on game object scope. 
03019         /// Game object scope supersedes global scope. Game parameter values reset on global scope are applied to all 
03020         /// game objects that were not overridden with a value on game object scope.
03021         /// To reset a game parameter value on global scope, pass AK_INVALID_GAME_OBJECT as the game object. 
03022         /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero 
03023         /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally 
03024         /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the 
03025         /// middle of an interpolation, the interpolation stops and the new value is set directly. 
03026         /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and 
03027         /// \ref soundengine_rtpc_effects for more details on RTPC scope.
03028         /// \return 
03029         /// - AK_Success if successful
03030         /// - AK_IDNotFound if in_pszParamName is NULL.
03031         /// \aknote Strings are case-insensitive. \endaknote
03032         /// \sa 
03033         /// - \ref soundengine_rtpc
03034         /// - AK::SoundEngine::SetRTPCValue()
03035         AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
03036             const char* in_pszRtpcName,                             ///< Name of the game parameter
03037             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
03038             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards its default value
03039             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
03040             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.
03041             );
03042 
03043         /// Set the state of a switch group (by IDs).
03044         /// \return Always returns AK_Success
03045         /// \sa 
03046         /// - \ref soundengine_switch
03047         /// - AK::SoundEngine::GetIDFromString()
03048         AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )( 
03049             AkSwitchGroupID in_switchGroup,             ///< ID of the switch group
03050             AkSwitchStateID in_switchState,             ///< ID of the switch
03051             AkGameObjectID in_gameObjectID              ///< Associated game object ID
03052             );
03053 
03054 #ifdef AK_SUPPORT_WCHAR
03055         /// Set the state of a switch group (by Unicode string names).
03056         /// \return 
03057         /// - AK_Success if successful
03058         /// - AK_IDNotFound if the switch or switch group name was not resolved to an existing ID\n
03059         /// Make sure that the banks were generated with the "include string" option.
03060         /// \aknote Strings are case-insensitive. \endaknote
03061         /// \sa 
03062         /// - \ref soundengine_switch
03063         AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )( 
03064             const wchar_t* in_pszSwitchGroup,           ///< Name of the switch group
03065             const wchar_t* in_pszSwitchState,           ///< Name of the switch
03066             AkGameObjectID in_gameObjectID              ///< Associated game object ID
03067             );
03068 #endif //AK_SUPPORT_WCHAR
03069 
03070         /// Set the state of a switch group.
03071         /// \return 
03072         /// - AK_Success if successful
03073         /// - AK_IDNotFound if the switch or switch group name was not resolved to an existing ID\n
03074         /// Make sure that the banks were generated with the "include string" option.
03075         /// \aknote Strings are case-insensitive. \endaknote
03076         /// \sa 
03077         /// - \ref soundengine_switch
03078         AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )( 
03079             const char* in_pszSwitchGroup,              ///< Name of the switch group
03080             const char* in_pszSwitchState,              ///< Name of the switch
03081             AkGameObjectID in_gameObjectID              ///< Associated game object ID
03082             );
03083 
03084         /// Post the specified trigger (by IDs).
03085         /// \return Always returns AK_Success
03086         /// \sa 
03087         /// - \ref soundengine_triggers
03088         /// - AK::SoundEngine::GetIDFromString()
03089         AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )( 
03090             AkTriggerID     in_triggerID,               ///< ID of the trigger
03091             AkGameObjectID  in_gameObjectID             ///< Associated game object ID
03092             );
03093 
03094 #ifdef AK_SUPPORT_WCHAR
03095         /// Post the specified trigger (by Unicode string name).
03096         /// \return 
03097         /// - AK_Success if successful
03098         /// - AK_IDNotFound if the trigger name was not resolved to an existing ID\n
03099         /// Make sure that the banks were generated with the "include string" option.
03100         /// \aknote Strings are case-insensitive. \endaknote
03101         /// \sa 
03102         /// - \ref soundengine_triggers
03103         AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )( 
03104             const wchar_t* in_pszTrigger,               ///< Name of the trigger
03105             AkGameObjectID in_gameObjectID              ///< Associated game object ID
03106             );
03107 #endif //AK_SUPPORT_WCHAR
03108 
03109         /// Post the specified trigger.
03110         /// \return 
03111         /// - AK_Success if successful
03112         /// - AK_IDNotFound if the trigger name was not resolved to an existing ID\n
03113         /// Make sure that the banks were generated with the "include string" option.
03114         /// \aknote Strings are case-insensitive. \endaknote
03115         /// \sa 
03116         /// - \ref soundengine_triggers
03117         AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )( 
03118             const char* in_pszTrigger,                  ///< Name of the trigger
03119             AkGameObjectID in_gameObjectID              ///< Associated game object ID
03120             );
03121 
03122         /// Set the state of a state group (by IDs).
03123         /// \return Always returns AK_Success
03124         /// \sa 
03125         /// - \ref soundengine_states
03126         /// - AK::SoundEngine::GetIDFromString()
03127         AK_EXTERNAPIFUNC( AKRESULT, SetState )( 
03128             AkStateGroupID in_stateGroup,               ///< ID of the state group
03129             AkStateID in_state                          ///< ID of the state
03130             );
03131 
03132 #ifdef AK_SUPPORT_WCHAR
03133         /// Set the state of a state group (by Unicode string names).
03134         /// \return 
03135         /// - AK_Success if successful
03136         /// - AK_IDNotFound if the state or state group name was not resolved to an existing ID\n
03137         /// Make sure that the banks were generated with the "include string" option.
03138         /// \aknote Strings are case-insensitive. \endaknote
03139         /// \sa 
03140         /// - \ref soundengine_states
03141         /// - AK::SoundEngine::GetIDFromString()
03142         AK_EXTERNAPIFUNC( AKRESULT, SetState )( 
03143             const wchar_t* in_pszStateGroup,                ///< Name of the state group
03144             const wchar_t* in_pszState                      ///< Name of the state
03145             );
03146 #endif //AK_SUPPORT_WCHAR
03147 
03148         /// Set the state of a state group.
03149         /// \return 
03150         /// - AK_Success if successful
03151         /// - AK_IDNotFound if the state or state group name was not resolved to an existing ID\n
03152         /// Make sure that the banks were generated with the "include string" option.
03153         /// \aknote Strings are case-insensitive. \endaknote
03154         /// \sa 
03155         /// - \ref soundengine_states
03156         /// - AK::SoundEngine::GetIDFromString()
03157         AK_EXTERNAPIFUNC( AKRESULT, SetState )( 
03158             const char* in_pszStateGroup,                   ///< Name of the state group
03159             const char* in_pszState                         ///< Name of the state
03160             );
03161 
03162         //@}
03163 
03164         ////////////////////////////////////////////////////////////////////////
03165         /// @name Environments
03166         //@{
03167 
03168         /// Set the auxiliary busses to route the specified game object
03169         /// The array size cannot exceed AK_MAX_AUX_PER_OBJ.
03170         /// To clear the game object's auxiliary sends, in_uNumSendValues must be 0.
03171         /// \aknote The actual maximum number of aux sends in which a game object can be is AK_MAX_AUX_PER_OBJ. \endaknote
03172         /// \aknote If an send control value is set to 0%, the effect won't be inserted at all, as if it wasn't part of the array.
03173         /// \sa 
03174         /// - \ref soundengine_environments
03175         /// - \ref soundengine_environments_dynamic_aux_bus_routing
03176         /// - \ref soundengine_environments_id_vs_string
03177         /// - AK::SoundEngine::GetIDFromString()
03178         /// \return 
03179         /// - AK_Success if successful
03180         /// - AK_InvalidParameter if the array size exceeds AK_MAX_AUX_PER_OBJ, or if a duplicated environment is found in the array
03181         AK_EXTERNAPIFUNC( AKRESULT, SetGameObjectAuxSendValues )( 
03182             AkGameObjectID      in_gameObjectID,        ///< Associated game object ID
03183             AkAuxSendValue*     in_aAuxSendValues,      ///< Variable-size array of AkAuxSendValue structures
03184                                                         ///< (it may be NULL if no environment must be set, and its size cannot exceed AK_MAX_AUX_PER_OBJ)
03185             AkUInt32            in_uNumSendValues       ///< The number of auxiliary busses at the pointer's address
03186                                                         ///< (it must be 0 if no environment is set, and can not exceed AK_MAX_AUX_PER_OBJ)
03187             );
03188 
03189         /// Register a callback to allow the game to modify or override the volume to be applied at the output of an audio bus.
03190         /// The callback must be registered once per bus ID.
03191         /// Call with in_pfnCallback = NULL to unregister.
03192         /// \aknote The bus in_busID needs to be a mixing bus.\endaknote
03193         /// \aknote Beware when using this callback on the Master Audio Bus: since the output of this bus is not a bus, but is instead a system end-point, AkSpeakerVolumeMatrixCallbackInfo::pMixerContext will be NULL. You cannot modify panning at the output of the Master Audio Bus.\endaknote
03194         /// \sa 
03195         /// - \ref goingfurther_speakermatrixcallback
03196         /// - \ref soundengine_environments
03197         /// - AkSpeakerVolumeMatrixCallbackInfo
03198         /// - AK::IAkMixerInputContext
03199         /// - AK::IAkMixerPluginContext
03200         /// \return 
03201         /// - AK_Success if successful
03202         AK_EXTERNAPIFUNC( AKRESULT, RegisterBusVolumeCallback )( 
03203             AkUniqueID in_busID,                        ///< Bus ID, as obtained by GetIDFromString( bus_name ).
03204             AkBusCallbackFunc in_pfnCallback            ///< Callback function.
03205             );
03206 
03207         /// Register 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 
03208         /// by querying the peak, RMS, True Peak and K-weighted power (according to loudness standard ITU BS.1770). See \ref goingfurther_speakermatrixcallback for an example.
03209         /// The callback must be registered once per bus ID.
03210         /// Call with in_pfnCallback = NULL to unregister.
03211         /// \aknote The bus in_busID needs to be a mixing bus.\endaknote
03212         /// \sa 
03213         /// - \ref goingfurther_speakermatrixcallback
03214         /// - AkBusMeteringCallbackFunc
03215         /// - AK::IAkMetering
03216         /// \return 
03217         /// - AK_Success if successful
03218         AK_EXTERNAPIFUNC( AKRESULT, RegisterBusMeteringCallback )( 
03219             AkUniqueID in_busID,                        ///< Bus ID, as obtained by GetIDFromString( bus_name ).
03220             AkBusMeteringCallbackFunc in_pfnCallback,   ///< Callback function.
03221             AkMeteringFlags in_eMeteringFlags           ///< Metering flags.
03222             );
03223 
03224         /// Set the output bus volume (direct) to be used for the specified game object.
03225         /// The control value is a number ranging from 0.0f to 1.0f.
03226         /// \sa 
03227         /// - \ref soundengine_environments
03228         /// - \ref soundengine_environments_setting_dry_environment
03229         /// - \ref soundengine_environments_id_vs_string
03230         /// \return Always returns AK_Success
03231         AK_EXTERNAPIFUNC( AKRESULT, SetGameObjectOutputBusVolume )( 
03232             AkGameObjectID      in_emitterObjID,        ///< Associated emitter game object ID
03233             AkGameObjectID      in_listenerObjID,       ///< Associated listener game object ID
03234             AkReal32            in_fControlValue        ///< A multiplier where 0 means silence and 1 means no change. 
03235                                                         ///< (Therefore, values between 0 and 1 will attenuate the sound, and values greater than 1 will amplify it.)
03236             );
03237 
03238         /// Set an effect ShareSet at the specified audio node and effect slot index.
03239         /// The target node cannot be a Bus, to set effects on a bus, use SetBusEffect() instead.
03240         /// \aknote The option "Override Parent" in 
03241         /// the Effect section in Wwise must be enabled for this node, otherwise the parent's effect will 
03242         /// still be the one in use and the call to SetActorMixerEffect will have no impact.
03243         /// \endaknote
03244         /// \return Always returns AK_Success
03245         AK_EXTERNAPIFUNC( AKRESULT, SetActorMixerEffect )( 
03246             AkUniqueID in_audioNodeID,                  ///< Can be a member of the Actor-Mixer or Interactive Music Hierarchy (not a bus).
03247             AkUInt32 in_uFXIndex,                       ///< Effect slot index (0-3)
03248             AkUniqueID in_shareSetID                    ///< ShareSet ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
03249             );
03250 
03251         /// Set an Effect ShareSet at the specified bus and Effect slot index.
03252         /// The Bus can either be an Audio Bus or an Auxiliary Bus.
03253         /// This adds a reference on the audio node to an existing ShareSet.
03254         /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
03255         /// Bus which does not have any Effects, or removing the last Effect on a currently playing bus.
03256         /// \endaknote
03257         /// \aknote This function will replace existing Effects on the node. If the target node is not at 
03258         /// the top of the hierarchy and is in the actor-mixer hierarchy, the option "Override Parent" in 
03259         /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will 
03260         /// still be the one in use and the call to SetBusEffect will have no impact.
03261         /// \endaknote
03262         /// \return Always returns AK_Success
03263         AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )( 
03264             AkUniqueID in_audioNodeID,                  ///< Bus Short ID.
03265             AkUInt32 in_uFXIndex,                       ///< Effect slot index (0-3)
03266             AkUniqueID in_shareSetID                    ///< ShareSet ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
03267             );
03268 
03269 #ifdef AK_SUPPORT_WCHAR
03270         /// Set an Effect ShareSet at the specified Bus and Effect slot index.
03271         /// The Bus can either be an Audio Bus or an Auxiliary Bus.
03272         /// This adds a reference on the audio node to an existing ShareSet.
03273         /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
03274         /// bus which does not have any Effects, or removing the last Effect on a currently playing Bus.
03275         /// \endaknote
03276         /// \aknote This function will replace existing Effects on the node. If the target node is not at 
03277         /// the top of the hierarchy and is in the Actor-Mixer Hierarchy, the option "Override Parent" in 
03278         /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will 
03279         /// still be the one in use and the call to SetBusEffect will have no impact.
03280         /// \endaknote
03281         /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
03282         AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )( 
03283             const wchar_t* in_pszBusName,               ///< Bus name
03284             AkUInt32 in_uFXIndex,                       ///< Effect slot index (0-3)
03285             AkUniqueID in_shareSetID                    ///< ShareSet ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
03286             );
03287 #endif //AK_SUPPORT_WCHAR
03288 
03289         /// Set an Effect ShareSet at the specified Bus and Effect slot index.
03290         /// The Bus can either be an Audio Bus or an Auxiliary Bus.
03291         /// This adds a reference on the audio node to an existing ShareSet.
03292         /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
03293         /// Bus which does not have any effects, or removing the last Effect on a currently playing bus.
03294         /// \endaknote
03295         /// \aknote This function will replace existing Effects on the node. If the target node is not at 
03296         /// the top of the hierarchy and is in the Actor-Mixer Hierarchy, the option "Override Parent" in 
03297         /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will 
03298         /// still be the one in use and the call to SetBusEffect will have no impact.
03299         /// \endaknote
03300         /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
03301         AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )( 
03302             const char* in_pszBusName,      ///< Bus name
03303             AkUInt32 in_uFXIndex,           ///< Effect slot index (0-3)
03304             AkUniqueID in_shareSetID        ///< ShareSet ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
03305             );
03306 
03307         /// Set a Mixer ShareSet at the specified bus.
03308         /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
03309         /// Bus which does not have any Effects or mixer, or removing the last mixer on a currently playing Bus.
03310         /// \endaknote
03311         /// \aknote This function will replace existing mixers on the node. 
03312         /// \endaknote
03313         /// \return Always returns AK_Success
03314         AK_EXTERNAPIFUNC( AKRESULT, SetMixer )( 
03315             AkUniqueID in_audioNodeID,                  ///< Bus Short ID.
03316             AkUniqueID in_shareSetID                    ///< ShareSet ID; pass AK_INVALID_UNIQUE_ID to remove.
03317             );
03318 
03319 #ifdef AK_SUPPORT_WCHAR
03320         /// Set a Mixer ShareSet at the specified bus.
03321         /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
03322         /// bus which does not have any effects nor mixer, or removing the last mixer on a currently playing bus.
03323         /// \endaknote
03324         /// \aknote This function will replace existing mixers on the node. 
03325         /// \endaknote
03326         /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
03327         AK_EXTERNAPIFUNC( AKRESULT, SetMixer )( 
03328             const wchar_t* in_pszBusName,               ///< Bus name
03329             AkUniqueID in_shareSetID                    ///< ShareSet ID; pass AK_INVALID_UNIQUE_ID to remove.
03330             );
03331 #endif //AK_SUPPORT_WCHAR
03332 
03333         /// Set a Mixer ShareSet at the specified bus.
03334         /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
03335         /// bus which does not have any effects nor mixer, or removing the last mixer on a currently playing bus.
03336         /// \endaknote
03337         /// \aknote This function will replace existing mixers on the node.
03338         /// \endaknote
03339         /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
03340         AK_EXTERNAPIFUNC( AKRESULT, SetMixer )( 
03341             const char* in_pszBusName,      ///< Bus name
03342             AkUniqueID in_shareSetID        ///< ShareSet ID; pass AK_INVALID_UNIQUE_ID to remove.
03343             );
03344 
03345         /// Force channel configuration for the specified bus.
03346         /// \aknote You cannot change the configuration of the master bus.\endaknote
03347         /// 
03348         /// \return Always returns AK_Success
03349         AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
03350             AkUniqueID in_audioNodeID,                  ///< Bus Short ID.
03351             AkChannelConfig in_channelConfig            ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
03352             );
03353 
03354 #ifdef AK_SUPPORT_WCHAR
03355         /// Force channel configuration for the specified bus.
03356         /// \aknote You cannot change the configuration of the master bus.\endaknote
03357         /// 
03358         /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
03359         AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
03360             const wchar_t* in_pszBusName,               ///< Bus name
03361             AkChannelConfig in_channelConfig            ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
03362             );
03363 #endif //AK_SUPPORT_WCHAR
03364 
03365         /// Force channel configuration for the specified bus.
03366         /// \aknote You cannot change the configuration of the master bus.\endaknote
03367         /// 
03368         /// \returns AK_IDNotFound is name not resolved, returns AK_Success otherwise.
03369         AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
03370             const char* in_pszBusName,                  ///< Bus name
03371             AkChannelConfig in_channelConfig            ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
03372             );
03373 
03374         /// Set a game object's obstruction and occlusion levels. If SetMultiplePositions were used, values are set for all positions.
03375         /// This function is used to affect how an object should be heard by a specific listener.
03376         /// \sa 
03377         /// - \ref soundengine_obsocc
03378         /// - \ref soundengine_environments
03379         /// \return Always returns AK_Success
03380         AK_EXTERNAPIFUNC( AKRESULT, SetObjectObstructionAndOcclusion )(  
03381             AkGameObjectID in_EmitterID,        ///< Emitter game object ID
03382             AkGameObjectID in_ListenerID,       ///< Listener game object ID
03383             AkReal32 in_fObstructionLevel,      ///< ObstructionLevel: [0.0f..1.0f]
03384             AkReal32 in_fOcclusionLevel         ///< OcclusionLevel: [0.0f..1.0f]
03385             );
03386 
03387         /// Set a game object's obstruction and occlusion level for each positions defined by SetMultiplePositions.
03388         /// This function differs from SetObjectObstructionAndOcclusion as a list of obstruction/occlusion pair is provided
03389         /// and each obstruction/occlusion pair will affect the corresponding position defined at the same index.
03390         /// \aknote In the case the number of obstruction/occlusion pairs is smaller than the number of positions, remaining positions' 
03391         /// obstrucion/occlusion values are set to 0.0. \endaknote
03392         /// \sa
03393         /// - \ref soundengine_obsocc
03394         /// - \ref soundengine_environments
03395         /// \return AK_Success if occlusion/obstruction values are successfully stored for this emitter
03396         AK_EXTERNAPIFUNC( AKRESULT, SetMultipleObstructionAndOcclusion )(
03397             AkGameObjectID in_EmitterID,                                        ///< Emitter game object ID
03398             AkGameObjectID in_uListenerID,                                      ///< Listener game object ID
03399             AkObstructionOcclusionValues* in_fObstructionOcclusionValues,       ///< Array of obstruction/occlusion pairs to apply
03400                                                                                 ///< ObstructionLevel: [0.0f..1.0f]
03401                                                                                 ///< OcclusionLevel: [0.0f..1.0f]
03402             AkUInt32 in_uNumOcclusionObstruction                                ///< Number of obstruction/occlusion pairs specified in the provided array
03403             );
03404 
03405         /// Save the playback history of container structures.
03406         /// This function will write history data for all currently loaded containers and instantiated game
03407         /// objects (for example, current position in Sequence containers and previously played elements in
03408         /// Random containers). 
03409         /// \remarks
03410         /// This function acquires the main audio lock, and may block the caller for several milliseconds.
03411         /// \sa 
03412         /// - AK::SoundEngine::SetContainerHistory()
03413         AK_EXTERNAPIFUNC( AKRESULT, GetContainerHistory)(
03414             AK::IWriteBytes * in_pBytes         ///< Pointer to IWriteBytes interface used to save the history.
03415             );
03416 
03417         /// Restore the playback history of container structures.
03418         /// This function will read history data from the passed-in stream reader interface, and apply it to all
03419         /// currently loaded containers and instantiated game objects. Game objects are matched by
03420         /// ID. History for unloaded structures and unknown game objects will be skipped.
03421         /// \remarks
03422         /// This function acquires the main audio lock, and may block the caller for several milliseconds.
03423         /// \sa 
03424         /// - AK::SoundEngine::GetContainerHistory()
03425         AK_EXTERNAPIFUNC(AKRESULT, SetContainerHistory)(
03426             AK::IReadBytes * in_pBytes          ///< Pointer to IReadBytes interface used to load the history.
03427             );
03428 
03429         //@}
03430         
03431         ////////////////////////////////////////////////////////////////////////
03432         /// @name Capture
03433         //@{
03434 
03435         /// Start recording the sound engine audio output. 
03436         /// StartOutputCapture outputs a wav file in the 5.1 configuration with the channels in this order:
03437         /// <ol>
03438         ///     <li>Front Left</li>
03439         ///     <li>Front Right</li>
03440         ///     <li>Center</li>
03441         ///     <li>LFE</li>
03442         ///     <li>Surround Left</li>
03443         ///     <li>Surround Right</li>
03444         /// </ol>
03445         /// \return AK_Success if successful, AK_Fail if there was a problem starting the output capture.
03446         /// \remark
03447         ///     - The sound engine opens a stream for writing using AK::IAkStreamMgr::CreateStd(). If you are using the
03448         ///         default implementation of the Stream Manager, file opening is executed in your implementation of 
03449         ///         the Low-Level IO interface AK::StreamMgr::IAkFileLocationResolver::Open(). The following 
03450         ///         AkFileSystemFlags are passed: uCompanyID = AKCOMPANYID_AUDIOKINETIC and uCodecID = AKCODECID_PCM,
03451         ///         and the AkOpenMode is AK_OpenModeWriteOvrwr. Refer to \ref streamingmanager_lowlevel_location for
03452         ///         more details on managing the deployment of your Wwise generated data.
03453         /// \sa 
03454         /// - AK::SoundEngine::StopOutputCapture()
03455         /// - AK::StreamMgr::SetFileLocationResolver()
03456         /// - \ref streamingdevicemanager
03457         /// - \ref streamingmanager_lowlevel_location
03458         AK_EXTERNAPIFUNC( AKRESULT, StartOutputCapture )( 
03459             const AkOSChar* in_CaptureFileName              ///< Name of the output capture file
03460             );
03461 
03462         /// Stop recording the sound engine audio output. 
03463         /// \return AK_Success if successful, AK_Fail if there was a problem stopping the output capture.
03464         /// \sa 
03465         /// - AK::SoundEngine::StartOutputCapture()
03466         AK_EXTERNAPIFUNC( AKRESULT, StopOutputCapture )();
03467 
03468         /// Add text marker in audio output file. 
03469         /// \return AK_Success if successful, AK_Fail if there was a problem adding the output marker.
03470         /// \sa 
03471         /// - AK::SoundEngine::StartOutputCapture()
03472         AK_EXTERNAPIFUNC( AKRESULT, AddOutputCaptureMarker )(
03473             const char* in_MarkerText                   ///< Text of the marker
03474             );
03475             
03476         /// Start recording the sound engine profiling information into a file. This file can be read
03477         /// by Wwise Authoring.
03478         /// \remark This function is provided as a utility tool only. It does nothing if it is 
03479         ///         called in the release configuration and returns AK_NotCompatible.
03480         AK_EXTERNAPIFUNC( AKRESULT, StartProfilerCapture )( 
03481             const AkOSChar* in_CaptureFileName              ///< Name of the output profiler file (.prof extension recommended)
03482             );
03483 
03484         /// Stop recording the sound engine profiling information. 
03485         /// \remark This function is provided as a utility tool only. It does nothing if it is 
03486         ///         called in the release configuration and returns AK_NotCompatible.
03487         AK_EXTERNAPIFUNC( AKRESULT, StopProfilerCapture )();
03488 
03489         //@}
03490 
03491         ////////////////////////////////////////////////////////////////////////
03492         /// @name Secondary Outputs
03493         //@{
03494 
03495         /// Adds a secondary output to the system.  Use this to add controller-attached headphones or speakers.  You can attach multiple devices to the same "player" if needed.        
03496         /// Secondary output feature is supported only on PS4 (Controller-speaker & BGM), XboxOne (Controller-headphone & BGM).  Other platforms will return Ak_NotImplemented.
03497         /// \sa integrating_secondary_outputs
03498         /// \return 
03499         /// - AK_NotImplemented: Feature not supported on this platforms (all platforms except PS4 and XBoxOne)
03500         /// - AK_InvalidParameter: Out of range parameters or unsupported parameter combinations (see parameter list below).
03501         /// - AK_Success: Parameters are valid.
03502         AK_EXTERNAPIFUNC( AKRESULT, AddSecondaryOutput )(
03503             AkUInt32 in_iOutputID,          ///< Device identifier, when multiple devices of the same type are possible.
03504                                             ///< - PS4 Controller-Speakers: UserID as returned from sceUserServiceGetLoginUserIdList
03505                                             ///< - XBoxOne Controller-Headphones: Use the AK::GetDeviceID function to get the ID from an IMMDevice.  Find the player's device with the WASAPI API (IMMDeviceEnumerator, see Microsoft documentation) or use AK::GetDeviceIDFromName.
03506                                             ///< - XBoxOne & PS4 BGM outputs: use 0.
03507                                             ///< - Audio device plugins: use 0 to X
03508             AkAudioOutputType in_iDeviceType,   ///< Device Type, must be one of the currently supported devices types.  See AkAudioOutputType.
03509                                             ///< - PS4: Use AkOutput_PAD, AkOutput_Personal, AkOutput_BGM, AkOutput_BGM_NonRecordable
03510                                             ///< - XboxOne Use AkOutput_BGM, AkOutput_BGM_NonRecordable, AkOutput_Personal
03511                                             ///< - If you are using an Audio Device plug-in, you must specify AkOutput_Plugin.
03512             const AkGameObjectID* in_pListenerIDs,///< - Listener(s) to attach to this device.  Everything heard by these listeners will be sent to this output.  Avoid using listenerID 0, usually reserved for the main TV output.
03513             AkUInt32 in_uNumListeners,      ///< - The number of elements in the in_pListenerIDs array.
03514             AkUInt32 in_uOutputFlags = 0,   ///< Optional Flags that will be passed to the secondary output creation, OR-it to pass many flags.
03515                                             ///< \sa AkAudioOutputFlags
03516             AkUniqueID in_audioDeviceShareset = AK_INVALID_UNIQUE_ID ///< Unique ID of a custom audio device to be used. 
03517                                             ///< Leave this field to its default value (AK_INVALID_UNIQUE_ID) unless you are using an Audio device plug-in.
03518                                             ///< Typical usage: audioDeviceShareset = AK::SoundEngine::GetIDFromString("InsertYourAudioDeviceSharesetNameHere");
03519                                             ///< \ref AK::SoundEngine::GetIDFromString()
03520             );
03521 
03522         AK_EXTERNAPIFUNC( AKRESULT, RemoveSecondaryOutput )(
03523             AkUInt32 in_iOutputID,              ///< Player number (almost all platforms) or device-unique identifier (UserID on PS4).
03524             AkAudioOutputType in_iDeviceType    ///< Device Type, must be one of the currently supported devices types. 
03525             );
03526         
03527         /// Set the volume of a secondary output device.
03528         AK_EXTERNAPIFUNC( AKRESULT, SetSecondaryOutputVolume )(
03529             AkUInt32 in_iOutputID,          ///< Player number (almost all platforms) or device-unique identifier (UserID on PS4).          
03530             AkAudioOutputType in_iDeviceType, ///< Device Type, must be one of the currently supported devices types.  See AkAudioOutputType
03531             AkReal32 in_fVolume             ///< Volume (0.0 = Muted, 1.0 = Volume max)
03532             );
03533         //@}
03534 
03535         /// 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.
03536         /// Call WakeupFromSuspend when your application receives the message from the OS that the process is back in foreground.
03537         /// When suspended, the sound engine will process API messages (like PostEvent and SetSwitch) only when \ref RenderAudio() is called. 
03538         /// It is recommended to match the <b>in_bRenderAnyway</b> parameter with the behavior of the rest of your game: 
03539         /// 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.
03540         /// If you want to minimize CPU when in background, then don't allow rendering and never call RenderAudio from the game.
03541         ///
03542         /// - Android: Call for APP_CMD_PAUSE
03543         /// - iOS: Don't call.  All audio interrupts are handled internally.
03544         /// - XBoxOne: Use when entering constrained mode or suspended mode (see ResourceAvailability in XboxOne documentation).
03545         /// \sa \ref WakeupFromSuspend
03546         AK_EXTERNAPIFUNC( AKRESULT, Suspend )(
03547             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().
03548             );
03549 
03550         /// This function should be called to wakeup the sound engine and start processing audio again.  This needs to be called if the console has a background mode or some suspended state.
03551         /// - Android: Call for APP_CMD_RESUME
03552         /// - iOS: Don't call.  All audio interrupts are handled internally.        
03553         /// - XBoxOne: Use when the game is back to Full resources (see ResourceAvailability in XboxOne documentation).
03554         AK_EXTERNAPIFUNC( AKRESULT, WakeupFromSuspend )(); 
03555 
03556         /// Obtain the current audio output buffer tick. This corresponds to the number of buffers produced by
03557         /// the sound engine since initialization. 
03558         /// \return Tick count.
03559         AK_EXTERNAPIFUNC(AkUInt32, GetBufferTick)();
03560     }
03561 }
03562 
03563 #endif // _AK_SOUNDENGINE_H_

Was this page helpful?

Need Support?

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

Visit our Support page

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

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

Get started with Wwise