Table of Contents

Target Platform(s):
Wwise SDK 2018.1.11
AkWinSoundEngine.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Version: <VERSION> Build: <BUILDNUMBER>
25  Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
26 *******************************************************************************/
27 
28 // AkWinSoundEngine.h
29 
30 /// \file
31 /// Main Sound Engine interface, specific WIN32.
32 
33 #ifndef _AK_WIN_SOUND_ENGINE_H_
34 #define _AK_WIN_SOUND_ENGINE_H_
35 
38 
39 ///< API used for audio output
40 ///< Use with AkPlatformInitSettings to select the API used for audio output.
41 ///< Use AkAPI_Default, it will select the more appropriate API depending on the computer's capabilities. Other values should be used for testing purposes.
42 ///< \sa AK::SoundEngine::Init
44 {
45  AkAPI_Wasapi = 1 << 0, ///< Use Wasapi
46  AkAPI_XAudio2 = 1 << 1, ///< Use XAudio2 (this is the preferred API on Windows)
47  AkAPI_DirectSound = 1 << 2, ///< Use DirectSound
48  AkAPI_Default = AkAPI_Wasapi | AkAPI_XAudio2 | AkAPI_DirectSound, ///< Default value, will select the more appropriate API (XAudio2 is the default)
49 };
50 
51 ///< Used with \ref AK::GetWindowsDeviceName to specify the device state mask.
53 {
54  AkDeviceState_Active = 1 << 0, ///< The audio device is active That is, the audio adapter that connects to the endpont device is present and enabled.
55  AkDeviceState_Disabled = 1 << 1, ///< The audio device is disabled.
56  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.
57  AkDeviceState_Unplugged = 1 << 3, ///< The audio device is unplugged.
59 };
60 
61 struct IXAudio2;
62 
63 /// Platform specific initialization settings
64 /// \sa AK::SoundEngine::Init
65 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
66 /// - \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
67 
69 {
70  // Direct sound.
71  HWND hWnd; ///< Handle to the window associated to the audio.
72  ///< Each game must specify the HWND that will be passed to DirectSound initialization.
73  ///< The value returned by GetDefaultPlatformInitSettings is the foreground HWND at
74  ///< the moment of the initialization of the sound engine and may not be the correct one for your game.
75  ///< It is required that each game provides the correct HWND to be used.
76 
77 
78  // Threading model.
79  AkThreadProperties threadLEngine; ///< Lower engine threading properties
80  AkThreadProperties threadOutputMgr; ///< Ouput thread threading properties
81  AkThreadProperties threadBankManager; ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
82  AkThreadProperties threadMonitor; ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
83 
84  // Memory.
85  AkUInt32 uLEngineDefaultPoolSize;///< Lower Engine default memory pool size
86  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
87 
88  // Voices.
89  AkUInt16 uNumRefillsInVoice; ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4.
90 
91  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.
92 
93 
94  AkAudioAPI eAudioAPI; ///< Main audio API to use. Leave to AkAPI_Default for the default sink (default value).
95  ///< If a valid audioDeviceShareset plug-in is provided, the AkAudioAPI will be Ignored.
96  ///< \ref AkAudioAPI
97 
98  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.
99  ///< This setting is ignored when using other AkAudioAPI types.
100 
101  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.
102 };
103 
104 struct IDirectSound8;
105 struct IXAudio2;
106 struct IMMDevice;
107 struct IUnknown;
108 
109 namespace AK
110 {
111  /// Get instance of XAudio2 created by the sound engine at initialization.
112  /// \return Non-addref'd pointer to XAudio2 interface. NULL if sound engine is not initialized or XAudio2 is not used.
113  /// 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
115 
116  /// Get instance of DirectSound created by the sound engine at initialization.
117  /// \return Non-addref'd pointer to DirectSound interface. NULL if sound engine is not initialized or DirectSound is not used.
118  AK_EXTERNAPIFUNC( IDirectSound8 *, GetDirectSoundInstance )();
119 
120  /// Finds the device ID for particular Audio Endpoint.
121  /// \note CoInitialize must have been called for the calling thread. See Microsoft's documentation about CoInitialize for more details.
122  /// \return A device ID to use with AddSecondaryOutput or AkPlatformInitSettings.idAudioDevice
123  AK_EXTERNAPIFUNC( AkUInt32, GetDeviceID ) (IMMDevice* in_pDevice);
124 
125  /// Finds an audio endpoint that matches the token in the device name or device ID and returns and ID compatible with AddSecondaryOutput.
126  /// This is a helper function that searches in the device ID (as returned by IMMDevice->GetId) and
127  /// 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.
128  /// \note CoInitialize must have been called for the calling thread. See Microsoft's documentation about CoInitialize for more details.
129  /// \return An ID to use with AddSecondaryOutput. The ID returned is the device ID as returned by IMMDevice->GetId, hashed by AK::SoundEngine::GetIDFromName()
130  AK_EXTERNAPIFUNC( AkUInt32, GetDeviceIDFromName )(wchar_t* in_szToken);
131 
132  /// 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.
133  /// 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.
134  /// 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.
135  /// \note CoInitialize must have been called for the calling thread. See Microsoft's documentation about CoInitialize for more details.
136  /// \return The name of the device at the "index" specified. The pointer is valid until the next call to GetWindowsDeviceName.
137  AK_EXTERNAPIFUNC(const wchar_t*, GetWindowsDeviceName) (
138  AkInt32 index, ///< Index of the device in the array. -1 to get information on the default device.
139  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.
140  AkAudioDeviceState uDeviceStateMask = AkDeviceState_All ///< Optional bitmask used to filter the device based on their state.
141  );
142 };
143 
144 #endif //_AK_WIN_SOUND_ENGINE_H_
AkThreadProperties threadBankManager
Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
The audio device is not present because the audio adapter that connects to the endpoint device has be...
Definition: AkWinSoundEngine.h:56
AkUInt32 uSampleRate
Sampling Rate. Set to 0 to get the native sample rate. Default value is 0.
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkTypes.h:78
The audio device is active That is, the audio adapter that connects to the endpont device is present ...
Definition: AkWinSoundEngine.h:54
AkThreadProperties threadLEngine
Lower engine threading properties.
Audiokinetic namespace.
The audio device is disabled.
Definition: AkWinSoundEngine.h:55
#define AK_EXTERNAPIFUNC(__TYPE__, __NAME__)
const wchar_t *__cdecl GetWindowsDeviceName(AkInt32 index, AkUInt32 &out_uDeviceID, AkAudioDeviceState uDeviceStateMask=AkDeviceState_All)
AkUInt32 uLEngineDefaultPoolSize
Lower Engine default memory pool size.
Use DirectSound.
Definition: AkWinSoundEngine.h:47
AkAudioAPI
Definition: AkWinSoundEngine.h:43
Use XAudio2 (this is the preferred API on Windows)
Definition: AkWinSoundEngine.h:46
int32_t AkInt32
Signed 32-bit integer.
Definition: AkTypes.h:92
AkReal32 fLEngineDefaultPoolRatioThreshold
0.0f to 1.0f value: The percentage of occupied memory where the sound engine should enter in Low memo...
AkAudioDeviceState
Definition: AkWinSoundEngine.h:52
AkAudioAPI eAudioAPI
Definition: AkWinSoundEngine.h:94
AkUInt16 uNumRefillsInVoice
Number of refill buffers in voice buffer. Defaults to 4.
IDirectSound8 *__cdecl GetDirectSoundInstance()
Default value, will select the more appropriate API (XAudio2 is the default)
Definition: AkWinSoundEngine.h:48
Use Wasapi.
Definition: AkWinSoundEngine.h:45
AkThreadProperties threadOutputMgr
Ouput thread threading properties.
The audio device is unplugged.
Definition: AkWinSoundEngine.h:57
AkThreadProperties threadMonitor
Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL)....
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:79
IUnknown *__cdecl GetWwiseXAudio2Interface()
Includes audio devices in all states.
Definition: AkWinSoundEngine.h:58
float AkReal32
32-bit floating point
Definition: AkTypes.h:97
AkUInt32 __cdecl GetDeviceIDFromName(wchar_t *in_szToken)
IXAudio2 * pXAudio2
XAudio2 instance to use for the Wwise sound engine. If NULL (default) Wwise will initialize its own i...
AkUInt32 __cdecl GetDeviceID(IMMDevice *in_pDevice)