Skip to main content
在本主题中,我们将通过 Microsoft Game Development Kit (GDK) 附带的一个示例,逐步介绍在 XBOX Series X 设备上使用 Opus 硬件加速解码时的预期代码流程。该示例名为 DecodeOne.cpp,涵盖了一个客户端下的单流解码场景。

音频硬件连接与启动

解码从通过 XApuConnect 建立与硬件加速单元的连接开始。调用者使用 XApuConnectInputParameters 设置连接的要求,具体包括:
  1. 处理类型(此处为 XApuProcessType::DecodeOpus)。
  2. 流的数量(此处为 1)。
  3. 用于传入和取出输入/输出数据所需的总内存。这里 MaxInputBufferLength 为 1024(必须大于或等于流中最大的 Opus 数据包,且必须是 16 的倍数);MaxOutputBufferLength 为 7680,即 48 K 下 20 ms 的数据,960 × 2 × sizeof(float) = 7680,输出也需要是 16 的倍数。
如果该调用成功,XApuConnectOutputParameters::baseData 参数将指向操作系统分配的一块内存,硬件加速单元可以直接访问,无需额外的整理或复制。调用者应使用该内存来传入输入数据并取出输出数据。以下是一个简单内存管理器示例,可用于设置 XApuConnectInputParameters 并把 XApuConnectOutputParameters::baseData 划分为两个指针:一个用于输入数据,另一个用于输出数据。
以下是建立连接第一步的代码示例。

流的激活与停用

在与设备建立连接后,调用者应发送一个流激活命令来启用一个解码引擎。调用者必须指定流索引和声道数。只允许单声道或立体声流。 调用者应调用 XApuDequeueResult 获取激活结果。因为在本示例中 XApuConnectInputParameters::maxQueuedCommandsPerStream 设置为 1,所以调用者必须等到每个结果返回后再提交下一个命令。这包括 ActivateProcessDeactivate 命令(详情见 XApuCommandType)。 以下是激活一个流的代码。
激活结果收到后,调用者即可开始提交 Opus 数据包进行解码。这应通过 XApuCommandType::Process 命令完成。对于每个 Process 命令,调用者必须完成以下工作:
  1. 用恰好一个 Opus 数据包填充输入缓冲区。
  2. 指定数据包的长度。
  3. 提供输出缓冲区的位置,音频硬件加速单元将把解码数据写入其中。
  4. 指定输出缓冲区的最大长度。
此外,调用者必须指定 streamIndexframeCount 值。如果需要把所有解码数据都拷贝到输出缓冲区,则可将 frameCount 值设为大于或等于数据包中编码帧数的任意值(例如,对于一个 20 ms 的数据包,frameCount 可以在 960 到 0xFFFFFFFF 之间取任意值)。
接下来,应调用 XApuDequeueResult 获取该数据包的解码输出。成功取回 XApuResult 后,输出数据会存放在 result.outputData 中。处理完后,应通过新的一次 XApuEnqueueCommand 调用(携带 XApuCommandType::Process 命令)提交下一个数据包进行解码。
当流中所有数据包都解码完成后,应提交一个 XApuCommandType::Deactivate 命令。

终止

收到停用结果后,调用者必须调用 XApuDisconnect 与音频硬件加速单元断开连接,以释放所有已分配的资源。
最后修改于 2026年8月24日