Table of Contents

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