XDspSubmitCommandWithEnvelope
为给定的 XDSP 流向硬件队列提交一条命令。此 API 类似于向硬件提交一条命令的 XDspSubmitCommand，不同之处在于它还接受一个额外的参数 envelopeBuffer，该参数包含脉冲响应滤波器每个块的增益值。这些增益值在卷积过程中应用于脉冲响应。在需要使用包络时，应使用指向包络缓冲区的有效指针调用此 API。调用方负责确保包络缓冲区在不再使用之前始终保持有效。若要停止使用包络，应使用 XDspSubmitCommand，或使用 envelopeBuffer 为 nullptr 的 XDspSubmitCommandWithEnvelope。 此 API 只应用于为 XDspProcessType::Convolution 激活的流。
语法
参数
handle _In_类型：XDspStreamHandle 有效的 XDSP 流句柄。 command _In_
类型：XDspCommand* 指向 XDspCommand 结构的指针。 envelopeBuffer _In_
类型：float* 指向脉冲响应滤波器每个块的增益值的指针，这些增益值将在卷积过程中应用。
此缓冲区必须是通过 XDspConnect 或 XDspConnectWithMaximumStreamLimit 注册的内存的一部分，并且应为 16 字节对齐。此缓冲区由硬件使用，在使用此缓冲区的所有命令完成且已获取响应之前，不能修改或释放此缓冲区。 包络缓冲区中的增益值数量至少应为脉冲响应滤波器中的块数，计算方式如下：
uint32_t IRLengthInComplexValues = XDspActivationParameters::impulseResponseLengthInFloats/2;
uint32_t IRLengthInBlocks = IRLengthInComplexValues/ XDspActivationParameters::blockFrameCount;
uint32_t envelopeSize = ((IRLengthInBlocks * sizeof(float) + 15) & ~(0xF)) / sizeof(float); 此缓冲区遵循脉冲响应的大小。对于立体声脉冲响应，整个左声道的增益值后紧接整个右声道的增益值，方式与左声道脉冲响应后紧接右声道脉冲响应相同。 对于单声道脉冲响应，相同的增益值同时应用于立体声输入信号的左右两个声道。对于单声道脉冲响应滤波器，此缓冲区的最小大小应为 8 个 float 值；对于立体声脉冲响应滤波器，应为 16 个 float 值。 commandSequence _Out_
类型：uint32_t* 指向
uint32_t 的指针，用于返回命令序号值。有关其他详细信息，请参阅备注部分。
返回值
类型：HRESULT 如果方法成功，则返回 S_OK。如果方法失败，则返回下列代码（部分列表）：备注
此调用速度较快，因为它不会分配资源或处理数据，仅将命令发送到硬件服务器。 卷积过程有 “n” 个阶段，包络只能在第一阶段切换或启用/禁用。这意味着包络效果可能不会立即生效，可能会延迟几次提交。 若要禁用包络参数，应调用 XDspSubmitCommand 或使用 envelopeBuffer 为空的 XDspSubmitCommandWithEnvelope。 此调用还接受一个指向uint32_t 的指针，用于返回命令序号值 commandSequence，以便日后跟踪命令结果何时就绪。此数字表示自会话开始以及在调用 XDspActivate 之后已成功提交的命令总数。第一条命令的数值为 1，之后每次 XDspSubmitCommandWithEnvelope 或 XDspSubmitCommand 调用成功时该数值都会加 1。
如果硬件服务器处于错误状态，XDspSubmitCommandWithEnvelope 将返回 XDSP_E_DEVICE_FATAL_ERROR 错误代码。此时，无法为处于失败状态的 XDSP 流提交更多命令。该流对应的 XDspStatus 也将显示相同的错误。受影响的 XDSP 流应通过检查 XDspStatus 等待所有已提交的命令由硬件处理完毕，然后在所有命令处理完成后使用 XDspDeactivate 将其停用。其他 XDSP 流不会受到影响，硬件将继续处理它们的命令。
要求
头文件： XDspAudio.h 库： Chad.lib 支持的平台： XBOX Series X|S概念文档
另请参阅
XDSPXdspSubmitCommand
XDSP Errors
使用 XDSP API 进行单流卷积概述
使用 XDSP API 进行带包络的单流卷积概述 使用 XDSP API 进行单流 FFT/IFFT 概述