Version
menu_open
link
Target Platform(s):
Wwise SDK 2022.1.4
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  Copyright (c) 2023 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 // AkWinSoundEngine.h
28 
29 /// \file
30 /// Main Sound Engine interface, specific WIN32.
31 
32 #ifndef _AK_WIN_SOUND_ENGINE_H_
33 #define _AK_WIN_SOUND_ENGINE_H_
34 
35 #include <AK/SoundEngine/Common/AkTypes.h>
36 #include <AK/Tools/Common/AkPlatformFuncs.h>
37 
38 struct IXAudio2;
39 
40 /// \cond !(Web)
41 /// Platform specific initialization settings
42 /// \sa AK::SoundEngine::Init
43 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
44 
45 struct AkPlatformInitSettings
46 {
47  // Direct sound.
48  HWND hWnd; ///< Handle of the window associated with the audio.
49  ///< Each game must specify the HWND of the application for device detection purposes.
50  ///< The value returned by GetDefaultPlatformInitSettings is the foreground HWND at
51  ///< the moment of the initialization of the sound engine and might not be the correct one for your game.
52  ///< Each game must provide the correct HWND to use.
53 
54 
55  // Threading model.
56  AkThreadProperties threadLEngine; ///< Lower engine threading properties
57  AkThreadProperties threadOutputMgr; ///< Ouput thread threading properties
58  AkThreadProperties threadBankManager; ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
59  AkThreadProperties threadMonitor; ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
60 
61  // Voices.
62  AkUInt16 uNumRefillsInVoice; ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4.
63 
64  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.
65 
66  bool bEnableAvxSupport; ///< Enables run-time detection of AVX and AVX2 SIMD support in the engine and plug-ins. Disabling this may improve CPU performance by allowing for higher CPU clockspeeds.
67 
68  AkUInt32 uMaxSystemAudioObjects; ///< Dictates how many Microsoft Spatial Sound dynamic objects will be reserved by the System sink. On Windows, other running processes will be prevented from reserving these objects. Set to 0 to disable the use of System Audio Objects. Default is 128.
69 };
70 /// \endcond
71 
72 struct IDirectSound8;
73 struct IXAudio2;
74 struct IMMDevice;
75 struct IUnknown;
76 
77 namespace AK
78 {
79  /// Get instance of XAudio2 created by the sound engine at initialization.
80  /// \return Non-addref'd pointer to XAudio2 interface. NULL if sound engine is not initialized or XAudio2 is not used.
81  /// 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
82  AK_EXTERNAPIFUNC( IUnknown *, GetWwiseXAudio2Interface)();
83 
84  /// Get instance of DirectSound created by the sound engine at initialization.
85  /// \return Non-addref'd pointer to DirectSound interface. NULL if sound engine is not initialized or DirectSound is not used.
86  AK_EXTERNAPIFUNC( IDirectSound8 *, GetDirectSoundInstance )();
87 
88  /// Finds the device ID for particular Audio Endpoint.
89  /// \note CoInitialize must have been called for the calling thread. See Microsoft's documentation about CoInitialize for more details.
90  /// \return A device ID to use with AkPlatformInitSettings.idAudioDevice
91  AK_EXTERNAPIFUNC( AkUInt32, GetDeviceID ) (IMMDevice* in_pDevice);
92 
93  /// Finds an audio endpoint that matches the token in the device name or device ID and returns an ID.
94  /// This is a helper function that searches in the device ID (as returned by IMMDevice->GetId) and
95  /// 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.
96  /// \note CoInitialize must have been called for the calling thread. See Microsoft's documentation about CoInitialize for more details.
97  /// \return The device ID as returned by IMMDevice->GetId, hashed by AK::SoundEngine::GetIDFromName()
98  AK_EXTERNAPIFUNC( AkUInt32, GetDeviceIDFromName )(wchar_t* in_szToken);
99 
100  /// 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 and out_uDeviceID is zero.
101  /// The number of indexable devices for the given uDeviceStateMask can be fetched by calling AK::SoundEngine::GetWindowsDeviceCount().
102  /// 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.
103  /// The returned out_uDeviceID parameter is the Device ID to use with Wwise. Use it to specify the main device in AkPlatformInitSettings.idAudioDevice.
104  /// \note CoInitialize must have been called for the calling thread. See Microsoft's documentation about CoInitialize for more details.
105  /// \return The name of the device at the "index" specified. The pointer is valid until the next call to GetWindowsDeviceName.
106  AK_EXTERNAPIFUNC(const wchar_t*, GetWindowsDeviceName) (
107  AkInt32 index, ///< Index of the device in the array. -1 to get information on the default device.
108  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.
109  AkAudioDeviceState uDeviceStateMask = AkDeviceState_All ///< Optional bitmask used to filter the device based on their state.
110  );
111 
112  /// Get the number of Audio Endpoints available for the specified device state mask.
113  /// \note CoInitialize must have been called for the calling thread. See Microsoft's documentation about CoInitialize for more details.
114  /// \return The number of Audio Endpoints available for the specified device state mask.
115  AK_EXTERNAPIFUNC( AkUInt32, GetWindowsDeviceCount ) (
116  AkAudioDeviceState uDeviceStateMask = AkDeviceState_All ///< Optional bitmask used to filter the device based on their state.
117  );
118 
119  /// Get the Audio Endpoint for the specified device index. Call repeatedly with index starting at 0 and increasing to get all available devices, including disabled and unplugged devices, until the false is returned.
120  /// 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.
121  /// The returned out_uDeviceID parameter is the Device ID to use with Wwise. Use it to specify the main device in AkPlatformInitSettings.idAudioDevice.
122  /// The returned out_ppDevice is a pointer to a pointer variable to which the method writes the address of the IMMDevice. out_ppDevice is optional; if it is null, then no action is taken.
123  /// If the method returns false, *out_ppDevice is null. If the method successed, *out_ppDevice will be a counted reference to the interface, and the caller is responsible for releasing the interface when it is no longer needed, by calling Release(), or encapsulating the device in a COM Smart Pointer.
124  /// \note CoInitialize must have been called for the calling thread. See Microsoft's documentation about CoInitialize for more details.
125  /// \return Whether or not a device was found at the given index.
126  AK_EXTERNAPIFUNC( bool, GetWindowsDevice) (
127  AkInt32 in_index, ///< Index of the device in the array. -1 to get information on the default device.
128  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.
129  IMMDevice** out_ppDevice, ///< pointer to a pointer variable to which the method writes the address of the IMMDevice in question.
130  AkAudioDeviceState uDeviceStateMask = AkDeviceState_All ///< Optional bitmask used to filter the device based on their state.
131  );
132 
133 #ifdef AK_UWP_CPP_CX
134 
135  /// Get the device ID corresponding to a Universal Windows Platform Gamepad reference. This device ID can be used to add/remove motion output for that gamepad.
136  /// \note The ID returned is unique to Wwise and does not correspond to any sensible value outside of Wwise.
137  /// \note This function is only available for project code using C++/CX.
138  /// \return Unique device ID, or AK_INVALID_DEVICE_ID if the reference is no longer valid (such as if the gamepad was disconnected)
139  AK_EXTERNAPIFUNC(AkDeviceID, GetDeviceIDFromGamepad) (Windows::Gaming::Input::Gamepad^ rGamepad);
140 
141 #endif
142 
143 };
144 
145 #endif //_AK_WIN_SOUND_ENGINE_H_
AkUInt16
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkNumeralTypes.h:37
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:31
AK::GetDirectSoundInstance
AKSOUNDENGINE_API IDirectSound8 * GetDirectSoundInstance()
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:81
AkDeviceID
AkUInt32 AkDeviceID
I/O device ID.
Definition: AkTypes.h:140
AK::GetDeviceID
AKSOUNDENGINE_API AkUInt32 GetDeviceID(IMMDevice *in_pDevice)
AkDeviceState_All
@ AkDeviceState_All
Includes audio devices in all states.
Definition: AkTypes.h:291
AK::GetWindowsDevice
AKSOUNDENGINE_API bool GetWindowsDevice(AkInt32 in_index, AkUInt32 &out_uDeviceID, IMMDevice **out_ppDevice, AkAudioDeviceState uDeviceStateMask=AkDeviceState_All)
AkInt32
int32_t AkInt32
Signed 32-bit integer.
Definition: AkNumeralTypes.h:43
AK::GetWindowsDeviceName
AKSOUNDENGINE_API const wchar_t * GetWindowsDeviceName(AkInt32 index, AkUInt32 &out_uDeviceID, AkAudioDeviceState uDeviceStateMask=AkDeviceState_All)
AK::GetWwiseXAudio2Interface
AKSOUNDENGINE_API IUnknown * GetWwiseXAudio2Interface()
AK::GetDeviceIDFromName
AKSOUNDENGINE_API AkUInt32 GetDeviceIDFromName(wchar_t *in_szToken)
AkAudioDeviceState
AkAudioDeviceState
Definition: AkTypes.h:285
AK::GetDeviceIDFromGamepad
AKSOUNDENGINE_API AkDeviceID GetDeviceIDFromGamepad(Windows::Gaming::Input::Gamepad^ rGamepad)
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:38
AK::GetWindowsDeviceCount
AKSOUNDENGINE_API AkUInt32 GetWindowsDeviceCount(AkAudioDeviceState uDeviceStateMask=AkDeviceState_All)

Was this page helpful?

Need Support?

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

Visit our Support page

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

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

Get started with Wwise