IAcpHal::SubmitCommand
向 ACP 提交命令。语法
参数
command类型:ACP_COMMAND_TYPE 命令。请参阅 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)较高的流程图丢弃部分语音。
类型:void* 与命令关联的可选数据。大多数命令都需要一个数据结构体。 notification _In_opt_
类型:APU_ADDRESS 一个 UINT32 元素的可选物理地址,当命令完成时,该元素将被设置为非零值。指向对应虚拟地址的指针应声明为 volatile。这类似于命令完成消息,不同之处在于并不需要通过消息来告知命令的完成。当 XAudio2 向 ACP 提交命令时,它会使用此通知指针来检查命令是否已完成。
返回值
类型:HRESULT 如果方法成功,则返回 S_OK。如果方法失败,则返回以下代码之一(部分列表):备注
这是允许游戏与音频控制处理器(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 不会阻塞处理。
游戏使用通知的最有效方法如下:
- 使用 ApuCreateHeap 创建一个 APU 堆,其中非缓存大小要足够容纳游戏所需的所有上下文以及将要使用的所有通知。如果在任何其他 ACP 或相关方法之前未调用此方法,则会分配一个默认堆。
- 分配一个非缓存 UINT32 数组,其大小等于所需通知的数量:即每个音频帧将发出的上下文更新总数。请注意,每次分配一个通知的效率非常低。