_ak_win_sound_engine_8h

Target Platform(s):

Wwise SDK 2025.1.0

 /*******************************************************************************
 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
 released in source code form as part of the SDK installer package.
  
 Commercial License Usage
  
 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
 may use this file in accordance with the end user license agreement provided 
 with the software or, alternatively, in accordance with the terms contained in a
 written agreement between you and Audiokinetic Inc.
  
 Apache License Usage
  
 Alternatively, this file may be used under the Apache License, Version 2.0 (the 
 "Apache License"); you may not use this file except in compliance with the 
 Apache License. You may obtain a copy of the Apache License at 
 http://www.apache.org/licenses/LICENSE-2.0.
  
 Unless required by applicable law or agreed to in writing, software distributed
 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
 the specific language governing permissions and limitations under the License.
  
   Copyright (c) 2025 Audiokinetic Inc.
 *******************************************************************************/
  
 // AkWinSoundEngine.h
  
 /// \file 
 /// Main Sound Engine interface, specific WIN32.
  
 #ifndef _AK_WIN_SOUND_ENGINE_H_
 #define _AK_WIN_SOUND_ENGINE_H_
  
 #include <AK/SoundEngine/Common/AkTypes.h>
 #include <AK/Tools/Common/AkPlatformFuncs.h>
  
 /// Platform specific initialization settings
 /// \sa AK::SoundEngine::Init
 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
  
 struct AkPlatformInitSettings
 {
     // Threading configuration
     AkThreadProperties  threadLEngine;          ///< Lower engine threading properties
     AkThreadProperties  threadOutputMgr;        ///< Ouput thread threading properties
     AkThreadProperties  threadBankManager;      ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
     AkThreadProperties  threadMonitor;          ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
  
     // Audio render configuration
     AkUInt16            uNumRefillsInVoice;     ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4.
  
     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.
  
     bool                bEnableAvxSupport;      ///< Enables run-time detection of AVX and AVX2 SIMD support in the engine and plug-ins.
  
     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.
 };
  
 struct IMMDevice;
  
 namespace AK
 {
     /// Finds the device ID for particular Audio Endpoint. 
     /// \note CoInitialize must have been called for the calling thread.  See Microsoft's documentation about CoInitialize for more details.
     /// \return A device ID to use with AkPlatformInitSettings.idAudioDevice
     AK_EXTERNAPIFUNC( AkUInt32, GetDeviceID ) (IMMDevice* in_pDevice);
  
     /// Finds an audio endpoint that matches the token in the device name or device ID and returns an ID.  
     /// This is a helper function that searches in the device ID (as returned by IMMDevice->GetId) and 
     /// 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.
     /// \return The device ID as returned by IMMDevice->GetId, hashed by AK::SoundEngine::GetIDFromName()
     AK_EXTERNAPIFUNC( AkUInt32, GetDeviceIDFromName )(wchar_t* in_szToken);
  
     /// 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 AK_INVALID_DEVICE_ID.
     /// The number of indexable devices for the given uDeviceStateMask can be fetched by calling AK::SoundEngine::GetWindowsDeviceCount().
     /// 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.
     /// The returned out_uDeviceID parameter is the Device ID to use with Wwise.  Use it to specify the main device in AkPlatformInitSettings.idAudioDevice. 
     /// \return The name of the device at the "index" specified.  The pointer is valid until the next call to GetWindowsDeviceName.
     AK_EXTERNAPIFUNC(const wchar_t*, GetWindowsDeviceName) (
         AkInt32 index,           ///< Index of the device in the array.  -1 to get information on the default device.
         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. 
         AkAudioDeviceState uDeviceStateMask = AkDeviceState_All ///< Optional bitmask used to filter the device based on their state.
         );
  
     /// Get the number of Audio Endpoints available for the specified device state mask.
     /// \return The number of Audio Endpoints available for the specified device state mask.
     AK_EXTERNAPIFUNC( AkUInt32, GetWindowsDeviceCount ) (
         AkAudioDeviceState uDeviceStateMask = AkDeviceState_All ///< Optional bitmask used to filter the device based on their state.
         );
  
     /// 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.
     /// 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.
     /// The returned out_uDeviceID parameter is the Device ID to use with Wwise.  Use it to specify the main device in AkPlatformInitSettings.idAudioDevice. 
     /// 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. 
     /// If the method returns false, *out_ppDevice is null and out_uDeviceID is AK_INVALID_DEVICE_ID. 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.
     /// \return Whether or not a device was found at the given index.
     AK_EXTERNAPIFUNC( bool, GetWindowsDevice) (
         AkInt32 in_index,           ///< Index of the device in the array.  -1 to get information on the default device.
         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. 
         IMMDevice** out_ppDevice,   ///< pointer to a pointer variable to which the method writes the address of the IMMDevice in question.
         AkAudioDeviceState uDeviceStateMask = AkDeviceState_All ///< Optional bitmask used to filter the device based on their state.
         );
  
 };
  
 #endif //_AK_WIN_SOUND_ENGINE_H_

AkUInt16

uint16_t AkUInt16

Unsigned 16-bit integer.

Definition: AkNumeralTypes.h:33

Definition of data structures for AkAudioObject.

Definition: AkWwiseSDKVersion.cs:31

AkThreadProperties

Definition: AkPlatformFuncs.h:45

AkPlatformInitSettings::uMaxSystemAudioObjects

AkUInt32 uMaxSystemAudioObjects

Dictates how many Microsoft Spatial Sound dynamic objects will be reserved by the System sink....

Definition: AkWinSoundEngine.h:57

AkPlatformInitSettings

Definition: AkAndroidSoundEngine.h:83

AK_EXTERNAPIFUNC

#define AK_EXTERNAPIFUNC(_type, _name)

Definition: AkSoundEngineExport.h:81

AK::GetDeviceID

AKSOUNDENGINE_API AkUInt32 GetDeviceID(IMMDevice *in_pDevice)

AK::GetWindowsDevice

AKSOUNDENGINE_API bool GetWindowsDevice(AkInt32 in_index, AkUInt32 &out_uDeviceID, IMMDevice **out_ppDevice, AkAudioDeviceState uDeviceStateMask=AkDeviceState_All)

AkPlatformInitSettings::threadMonitor

AkThreadProperties threadMonitor

Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL)....

Definition: AkAndroidSoundEngine.h:88

AkPlatformInitSettings::threadLEngine

AkThreadProperties threadLEngine

Lower engine threading properties.

Definition: AkAndroidSoundEngine.h:85

AkInt32

int32_t AkInt32

Signed 32-bit integer.

Definition: AkNumeralTypes.h:40