XAudio 2.9 可轉散發版本的開發人員指南

發行項
06/12/2023

XAudio 2.9 版本以 NuGet 套件的形式提供。開發人員可以使用其應用程式來轉散發此版本的 XAudio 2.9。這可讓應用程式在舊版 Windows 上使用 XAudio 2.9，但不包含 XAudio 2.9 做為作業系統映射的一部分。使用這個可轉散發套件是慣用的，而不是從 DirectX SDK 轉散發 XAudio 2.7，因為 XAudio 2.7 自 2010 年之後尚未更新。

請確定您流覽 DirectX 登陸頁面，以取得 DirectX 開發人員更多資源。

支援的平台

XAudio 2.9 NuGet 套件 (Microsoft.XAudio2.Redist.*.nupkg) 包含實作 XAudio 2.9 API 的 32 位和 64 位版本的 DLL。 DLL 稱為 XAUDIO2_9REDIST.DLL。此 DLL 適用于 Windows 7 SP1、Windows 8、Windows 8.1和Windows 10。

在Windows 10系統上使用 DLL 時，它會檢查屬於作業系統一部分之XAUDIO2_9.DLL的版本號碼，如果作業系統較新，則會將所有 API 呼叫委派給作業系統中的XAUDIO2_9.DLL。這可確保應用程式一律使用目前平臺上可用的最新版 XAudio 2.9。

DLL 不適用於 Xbox One。如果在 Xbox One 上使用，DLL 一律會將所有 API 呼叫委派給 Xbox One 作業系統中的XAUDIO2_9.DLL。

DLL 不適用於 UWP 應用程式。 UWP 應用程式應該使用屬於作業系統的XAUDIO2_9.DLL。

安裝 NuGet 封裝

安裝 NuGet 套件最簡單的方式是使用 Microsoft Visual Studio 中的 NuGet 套件管理員。如果您這樣做，Visual Studio 專案檔將會自動更新，以包含 Microsoft.XAudio2.Redist.targets。 .targets檔案會將包含 XAudio2 標頭檔之 Include 資料夾新增至專案包含路徑的集合。 .targets檔案也會讓您的.DLL或.EXE與 XAUDIO2REDIST 連結。LIB 和 XAPOBASEREDIST。自由。

程式庫 XAPOBASEREDIST。只有在您想要在 XAPO (XAPO) 內實作自訂 XAudio 處理物件，而且若未使用，您才能從 Microsoft.XAudio2.Redist.targets 中移除 LIB。

您也可以使用其他工具來擷取 NuGet 套件的內容，或甚至將副檔名重新命名為.zip，並使用任何 ZIP 擷取器工具解壓縮檔案。

另外還有一個 xaudio2redist 埠可供 VC++ 套件管理員使用。

編譯您的應用程式

選擇要包含的標頭

XAudio 2.9 NuGet 套件包含Windows 10 SDK 中包含的相同 XAudio2 標頭檔。不過，標頭檔已進行一些調整，以確保您可以在明確以所有支援的平臺為目標時使用它們，包括舊版 Windows。

如果您使用 Microsoft Visual Studio 中的 NuGet 套件管理員安裝 NuGet 套件，則標頭檔的路徑會放在 Windows SDK 標頭檔的路徑前面。這表示如果您的專案中的程式碼包含 XAUDIO2。H 標頭，它會從 NuGet 套件中挑選跨平臺標頭。這通常是所需的行為。

如果手動將包含標頭的路徑新增至專案，您應該小心，因為以錯誤順序指定它們可能會導致 OS 版本特定的 XAUDIO2。要包含在 Windows SDK 中的 H，而不是 XAUDIO2.H 的跨平臺版本。

為了讓標頭包含較不容易出錯，NuGet 套件包含每個標頭的版本，並附加「REDIST」。例如，除了 XAUDIO2 之外。H，NuGet 套件也包含 XAUDIO2REDIST.H。如果您偏好，您的程式碼可以直接包含 XAUDIO2REDIST。H 可消除使用哪個標頭檔的任何模棱兩可。包含 -REDIST 時。標頭檔 H 版本，專案檔中列出包含檔案目錄的順序並不重要。

請注意，如果您的應用程式也正在針對 Xbox One 進行編譯，您應該繼續包含 XAUDIO2。針對 Xbox One 進行編譯時，H，因為某些 Xbox One 特定 API 會從 XAUDIO2REDIST.H 中排除。此 NuGet 套件不適用於 Xbox One。

載入 DLL

