> ## 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.

# IAcpHal::SubmitCommand

> IAcpHal::SubmitCommand

# IAcpHal::SubmitCommand

向 ACP 提交命令。

## 语法

```cpp theme={null}
HRESULT SubmitCommand(  
         ACP_COMMAND_TYPE command,  
         UINT64 commandId,  
         UINT32 audioFrame,  
         const void* data= nullptr,  
         APU_ADDRESS notification= 0  
)  
```

### 参数

*command*   \
类型:[ACP\_COMMAND\_TYPE](/reference/audio/acphal/enums/acp_command_type)

命令。请参阅 [ACP\_COMMAND\_TYPE](/reference/audio/acphal/enums/acp_command_type) 枚举。

*commandId*   \
类型:UINT64

命令的可选任意标识符。此 ID 将随特定消息一起返回。之所以采用 UINT64,是为了支持将指针作为命令 ID 传递。

*audioFrame*   \
类型:UINT32

如果指定了某个音频帧编号,则命令将在该音频帧的开始处理,除非该帧已经过去,在这种情况下将从下一个音频帧开始处理。此参数还有两个特殊值:

* `ACP_SUBMIT_PROCESS_COMMAND_ASAP` 指示 ACP 尽快处理该命令——如果可能,在当前音频帧就处理。
* `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` 指示 ACP 在下一个音频帧的开始处理该命令。如果该命令是要更新上下文,则会在流程图处理开始之前更新该上下文。这确实会延迟流程图处理的开始时间,可能导致语音数(voice count)较高的流程图丢弃部分语音。

*data*   \_In\_opt\_\
类型:void\*

与命令关联的可选数据。大多数命令都需要一个数据结构体。

*notification*   \_In\_opt\_\
类型:APU\_ADDRESS

一个 UINT32 元素的可选物理地址,当命令完成时,该元素将被设置为非零值。指向对应虚拟地址的指针应声明为 **volatile**。这类似于命令完成消息,不同之处在于并不需要通过消息来告知命令的完成。当 XAudio2 向 ACP 提交命令时,它会使用此通知指针来检查命令是否已完成。

### 返回值

类型:HRESULT

如果方法成功,则返回 S\_OK。如果方法失败,则返回以下代码之一(部分列表):

| 返回代码                | 描述         |
| ------------------- | ---------- |
| E\_INVALIDARG       | 一个或多个参数无效。 |
| ACP\_E\_QUEUE\_FULL | 命令队列已满。    |

## 备注

这是允许游戏与音频控制处理器(Audio Control Processor,ACP)、可伸缩硬件音频处理引擎(Scalable Hardware Audio Processing Engine,SHAPE)和 XMA 通信的唯一 API。

使用 `SubmitCommand` 方法提交的数据的生命周期是可变的。作为输入传入的结构体指针仅在 API 调用期间被引用;这意味着开发者可以安全地使用局部变量。如果命令中包含指向另一块数据的指针,则该数据不会被复制,必须保持存在,直到 ACP 处理完该命令为止。这样做是为了尽量减少内部需要复制的数据量。如果对附加命令数据的生命周期管理有顾虑,应用程序可以注册 *command completed* 消息,以便在命令中的附加数据不再被引用时立即收到通知。

如果游戏提交一个或多个设置了 `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` 标志或指定了特定音频帧编号的命令,那么所有这些命令都将在指定音频帧的开始处理,并且在进行任何其他处理之前处理。

请注意,由于所有 ACP 命令在主 CPU 上都是异步的,调用 `IAcpHal::SubmitCommand` 不会阻塞处理。

游戏使用通知的最有效方法如下:

1. 使用 [ApuCreateHeap](/reference/audio/apu/functions/apucreateheap) 创建一个 APU 堆,其中非缓存大小要足够容纳游戏所需的所有上下文以及将要使用的所有通知。如果在任何其他 ACP 或相关方法之前未调用此方法,则会分配一个默认堆。

2. 分配一个非缓存 UINT32 数组,其大小等于所需通知的数量:即每个音频帧将发出的上下文更新总数。请注意,每次分配一个通知的效率非常低。

## 要求

**头文件:** acphal.h

**支持的平台:** XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[ACP\_COMMAND\_TYPE](/reference/audio/acphal/enums/acp_command_type)
[AcpHal](/reference/audio/acphal/acphal_members)


## Related topics

- [IAcpHal](/zh-CN/reference/audio/acphal/interfaces/IAcpHal/iacphal.md)
- [SHAPE 音频流程图构建最佳实践](/zh-CN/build/console-features/audio/overviews/best-practices-audio-flowgraph-construction.md)
- [IAcpHal::Connect](/zh-CN/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_connect.md)
- [ACP_COMMAND_TYPE](/zh-CN/reference/audio/acphal/enums/acp_command_type.md)
- [ACP_COMMAND_UPDATE_CONTEXTS](/zh-CN/reference/audio/acphal/structs/acp_command_update_contexts.md)