XAudio 2.9 可再发行版本的开发人员指南

项目
06/13/2023

XAudio 2.9 版本作为 NuGet 包提供。开发人员可以使用其应用重新分发此版本的 XAudio 2.9。这允许应用在未将 XAudio 2.9 作为操作系统映像一部分的旧版 Windows 上使用 XAudio 2.9。使用此可再发行组件优先于从 DirectX SDK 重新分发 XAudio 2.7，因为自 2010 年以来，XAudio 2.7 尚未更新。

请确保访问 DirectX 登陆页面，以获取 DirectX 开发人员的更多资源。

支持的平台

(Microsoft.XAudio2.Redist.*.nupkg) 的 XAudio 2.9 NuGet 包包含实现 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 文件还将与 XAUDIO2REDIST .DLL或.EXE链接。LIB 和 XAPOBASEREDIST。自由。

库 XAPOBASEREDIST。仅当你打算将自定义 XAudio 处理对象 (XAPO) 时才需要 LIB，如果它未使用，则可以将其从 Microsoft.XAudio2.Redist.targets 中删除。

还可以使用其他工具提取 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 会自动使用虚拟环绕声。建议测试在 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

XMA 格式仅在 Xbox One 上受支持。

首选 CPU 核心

可以指定哪个 CPU 核心 XAudio 2.9 应用于其音频处理线程。但是，通常首选让 XAudio 2.9 自行选择此值。为此，在调用 XAudio2Create 时将 XAudio2Processor 参数设置为 XAUDIO2_USE_DEFAULT_PROCESSOR。

XAudio 2.9 将在 Xbox One 上选择与电脑上不同的 CPU 核心。 IXAudio2Extension：：GetProcessor 方法可用于确定 XAudio2 选择了哪个 CPU 核心。

虚拟音频终结点

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 音频终结点，则 7.1 声道音频将通过 HDMI 连接按原样传输。

Windows 10使用将音频编码为用户选择的空间声音格式的集中式编码器添加了对空间音频的支持。 Windows 10附带了名为 Windows Sonic 的空间声音格式。其他格式（如Dolby Atmos for Headphones）可以从 Microsoft Store 下载。某些空间声音格式（如 Windows Sonic 和 Dolby Atmos for Headphones）设计用于立体声音频终结点。这些格式使用专有算法将环绕声折叠为立体声，以实现“虚拟”环绕音效。换句话说，即使只戴耳机，或在一对立体声扬声器上听时，侦听器也可以感知从 3D 空间中不同位置出现的声音。

可以使用 XAudio 2.9 附带的 X3DAudio API 实现类似的效果。 main区别在于，X3DAudio 要求应用开发人员显式为 3D 音频编程，而虚拟环绕声会自动应用于任何基于传统通道的声源。

在 Windows 10 1903 及更新版本上，使用 XAudio 2.9 的游戏将使用用户在音频终结点上启用的系统范围空间声音格式（如果有）。这意味着 XAudio 2.9 不会执行通常的环绕声到立体声的折叠。相反，环绕声信号将传送到空间声音编码器 (例如 Windows Sonic) ，以实现虚拟环绕音效。

CreateHrtfApo

CreateHrtfApo 函数仅适用于 Windows 10。它未在 XAudio 2.9 可再发行组件中实现。