> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XDSP 概述

> 使用 XDSP API 在 XBOX Series X|S 主机上实现硬件加速的卷积混响、FFT 和 IFFT，以及脉冲响应包络处理。

本主题概述了 [XDSP API](/reference/audio/xdspaudio/xdspaudio_members)。XDSP 让游戏能够利用 XBOX Series X|S 世代主机上的硬件加速卷积混响 (Hardware Accelerated Convolution Reverb) 功能。当前实现能够实时处理累计 80 秒的脉冲响应。例如，可同时实时处理 40 条各 2 秒脉冲响应的流。

### 2022 年 10 月版本新增

* 新增两个 API：[XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit) 与 [XDspSubmitCommandWithEnvelope](/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope)。当可激活的最大流数少于 256 时，**XDspConnectWithMaximumStreamLimit** 会在内部占用更少的内存；相比之下，[XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 会按 256 条流预留内存，因此占用更多。
  **XDspSubmitCommandWithEnvelope** 支持对脉冲响应滤波器进行包络处理。详见 [使用 XDSP API 的包络概述](/build/console-features/audio/overviews/xdsp-overview-enveloping)。

### 版本特性

* 对于卷积，支持的块大小为 512 和 1024 帧。使用 1024 帧的块大小性能更好。
* 对于 FFT/IFFT，支持的块大小为 512、1024 和 2048 帧。
* 卷积支持单声道、立体声以及立体声去交错模式，并可搭配单声道或立体声脉冲响应。
* [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 或 [XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit) 调用会建立与硬件的连接并返回一个 XDspClientHandle。任意时刻最多只能有 8 个处于活动状态的连接。
* [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 支持的 *aggregateImpulseResponseInSeconds* 最大值为 128。这也是所有 XDspConnect 调用累计的上限。如果某次 XDspConnect 调用将 aggregateImpulseResponseInSeconds 设为 128，则不能再有任何 aggregateImpulseResponseInSeconds 大于 0 的 XDspConnect 调用。要激活可用于卷积处理的流，aggregateImpulseResponseInSeconds 必须大于 0。
* 对于 [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 返回的每个 [XDspClientHandle](/reference/audio/xdspaudio/handles/xdspclienthandle)，通过 [XDspActivate](/reference/audio/xdspaudio/functions/xdspactivate) 最多可激活 256 个流。对于 [XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit) 返回的每个 [XDspClientHandle](/reference/audio/xdspaudio/handles/xdspclienthandle)，最多可以激活 *maximumStreamCount* 个流，其中 *maximumStreamCount* 就是调用 **XDspConnectWithMaximumStreamLimit** 时使用的流数。这些流可以是任意 [XDspProcessType](/reference/audio/xdspaudio/enums/xdspprocesstype)。
* 使用立体声输入时，支持的累计脉冲响应最大值降为 64 秒。
* 传给 API 的所有缓冲区都必须按 16 字节对齐。缓冲区未按 16 字节对齐时，硬件可能发生错误并重置。硬件崩溃或挂起时，[XDspStatus.result](/reference/audio/xdspaudio/structs/xdspstatus) 会指示 XDSP\_E\_DEVICE\_FATAL\_ERROR。
* **脉冲响应应位于频域中。我们提供了一个工具用于将时域脉冲响应转换为频域。** 请从 [https://aka.ms/gdkdl](https://aka.ms/gdkdl) 下载。
* 脉冲响应转换工具现已支持压缩功能，允许你以损失一定质量为代价获得更高性能。详见 [XDSP 脉冲响应压缩概述](/build/console-features/audio/overviews/xdsp-overview-ir-reduction)。
* 对 [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 调用的延迟做了改进。

### 已知问题

* 在 FFT/IFFT 处理中，[XDspActivationOptions](/reference/audio/xdspaudio/enums/xdspactivationoptions) 中的 "EnablePolarFormat" 选项相较默认的笛卡尔格式耗时明显更长；后者性能更好。

### 最佳实践

* 即使硬件出现故障，为每条提交到硬件的命令都会返回一个响应。调用者在调用 [XDspDeactivate](/reference/audio/xdspaudio/functions/xdspdeactivate) 停用流之前，应等待硬件处理完所有命令。[XDspStatus.lastProcessedCommandSequence](/reference/audio/xdspaudio/structs/xdspstatus) 显示硬件为该流处理的最后一条命令的序列号。其他 XDSP 流不会受影响，硬件会继续处理它们的命令。
* 传给 [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 调用的 *"baseBuffer"* 在所有流都通过 [XDspDeactivate](/reference/audio/xdspaudio/functions/xdspdeactivate) 停用且 [XDspDisconnect](/reference/audio/xdspaudio/functions/xdspdisconnect) 成功之前不应释放。
* 每条流都有内部队列上限，达到该上限时 [XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand) 会返回 XDSP\_E\_QUEUE\_FULL。遇到此错误时，请给硬件足够时间处理该流的命令后再提交更多命令。可通过 [XDspStatus.lastProcessedCommandSequence](/reference/audio/xdspaudio/structs/xdspstatus) 查看硬件为该流处理的最后一条命令。
* 卷积使用 1024 块大小时性能优于 512 块大小。
* 卷积算法在处理连续命令时并不均匀，即并非所有块耗时相同，有些块可能耗时更长。

### 游戏的暂停与恢复

游戏必须能够暂停和恢复，例如当用户将其切换到 Constrained 模式时。挂起处理器被调用时，只需停止向硬件提交 XDSP 命令即可。已提交的命令会正常处理，XDspStatus 会相应更新。

### 示例

* 可从 [https://aka.ms/gdkdl](https://aka.ms/gdkdl) 或 ATG 示例下载。
  可查阅示例走查：[单流卷积混响](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution) 和 [单流 FFT IFFT](/build/console-features/audio/overviews/xdsp-overview-single-stream-fft-ifft)。
* GDK 下载门户 [https://aka.ms/gdkdl](https://aka.ms/gdkdl) 中还包含一个 XDSP 示例，演示了如何使用硬件加速器将时域脉冲响应转换为频域。此示例的输出与随 GDK 安装的 Impulse Response Transform 工具完全一致，展示了如何利用硬件加速在飞行中转换脉冲响应，供 XDSP API 使用。

### 联系

如果你对该功能有任何问题或疑问，请发送邮件至 [AnaAud@microsoft.com](mailto:AnaAud@microsoft.com) 或使用在线论坛。

## 参考 API 文档

* [Xdspaudio (API 内容)](/reference/audio/xdspaudio/xdspaudio_members)
  * Functions
    * [XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit)
    * [XDspSubmitCommandWithEnvelope](/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope)
    * [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect)
    * [XDspActivate](/reference/audio/xdspaudio/functions/xdspactivate)
    * [XDspDeactivate](/reference/audio/xdspaudio/functions/xdspdeactivate)
    * [XDspDisconnect](/reference/audio/xdspaudio/functions/xdspdisconnect)
    * [XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand)
  * Structures
    * [xdspstatus](/reference/audio/xdspaudio/structs/xdspstatus)


## Related topics

- [XDSP audio](/zh-CN/reference/audio/xdspaudio/xdspaudio_members.md)
- [XDSP 包络概述](/zh-CN/build/console-features/audio/overviews/xdsp-overview-enveloping.md)
- [XDSP 脉冲响应压缩概述](/zh-CN/build/console-features/audio/overviews/xdsp-overview-ir-reduction.md)
- [使用 XDSP API 进行单流卷积概述](/zh-CN/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution.md)
- [使用 XDSP API 进行带包络的单流卷积](/zh-CN/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope.md)