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