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

# XDspSubmitCommandWithEnvelope

> XDspSubmitCommandWithEnvelope

# XDspSubmitCommandWithEnvelope

为给定的 XDSP 流向硬件队列提交一条命令。此 API 类似于向硬件提交一条命令的 XDspSubmitCommand，不同之处在于它还接受一个额外的参数 envelopeBuffer，该参数包含脉冲响应滤波器每个块的增益值。这些增益值在卷积过程中应用于脉冲响应。\
在需要使用包络时，应使用指向包络缓冲区的有效指针调用此 API。调用方负责确保包络缓冲区在不再使用之前始终保持有效。若要停止使用包络，应使用 XDspSubmitCommand，或使用 envelopeBuffer 为 nullptr 的 XDspSubmitCommandWithEnvelope。
此 API 只应用于为 XDspProcessType::Convolution 激活的流。

## 语法

```cpp theme={null}
HRESULT XDspSubmitCommandWithEnvelope(  
         XDspStreamHandle handle,  
         XDspCommand* command,  
         float* envelopeBuffer,
         uint32_t* commandSequence  
)  
```

### 参数

*handle*   \_In\_\
类型：[XDspStreamHandle](/reference/audio/xdspaudio/handles/xdspstreamhandle)

有效的 XDSP 流句柄。

*command*   \_In\_\
类型：[XDspCommand\*](/reference/audio/xdspaudio/structs/xdspcommand)

指向 [XDspCommand](/reference/audio/xdspaudio/structs/xdspcommand) 结构的指针。

*envelopeBuffer*   \_In\_\
类型：float\*

指向脉冲响应滤波器每个块的增益值的指针，这些增益值将在卷积过程中应用。\
此缓冲区必须是通过 [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 或 [XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/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。如果方法失败，则返回下列代码（部分列表）：

| 返回代码                          | 说明                                                                                      |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| E\_INVALIDARG                 | 一个或多个参数无效。                                                                              |
| XDSP\_E\_QUEUE\_FULL          | 如果流和硬件服务器达到了最大处理容量，此调用将返回 XDSP\_E\_QUEUE\_FULL。请等待硬件处理完成后再提交更多命令。                       |
| XDSP\_E\_DEVICE\_FATAL\_ERROR | 如果硬件服务器处于错误状态，**XDspSubmitCommandWithEnvelope** 将返回 XDSP\_E\_DEVICE\_FATAL\_ERROR 错误代码。 |

## 备注

此调用速度较快，因为它不会分配资源或处理数据，仅将命令发送到硬件服务器。

卷积过程有 *"n"* 个阶段，包络只能在第一阶段切换或启用/禁用。这意味着包络效果可能不会立即生效，可能会延迟几次提交。

若要禁用包络参数，应调用 **XDspSubmitCommand** 或使用 envelopeBuffer 为空的 **XDspSubmitCommandWithEnvelope**。

此调用还接受一个指向 `uint32_t` 的指针，用于返回命令序号值 *commandSequence*，以便日后跟踪命令结果何时就绪。此数字表示自会话开始以及在调用 [XDspActivate](/reference/audio/xdspaudio/functions/xdspactivate) 之后已成功提交的命令总数。第一条命令的数值为 1，之后每次 **XDspSubmitCommandWithEnvelope** 或 [XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand) 调用成功时该数值都会加 1。

如果硬件服务器处于错误状态，**XDspSubmitCommandWithEnvelope** 将返回 XDSP\_E\_DEVICE\_FATAL\_ERROR 错误代码。此时，无法为处于失败状态的 XDSP 流提交更多命令。该流对应的 [XDspStatus](/reference/audio/xdspaudio/structs/xdspstatus) 也将显示相同的错误。受影响的 XDSP 流应通过检查 [XDspStatus](/reference/audio/xdspaudio/structs/xdspstatus) 等待所有已提交的命令由硬件处理完毕，然后在所有命令处理完成后使用 [XDspDeactivate](/reference/audio/xdspaudio/functions/xdspdeactivate) 将其停用。其他 XDSP 流不会受到影响，硬件将继续处理它们的命令。

## 要求

**头文件：** XDspAudio.h

**库：** Chad.lib

**支持的平台：** XBOX Series X|S

## 概念文档

* [XDSP 包络处理概述](/build/console-features/audio/overviews/xdsp-overview-enveloping)
* [使用 XDSP API 进行带包络的单流卷积概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)
* [XDSP 概述](/build/console-features/audio/overviews/xdsp-overview)

## 另请参阅

[XDSP](/reference/audio/xdspaudio/xdspaudio_members)\
[XdspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand)\
[XDSP Errors](/reference/audio/xdspaudio/enums/xdsperrors)\
[使用 XDSP API 进行单流卷积概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)\
[使用 XDSP API 进行带包络的单流卷积概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)
[使用 XDSP API 进行单流 FFT/IFFT 概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-fft-ifft)


## Related topics

- [XDspSubmitCommand](/zh-CN/reference/audio/xdspaudio/functions/xdspsubmitcommand.md)
- [XDSP 包络概述](/zh-CN/build/console-features/audio/overviews/xdsp-overview-enveloping.md)
- [XDSP 概述](/zh-CN/build/console-features/audio/overviews/xdsp-overview.md)
- [使用 XDSP API 进行带包络的单流卷积](/zh-CN/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope.md)
- [XDSP audio](/zh-CN/reference/audio/xdspaudio/xdspaudio_members.md)