我們建議您將應用程式與 XAUDIO2REDIST 連結。LIB 並安裝在與應用程式可執行檔相同的資料夾中XAUDIO2_9REDIST.DLL。這會導致在可執行檔啟動時立即載入XAUDIO2_9REDIST.DLL。不過，如果您想要的話，您可以使用 LoadLibraryEx 和 GetProcAddress 視需要載入XAUDIO2_9REDIST.DLL。如果您的應用程式不一定需要使用 XAudio2 API，這是很好的解決方案。但是，如果您這樣做，您應該保留載入XAUDIO2_9REDIST.DLL，直到應用程式結束為止，因為嘗試卸載 DLL 可能會導致當機，如果背景執行緒仍在 DLL 中執行程式碼。

不同于較舊的 XAudio 2.7，無法使用 CoCreateInstance 載入 DLL。

驗證 DLL 簽章

XAUDIO2_9REDIST.DLL二進位檔是由 Microsoft 使用 SHA-2 簽章簽署。任何嘗試驗證簽章的程式碼，例如遊戲的反速查模組，因此必須支援 SHA-2。請注意，Windows 7 SP1 原本不支援 SHA-2，而且需要更新才能新增該功能。更新可用為 KB4474419。

測試

較新版本Windows 10的空間音效

從 Windows 10 1903 更新開始，如果滿足特定條件，XAudio 2.9 會自動使用虛擬環繞音效。建議您測試在 1903 Windows 10 1903 (或更新版本) 上產生多頻道音效的遊戲，以確認遊戲音效如預期般。

啟用空間音效

使用者可以在 Windows 系統匣中以滑鼠右鍵按一下喇叭圖示，以啟用空間音效格式。

如果使用 XAudio2 API 的程式被 Windows 遊戲列辨識為遊戲，則 XAudio 2.9 只會使用使用者的選取空間音效格式。在開發期間，程式可能尚未由遊戲列辨識為遊戲。若要變更此動作，請使用 Win+G 鍵盤的快捷方式，在遊戲執行時啟動遊戲列。然後按一下 [設定] 圖示，然後核取指出「請記住這是遊戲」的核取方塊。

退出宣告空間音效

在IXAudio2：：CreateMasteringVoice中指定AUDIO_STREAM_CATEGORY參數的特定值，即可退出宣告使用 XAudio2 使用空間音效編碼器。

這些類別已啟用空間音效：

AudioCategory_ForegroundOnlyMedia
AudioCategory_GameEffects
AudioCategory_GameMedia
AudioCategory_Movie
AudioCategory_Media

如果指定下列任何類別，則不會啟用空間音效：

AudioCategory_Other
AudioCategory_Communications
AudioCategory_Alerts
AudioCategory_SoundEffects
AudioCategory_GameChat
AudioCategory_Speech

錯誤處理

請務必測試遊戲可以處理音訊裝置中的變更，例如，當耳機插入或取消叢集時。這應該使用只支援 44.1 kHz 取樣率的耳機進行測試。許多低階 USB 耳機和藍牙頭戴式裝置僅支援 44.1 kHz。即使使用虛擬音訊端點功能，48 kHz 取樣率與 44.1 kHz 取樣率之間的轉換仍會造成錯誤。如果耳機也支援 48 kHz，則不會發生此錯誤。請注意，Windows 7 SP1 上無法使用虛擬音訊端點功能。

當 XAudio 2.9 無法自動從音訊端點中的變更復原時，傳回的錯誤碼會XAUDIO2_E_DEVICE_INVALIDATED。不過，我們建議應用程式不會將相依性硬式編碼為具有特定值的錯誤碼。

若要收到錯誤通知，應用程式應該實作 IXAudio2EngineCallback 介面，並叫用 IXAudio2：：RegisterForCallbacks 方法來提供該介面的指標。如果播放期間發生錯誤，則會由 XAudio2 API 叫用 IXAudio2EngineCallback：：OnCriticalError 的應用程式實作。

請注意，如果音訊管線暫停，則不一定叫用 IXAudio2EngineCallback：：OnCriticalError 。例如，如果使用者最小化應用程式，或因為任何原因而暫停應用程式，音訊播放可能會暫停。如果音訊裝置在這段期間發生變更，只有在應用程式叫用 IXAudio2：：StartEngine 和/或叫用 IXAudio2SourceVoice：：Start時，才會傳回錯誤。如果可以使用您的應用程式暫停播放，您應該測試在播放暫停時變更音訊裝置，以確認應用程式仍然可以從這種情況復原。

與 XAudio 2.7 相比，XAudio 2.9 API 的差異

本節提供 XAudio 2.7 與 XAudio 2.9 可轉散發版本之間的一些 API 差異摘要。

支援的格式

XAudio 2.9 支援電腦上的這些輸入格式：

線性 16 位 PCM
線性 32 位浮點數 PCM
16 位 ADPCM
xWMA

只有 Xbox One 才支援 XMA 格式。

慣用 CPU 核心

