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 // AkWinSoundEngine.h
00029 
00030 /// \file 
00031 /// Main Sound Engine interface, specific WIN32.
00032 
00033 #ifndef _AK_WIN_SOUND_ENGINE_H_
00034 #define _AK_WIN_SOUND_ENGINE_H_
00035 
00036 #include <AK/SoundEngine/Common/AkTypes.h>
00037 #include <AK/Tools/Common/AkPlatformFuncs.h>
00038 
00039 ///< API used for audio output
00040 ///< Use with AkPlatformInitSettings to select the API used for audio output.  
00041 ///< Use AkAPI_Default, it will select the more appropriate API depending on the computer's capabilities.  Other values should be used for testing purposes.
00042 ///< \sa AK::SoundEngine::Init
00043 enum AkAudioAPI
00044 {
00045     AkAPI_Wasapi = 1 << 0,                              ///< Use Wasapi 
00046     AkAPI_XAudio2 = 1 << 1,                             ///< Use XAudio2 (this is the preferred API on Windows)
00047     AkAPI_DirectSound = 1 << 2,                         ///< Use DirectSound
00048     AkAPI_Default = AkAPI_Wasapi | AkAPI_XAudio2 | AkAPI_DirectSound,   ///< Default value, will select the more appropriate API (XAudio2 is the default)   
00049 };
00050 
00051 ///< Used with \ref AK::GetWindowsDeviceName to specify the device state mask.
00052 enum AkAudioDeviceState
00053 {
00054     AkDeviceState_Active = 1 << 0,     ///< The audio device is active That is, the audio adapter that connects to the endpont device is present and enabled.
00055     AkDeviceState_Disabled = 1 << 1,   ///< The audio device is disabled.
00056     AkDeviceState_NotPresent = 1 << 2, ///< The audio device is not present because the audio adapter that connects to the endpoint device has been removed from the system.
00057     AkDeviceState_Unplugged = 1 << 3,  ///< The audio device is unplugged.
00058     AkDeviceState_All = AkDeviceState_Active | AkDeviceState_Disabled | AkDeviceState_NotPresent | AkDeviceState_Unplugged, ///< Includes audio devices in all states.
00059 };
00060 
00061 ///< Used with \ref AK::SoundEngine::AddSecondaryOutput to specify the type of secondary output.
00062 enum AkAudioOutputType
00063 {
00064     AkOutput_None = 0,      ///< Used for uninitialized type, do not use.
00065     AkOutput_Dummy,         ///< Dummy output, simply eats the audio stream and outputs nothing.
00066     AkOutput_Main,          ///< Main output.  This cannot be used with AddSecondaryOutput, but can be used to query information about the main output (GetSpeakerConfiguration for example).   
00067     AkOutput_Secondary,     ///< Adds an output linked to the hardware device specified  (See AddSecondaryOutput).
00068     AkOutput_NumBuiltInOutputs,     ///< Do not use.
00069     AkOutput_Plugin         ///< Specify if using Audio Device Plugin Sink.
00070 };
00071 
00072 struct IXAudio2;
00073 
00074 /// Platform specific initialization settings
00075 /// \sa AK::SoundEngine::Init
00076 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
00077 /// - \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
00078 
00079 struct AkPlatformInitSettings
00080 {
00081     // Direct sound.
00082     HWND                hWnd;                   ///< Handle to the window associated to the audio.
00083                                                 ///< Each game must specify the HWND that will be passed to DirectSound initialization.
00084                                                 ///< The value returned by GetDefaultPlatformInitSettings is the foreground HWND at 
00085                                                 ///< the moment of the initialization of the sound engine and may not be the correct one for your game.
00086                                                 ///< It is required that each game provides the correct HWND to be used.
00087                                     
00088 
00089     // Threading model.
00090     AkThreadProperties  threadLEngine;          ///< Lower engine threading properties
00091     AkThreadProperties  threadBankManager;      ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
00092     AkThreadProperties  threadMonitor;          ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
00093 
00094     // Memory.
00095     AkUInt32            uLEngineDefaultPoolSize;///< Lower Engine default memory pool size
00096     AkReal32            fLEngineDefaultPoolRatioThreshold;  ///< 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
00097 
00098     // Voices.
00099     AkUInt16            uNumRefillsInVoice;     ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4.
00100 
00101     AkUInt32            uSampleRate;            ///< Sampling Rate. Default is 48000 Hz. Use 24000hz for low quality. Any positive reasonable sample rate is supported. However be careful setting a custom value. Using an odd or really low sample rate may result in malfunctionning sound engine.
00102 
00103 
00104     AkAudioAPI          eAudioAPI;              ///< Main audio API to use. Leave to AkAPI_Default for the default sink (default value).
00105                                                 ///< If a valid audioDeviceShareset plug-in is provided, the AkAudioAPI will be Ignored.
00106                                                 ///< \ref AkAudioAPI
00107     
00108     bool                bGlobalFocus;           ///< Corresponding to DSBCAPS_GLOBALFOCUS. If using the AkAPI_DirectSound AkAudioAPI type, sounds will be muted if set to false when the game loses the focus.
00109                                                 ///< This setting is ignored when using other AkAudioAPI types.
00110 
00111     IXAudio2*           pXAudio2;               ///< XAudio2 instance to use for the Wwise sound engine.  If NULL (default) Wwise will initialize its own instance.  Used only if the sink type is XAudio2 in AkInitSettings.outputType.
00112 
00113     AkUInt32            idAudioDevice;          ///< Device ID to use for the main audio output, as returned from AK::GetDeviceID or AK::GetDeviceIDFromName.  
00114                                                                                                 
00115 };
00116 
00117 struct IDirectSound8;
00118 struct IXAudio2;
00119 struct IMMDevice;
00120 struct IUnknown;
00121 
00122 namespace AK
00123 {
00124     /// Get instance of XAudio2 created by the sound engine at initialization.
00125     /// \return Non-addref'd pointer to XAudio2 interface. NULL if sound engine is not initialized or XAudio2 is not used.
00126     /// The returned pointer can be of either XAudio 2.7, XAudio 2.8, Xaudio 2.9 depending on the Windows version the game is running on.  Use QueryInterface to identify which one and cast appropriately
00127     AK_EXTERNAPIFUNC( IUnknown *, GetWwiseXAudio2Interface)();
00128 
00129     /// Get instance of DirectSound created by the sound engine at initialization.
00130     /// \return Non-addref'd pointer to DirectSound interface. NULL if sound engine is not initialized or DirectSound is not used.
00131     AK_EXTERNAPIFUNC( IDirectSound8 *, GetDirectSoundInstance )();
00132 
00133     /// Finds the device ID for particular Audio Endpoint. 
00134     /// \note CoInitialize must have been called for the calling thread.  See Microsoft's documentation about CoInitialize for more details.
00135     /// \return A device ID to use with AddSecondaryOutput or AkPlatformInitSettings.idAudioDevice
00136     AK_EXTERNAPIFUNC( AkUInt32, GetDeviceID ) (IMMDevice* in_pDevice);
00137 
00138     /// Finds an audio endpoint that matches the token in the device name or device ID and returns and ID compatible with AddSecondaryOutput.  
00139     /// This is a helper function that searches in the device ID (as returned by IMMDevice->GetId) and 
00140     /// in the property PKEY_Device_FriendlyName.  The token parameter is case-sensitive.  If you need to do matching on different conditions, use IMMDeviceEnumerator directly and AK::GetDeviceID.
00141     /// \note CoInitialize must have been called for the calling thread.  See Microsoft's documentation about CoInitialize for more details.
00142     /// \return An ID to use with AddSecondaryOutput.  The ID returned is the device ID as returned by IMMDevice->GetId, hashed by AK::SoundEngine::GetIDFromName()
00143     AK_EXTERNAPIFUNC( AkUInt32, GetDeviceIDFromName )(wchar_t* in_szToken);
00144 
00145     /// Get the user-friendly name for the specified device.  Call repeatedly with index starting at 0 and increasing to get all available devices, including disabled and unplugged devices, until the returned string is null.
00146     /// You can also get the default device information by specifying index=-1.  The default device is the one with a green checkmark in the Audio Playback Device panel in Windows.
00147     /// The returned out_uDeviceID parameter is the Device ID to use with Wwise.  Use it to specify the main device in AkPlatformInitSettings.idAudioDevice or in AK::SoundEngine::AddSecondaryOutput. 
00148     /// \note CoInitialize must have been called for the calling thread.  See Microsoft's documentation about CoInitialize for more details.
00149     /// \return The name of the device at the "index" specified.  The pointer is valid until the next call to GetWindowsDeviceName.
00150     AK_EXTERNAPIFUNC(const wchar_t*, GetWindowsDeviceName) (
00151         AkInt32 index,           ///< Index of the device in the array.  -1 to get information on the default device.
00152         AkUInt32 &out_uDeviceID, ///< Device ID for Wwise.  This is the same as what is returned from AK::GetDeviceID and AK::GetDeviceIDFromName.  Use it to specify the main device in AkPlatformInitSettings.idAudioDevice or in AK::SoundEngine::AddSecondaryOutput. 
00153         AkAudioDeviceState uDeviceStateMask = AkDeviceState_All ///< Optional bitmask used to filter the device based on their state.
00154         );
00155 };
00156 
00157 #endif //_AK_WIN_SOUND_ENGINE_H_