您可以指定哪個 CPU 核心 XAudio 2.9 應該用於其音訊處理執行緒。不過，通常最好讓 XAudio 2.9 自行選擇此值。這是藉由將XAudio2Create呼叫中的XAudio2Processor參數設定為 XAUDIO2_USE_DEFAULT_PROCESSOR 來完成。

XAudio 2.9 會在 Xbox One 上選擇不同于電腦上的 CPU 核心。 IXAudio2Extension：：GetProcessor 方法可用來判斷哪些 CPU 核心 XAudio2 已選擇。

虛擬音訊端點

XAudio 2.9 預設會在 Windows 8 或更新版本上執行時，使用虛擬音訊端點。這表示，如果使用 XAudio 2.9 時預設音訊端點變更，它將會嘗試自動切換至新的音訊端點。當預設音訊端點是透過 USB 連線的一對耳機，然後使用者卸載耳機時，就會發生此情況的範例。這會導致喇叭成為新的預設音訊端點。

如果應用程式在叫用 IXAudio2：：CreateMasteringVoice時指定特定的音訊格式，XAudio 2.9 可能無法執行此參數。例如，如果應用程式指定主控語音應該使用 48 kHz 取樣率，而新的音訊裝置僅支援 44.1 kHz，則自動切換將會失敗，而 XAudio 2.9 會回報 XAUDIO2_E_DEVICE_INVALIDATED 錯誤。

應用程式可以透過將 XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT 旗標傳遞至 IXAudio2：：CreateMasteringVoice，選擇不使用虛擬音訊端點。

Windows 7 SP1 上無法使用虛擬音訊端點。 XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT旗標不會影響 Windows 7 SP1。

音訊類別

應用程式應該為其音訊串流指定類別。叫用 IXAudio2：：CreateMasteringVoice 方法時，會從 AudioCategory 列舉提供值來完成。例如，AudioCategory_GameEffects。音訊類別可能會影響 Windows 處理音效的方式，或它如何代表音量控制台中的音訊資料流程。音訊類別也會影響是否自動啟用虛擬環繞音效。

音訊處理量子的持續時間

在大部分電腦上，XAudio 2.9 會以 10 毫秒的區塊處理音訊。這稱為處理量子。不過，此量子的持續時間可能與某些硬體上的 10 毫秒不同。需要知道確切量子的應用程式可以叫用 IXAudio2Extension：：GetProcessingQuantum 方法來擷取值。

空間音效和虛擬環繞

從 Windows 10 1903 更新開始，如果滿足某些條件，XAudio 2.9 會自動使用虛擬環繞音效。建議您測試在 Windows 10 1903 (或更新版本) 上產生多聲道音效的遊戲，以確認遊戲如預期般音效。如需如何測試此功能的討論，請參閱測試空間音效一節。

一般而言，XAudio 2.9 會向下折迭任何多頻道音訊，以符合音訊端點支援的「實體」音訊通道數目。例如，如果遊戲提供 7.1 通道音訊來源，但音效是在耳機上播放，XAudio 2.9 會使用業界標準折迭矩陣，將 7.1 通道音訊折迭成身歷聲。如果電腦連線到 HDMI 音訊端點，則會透過 HDMI 連線依原狀傳輸 7.1 通道音訊。

Windows 10新增空間音訊的支援，使用將音訊編碼為使用者選取空間音效格式的集中式編碼器。 Windows 10隨附于稱為 Windows Sonic 的空間音效格式。您可以從 Microsoft Store 下載其他格式，例如Dolby Atmos for Headphones。某些空間音效格式，例如 Windows Sonic 和 Dolby Atmos for Headphones，設計成用於身歷聲音訊端點。這些格式會使用達到「虛擬」環繞音效的專屬演算法，將環繞音效折迭成身歷聲。換句話說，接聽程式可以在 3D 空間中察覺從不同位置出現的音效，即使只有戴上耳機，或在單一組身歷聲喇叭上接聽時也一樣。

您可以使用 XAudio 2.9 隨附的 X3DAudio API 來達成類似的效果。主要差異在於 X3DAudio 需要應用程式開發人員明確針對 3D 音訊進行程式設計，而虛擬環繞音效會自動套用至任何以通道為基礎的聲道來源。

在 Windows 10 1903 和更新版本上，使用 XAudio 2.9 的遊戲將會使用使用者在音訊端點上啟用的系統範圍空間音效格式。這表示 XAudio 2.9 不會對身歷聲執行一般環繞音效的折迭。相反地，環繞音效訊號會傳遞至空間音效編碼器 (例如 Windows Sonic) ，以達到虛擬環繞音效。

CreateHrtfApo

CreateHrtfApo函式僅適用于 Windows 10。它不會在 XAudio 2.9 可轉散發套件中實作。

Share via